diff --git a/doc/src/Developer_notes.rst b/doc/src/Developer_notes.rst index a562ee26e4..2d136055a4 100644 --- a/doc/src/Developer_notes.rst +++ b/doc/src/Developer_notes.rst @@ -268,12 +268,14 @@ There are multiple "signatures" that can be called: command would be the last line, but is unrelated to the error. - ``Error::all(FLERR, idx, "Error message")``: this is for argument - parsing where "idx" is the index of the argument for a LAMMPS command - that is causing the failure (use -1 for the command itself). The - output will then not only be the last input line, but also the command - and arguments *after* they have been pre-processed and split into - individual arguments and a textual indicator pointing to the specific - word that failed. + parsing where "idx" is the index (starting at 0) of the argument for a + LAMMPS command that is causing the failure (use -1 for the command + itself). The output may also include the last input line *before* and + *after*, if they differ due to substituting variables. A textual + indicator is pointing to the specific word that failed. Using the + constant ``Error::NOPOINTER`` in place of the *idx* argument will + suppress the marker and then the behavior is like the *idx* argument + is not provided. FLERR is a macro containing the filename and line where the Error class is called and that information is appended to the error message. This @@ -285,6 +287,13 @@ the arguments are then handed for formatting to the `{fmt} library `_ (which is bundled with LAMMPS) and thus allow processing similar to the "format()" functionality in Python. +.. note:: + + For commands like :doc:`fix ave/time ` that accept + wildcard arguments, the :cpp:func:`utils::expand_args` function + may be passed as an optional argument where the function will provide + a map to the original arguments from the expanded argument indices. + For complex errors, that can have multiple causes and which cannot be explained in a single line, you can append to the error message, the string created by :cpp:func:`utils::errorurl`, which then provides a diff --git a/doc/src/Run_output.rst b/doc/src/Run_output.rst index d79882511a..28ed891765 100644 --- a/doc/src/Run_output.rst +++ b/doc/src/Run_output.rst @@ -203,26 +203,39 @@ Two lines In addition to the single line output, also the last line of the input will be repeated. If a command is spread over multiple lines in the input using the continuation character '&', then the error will print -the entire concatenated line. However, there is no further processing -of that line. Example: +the entire concatenated line. For readability all whitespace is +compressed to single blanks. Example: .. parsed-literal:: ERROR: Unrecognized fix style 'printf' (src/modify.cpp:924) - Last input line: fix 0 all printf v_nevery 'Step: $(step) ${step}' + Last input line: fix 0 all printf v_nevery "Step: $(step) ${step}" -Four lines -^^^^^^^^^^ +Three lines +^^^^^^^^^^^ -In addition to the two line output, the last command is printed a second -time, but *after* all variables were substituted and the line separated -into "words" as they are passed internally to the called command. This line -is followed by a line with caret character markers '^' to indicate which -"word" in the parsed input is causing the failure. Example: +In addition to the two line output from above, a third line is added +that uses caret character markers '^' to indicate which "word" in the +input failed. Example: .. parsed-literal:: ERROR: Illegal fix print nevery value -100; must be > 0 (src/fix_print.cpp:41) - Last input line: fix 0 all print ${nevery} 'Step: $(step) ${step}' + Last input line: fix 0 all print -100 "Step: $(step) ${stepx}" + ^^^^ + +Four lines +^^^^^^^^^^ + +The three line output is expanded to four lines, if the the input is +modified through input pre-processing, e.g. when substituting +variables. Now the last command is printed once in the original form and +a second time after substitutions are applied. The caret character +markers '^' are applied to the second version. Example: + +.. parsed-literal:: + + ERROR: Illegal fix print nevery value -100; must be > 0 (src/fix_print.cpp:41) + Last input line: fix 0 all print ${nevery} 'Step: $(step) ${step}' --> parsed line: fix 0 all print -100 "Step: $(step) ${step}" ^^^^ diff --git a/src/utils.h b/src/utils.h index 21300c4943..38f91cfc66 100644 --- a/src/utils.h +++ b/src/utils.h @@ -402,9 +402,9 @@ This functions adds the following case to :cpp:func:`utils::bounds()