From 33f2cbc71304b45f4fbe26eb36c23d8707f9c2d5 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 31 Aug 2020 06:57:16 -0400 Subject: [PATCH] add docs for TextFileReader class to developer guide --- doc/doxygen/Doxyfile.in | 2 ++ doc/src/pg_developer.rst | 20 ++++++++++++++++ src/text_file_reader.cpp | 49 +++++++++++++++++++++++++++++++++++++++- src/text_file_reader.h | 2 +- src/tokenizer.cpp | 6 ++++- 5 files changed, 76 insertions(+), 3 deletions(-) diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in index d6b9327df1..47e61a4ca8 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@/text_file_reader.cpp \ + @LAMMPS_SOURCE_DIR@/text_file_reader.h \ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded diff --git a/doc/src/pg_developer.rst b/doc/src/pg_developer.rst index f6cd3cd6c3..737a1597b1 100644 --- a/doc/src/pg_developer.rst +++ b/doc/src/pg_developer.rst @@ -762,6 +762,8 @@ on reading or an unexpected end-of-file state was reached. In that case, the functions will stop the calculation with an error message, indicating the name of the problematic file, if possible. +---------- + .. doxygenfunction:: sfgets :project: progguide @@ -785,6 +787,8 @@ return the result of a partial conversion or zero in cases where the string is not a valid number. This behavior allows to more easily detect typos or issues when processing input files. +---------- + .. doxygenfunction:: numeric :project: progguide @@ -803,6 +807,8 @@ String processing functions The following are functions to help with processing strings and parsing files or arguments. +---------- + .. doxygenfunction:: trim :project: progguide @@ -995,3 +1001,17 @@ This code example should produce the following output: :project: progguide :members: what +File reader classes +==================== + +The purpose of the file reader classes is to simplify the recurring task +of reading and parsing files. They are built on top of the tokenizer +classes discussed in the previous section, but include operations that +are optimized for processing larger chunks of data more efficiently. + +---------- + +.. doxygenclass:: LAMMPS_NS::TextFileReader + :project: progguide + :members: + diff --git a/src/text_file_reader.cpp b/src/text_file_reader.cpp index 8abe1b001f..1e1e5e2ec1 100644 --- a/src/text_file_reader.cpp +++ b/src/text_file_reader.cpp @@ -28,6 +28,17 @@ using namespace LAMMPS_NS; +/** Class for reading and parsing text files + * + * The value of the class member variable *ignore_comments* controls + * whether any text following the pound sign (#) should be ignored (true) + * or not (false). Default: true, i.e. ignore. + * + * \param filename Name of file to be read + * \param filetype Description of file type for error messages + * + * \sa PotentialFileReader */ + TextFileReader::TextFileReader(const std::string &filename, const std::string &filetype) : filename(filename), filetype(filetype), ignore_comments(true) { @@ -38,10 +49,14 @@ TextFileReader::TextFileReader(const std::string &filename, const std::string &f } } +/** Closes the file */ + TextFileReader::~TextFileReader() { fclose(fp); } +/** Read the next line and ignore it */ + void TextFileReader::skip_line() { char *ptr = fgets(line, MAXLINE, fp); if (ptr == nullptr) { @@ -50,6 +65,20 @@ void TextFileReader::skip_line() { } } +/** Read the next line(s) until *nparams* words have been read. + * + * This reads a line and counts the words in it, if the number + * is less than the requested number, it will read the next + * line, as well. Output will be a string with all read lines + * combined. The purpose is to somewhat replicate the reading + * behavior of formatted files in Fortran. + * + * If the *ignore_comments* class member has the value *true*, + * then any text read in is truncated at the first '#' character. + * + * \param nparams Number of words that must be read. Default: 0 + * \return String with the concatenated text */ + char *TextFileReader::next_line(int nparams) { // concatenate lines until have nparams words int n = 0; @@ -82,7 +111,6 @@ char *TextFileReader::next_line(int nparams) { return nullptr; } - // strip comment if (ignore_comments && (ptr = strchr(line, '#'))) *ptr = '\0'; @@ -97,6 +125,15 @@ char *TextFileReader::next_line(int nparams) { return line; } +/** Read lines until *n* doubles have been read and stored in array *list* + * + * This reads lines from the file using the next_line() function, + * and splits them into floating-point numbers using the + * ValueTokenizer class and stores the number is the provided list. + * + * \param list Pointer to array with suitable storage for *n* doubles + * \param n Number of doubles to be read */ + void TextFileReader::next_dvector(double * list, int n) { int i = 0; while (i < n) { @@ -116,6 +153,16 @@ void TextFileReader::next_dvector(double * list, int n) { } } +/** Read text until *nparams* words are read and passed to a tokenizer object for custom parsing. + * + * This reads lines from the file using the next_line() function, + * and splits them into floating-point numbers using the + * ValueTokenizer class and stores the number is the provided list. + * + * \param nparams Number of words to be read + * \param separators String with list of separators. + * \return ValueTokenizer object for read in text */ + ValueTokenizer TextFileReader::next_values(int nparams, const std::string & separators) { return ValueTokenizer(next_line(nparams), separators); } diff --git a/src/text_file_reader.h b/src/text_file_reader.h index 80a5d756ea..b64407701f 100644 --- a/src/text_file_reader.h +++ b/src/text_file_reader.h @@ -33,7 +33,7 @@ namespace LAMMPS_NS FILE *fp; public: - bool ignore_comments; + bool ignore_comments; //!< Controls whether comments are ignored TextFileReader(const std::string &filename, const std::string &filetype); ~TextFileReader(); diff --git a/src/tokenizer.cpp b/src/tokenizer.cpp index bad6250df5..c08d66664f 100644 --- a/src/tokenizer.cpp +++ b/src/tokenizer.cpp @@ -35,7 +35,8 @@ TokenizerException::TokenizerException(const std::string & msg, const std::strin * This tokenizer will break down a string into sub-strings (i.e words) * separated by the given separator characters. * - * \exception TokenizerException + * \param str string to be processed + * \param separators string with separator characters (default: " \t\r\n\f") * * \sa ValueTokenizer TokenizerException */ @@ -148,6 +149,9 @@ std::vector Tokenizer::as_vector() { } /*! Class for reading text with numbers + * + * \param str string to be processed + * \param separators string with separator characters (default: " \t\r\n\f") * * \sa Tokenizer InvalidIntegerException InvalidFloatException */