diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in index f8a5bc6cdb..49a271355f 100644 --- a/doc/doxygen/Doxyfile.in +++ b/doc/doxygen/Doxyfile.in @@ -424,6 +424,8 @@ INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \ @LAMMPS_SOURCE_DIR@/input.h \ @LAMMPS_SOURCE_DIR@/tokenizer.cpp \ @LAMMPS_SOURCE_DIR@/tokenizer.h \ + @LAMMPS_SOURCE_DIR@/arg_info.cpp \ + @LAMMPS_SOURCE_DIR@/arg_info.h \ @LAMMPS_SOURCE_DIR@/text_file_reader.cpp \ @LAMMPS_SOURCE_DIR@/text_file_reader.h \ @LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \ diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst index 17b6f13bad..f6e7d64c3e 100644 --- a/doc/src/Developer_utils.rst +++ b/doc/src/Developer_utils.rst @@ -292,6 +292,50 @@ This code example should produce the following output: ---------- + +Argument parsing classes +--------------------------- + +The purpose of argument parsing classes it to simplify and unify how +arguments of commands in LAMMPS are parsed and to make abstractions of +repetitive tasks. + +The :cpp:class:`LAMMPS_NS::ArgInfo` class provides an abstraction +for parsing references to compute or fix styles or variables. These +would start with a "c\_", "f\_", "v\_" followed by the ID or name of +than instance and may be postfixed with one or two array indices +"[]" with numbers > 0. + +A typical code segment would look like this: + +.. code-block:: C++ + :caption: Usage example for ArgInfo class + + int nvalues = 0; + for (iarg = 0; iarg < nargnew; iarg++) { + ArgInfo argi(arg[iarg]); + + which[nvalues] = argi.get_type(); + argindex[nvalues] = argi.get_index1(); + ids[nvalues] = argi.copy_name(); + + if ((which[nvalues] == ArgInfo::UNKNOWN) + || (which[nvalues] == ArgInfo::NONE) + || (argi.get_dim() > 1)) + error->all(FLERR,"Illegal compute XXX command"); + + nvalues++; + } + +---------- + +.. doxygenclass:: LAMMPS_NS::ArgInfo + :project: progguide + :members: + + +---------- + File reader classes ------------------- diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 21582f11f1..e9ba170ac5 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -2478,6 +2478,9 @@ Poresag pos Poschel posix +postfix +postfixed +postfixes Postma Potapkin potin diff --git a/src/arg_info.cpp b/src/arg_info.cpp index 225b822fb9..72dde9a81f 100644 --- a/src/arg_info.cpp +++ b/src/arg_info.cpp @@ -18,6 +18,17 @@ using namespace LAMMPS_NS; +/** Class for processing references to fixes, computes and variables + * + * This class provides an abstraction for the repetitive task of + * parsing arguments that may contain references to fixes, computes, + * or variables. It will identify the name and the index in the first + * and second dimension, if present. + * + * + * \param arg string with possible reference + * \param allowed integer with bitmap of allowed types of references */ + ArgInfo::ArgInfo(const std::string &arg, int allowed) : type(NONE), dim(0), index1(-1), index2(-1) { @@ -72,6 +83,16 @@ ArgInfo::ArgInfo(const std::string &arg, int allowed) /* ---------------------------------------------------------------------- */ +/*! make copy of the ID of the reference as C-style string + * + * The ID is copied into a buffer allocated with "new" and thus + * must be later deleted with "delete []" to avoid a memory leak. + * Because it is a full copy in a newly allocated buffer, the + * lifetime of this string extends beyond the the time the ArgInfo + * class is in scope. + * + * \return copy of string as char * */ + char *ArgInfo::copy_name() { char *dest = new char[name.size()+1]; diff --git a/src/arg_info.h b/src/arg_info.h index ea1208c49b..34924c0796 100644 --- a/src/arg_info.h +++ b/src/arg_info.h @@ -21,7 +21,8 @@ namespace LAMMPS_NS { class ArgInfo { public: - enum { + /*! constants for argument types */ + enum ArgTypes { ERROR =-2, UNKNOWN =-1, NONE = 0, @@ -51,11 +52,52 @@ namespace LAMMPS_NS { virtual ~ArgInfo() {} public: + /*! get type of reference + * + * Return a type constant for the reference. This may be either + * COMPUTE, FIX, VARIABLE (if not restricted to a subset of those + * by the "allowed" argument of the constructor) or NONE, if it + * if not a recognized or allowed reference, or UNKNOWN, in case + * some error happened identifying or parsing the values of the indices + * + * \return integer with a constant from ArgTypes enumerator */ + int get_type() const { return type; } + + /*! get dimension of reference + * + * This will return either 0, 1, 2 depending on whether the + * reference has no, one or two "[]" postfixes. + * + * \return integer with the dimensionality of the reference */ int get_dim() const { return dim; } + + /*! get index of first dimension + * + * This will return the in the first "[]" + * postfix or 0 if there is no postfix. + * + * \return integer with index or the postfix or 0 */ int get_index1() const { return index1; } + + /*! get index of second dimension + * + * This will return the in the second "[]" + * postfix or -1 if there is no second postfix. + * + * \return integer with index of the postfix or -1 */ int get_index2() const { return index2; } + + /*! return reference to the ID or name of the reference + * + * This string is pointing to an internal storage element and + * is only valid to use while the ArgInfo class instance is + * in scope. If you need a long-lived string make a copy + * with copy_name(). + * + * \return C-style char * string */ const char *get_name() const { return name.c_str(); } + char *copy_name(); private: