ParmParse: Add TOML-like features

Docs/sphinx_documentation/source/Basics.rst

@@ -494,6 +494,125 @@ The following code shows how to query the enumerators.
        pp.query("color3", default_color); // Still MyColor::none
    }
 
+TOML-Like Features
+------------------
+
+Our :cpp:`ParmParse` format is somewhat similar to TOML. A subset of TOML
+can be processed by :cpp:`ParmParse`. For a key/value pair, the key starts
+with an alphabetical letter (a-zA-Z) followed by zero or more allowed
+characters (alphabetical letters, numbers, ``_``, ``-``, and ``.``).
+
+In TOML, the same key cannot appear more than once. In :cpp:`ParmParse`,
+this is allowed and the last one will overwrite previous ones.
+
+.. highlight:: python
+
+::
+
+   # Allowed in ParmParse, but do NOT do this if TOML compatibility is needed.
+   a = 1
+   a = 2
+
+In :cpp:`ParmParse`, quotes (``"``) are optional for strings, whereas in TOML
+they are required. In :cpp:`ParmParse`, a basic string is a raw string. For
+compatibility, you should avoid special escape sequences in strings. UTF-8
+strings are allowed, but it might be better to avoid them unless it's
+absolutely necessary.
+
+In TOML, arrays are values inside square brackets and they can be
+nested. :cpp:`ParmParse` supports TOML-like arrays and arrays of arrays, but
+not more deeply nested arrays. :cpp:`ParmParse` also does not support mixed
+types in an array. For arrays of strings using the ``[]`` syntax, you should
+avoid ``[`` or ``]`` as part of the strings. If, however, this is a desired
+feature, we could try to support it in the future.
+
+.. highlight:: python
+
+::
+
+  # valid in TOML, but not in ParmParse because of [] in the string
+  a = ["x[y]z", "123"]
+
+  # valid in ParmParse, but not in TOML
+  a = x[y]z 123
+  b = "x[y]z" "123"
+
+Although math expressions are allowed in :cpp:`ParmParse`'s native array
+format, they are not allowed in arrays started by square brackets.
+
+.. highlight:: python
+
+::
+
+  a = [3+4, 5+6] # Not allowed
+  b = 3+4  5+6  # Allowed in ParmParse, but not in TOML. Same as b = [7,11].
+
+Table in TOML are started by headers (e.g., ``[amr]`` in a line). By default,
+an entry before the table header is in the nameless top level table. Once a
+table header is defined, it will continue until another one is introduced.
+
+.. highlight:: python
+
+::
+
+   k = 1
+   p.k = 2
+
+   [a]
+   k = 3   # the full key/pair is a.k1 = 3
+   b.k = 4 # the full key/pair is a.b.k = 4
+
+   [b.c]
+   k = 5     # the full key/pair is b.c.k = 5
+   d.e.k = 6 # the full key/pair is b.c.d.e.k = 6
+
+The file above is the same as the following:
+
+.. highlight:: python
+
+::
+
+   k = 1
+   p.k = 2
+
+   a.k = 3
+   a.b.k = 4
+
+   b.c.k = 5
+   b.c.d.e.k = 6
+
+In TOML, it's not allowed to define a table more than once. But it's allowed
+in :cpp:`ParmParse`. If you want compatibility with TOML, you should avoid it.
+
+.. highlight:: python
+
+::
+
+   # Allowed in ParmParse, but do NOT do this if TOML compatibility is needed.
+   [a]
+   k = 1
+   [a.b]
+   k = 2
+
+.. highlight:: python
+
+::
+
+   # Allowed in ParmParse, but do NOT do this if TOML compatibility is needed.
+   [a]
+   k = 1
+   [a]
+   b = 2
+
+Including Another File
+----------------------
+
+In :cpp:`ParmParse`, you can use ``FILE = another_file`` to add the contents
+in another file into the :cpp:`ParmParse` database of key/value pairs. Note
+that TOML-like table headers defined in the included file have no effect on
+the current environment. Likewise, the included file also does not inherit
+the active table header from the including file.
+
 Overriding Parameters with Command-Line Arguments
 -------------------------------------------------
 

Src/Base/AMReX_ParmParse.H

@@ -1658,6 +1658,31 @@ public:
         }
     }
 
+    /**
+     * \brief Query vector of vector. The return value indicates whether
+     * it's found. The vector of vector is in the format of
+     * `[[a00, a01, a02...], [a10, a11, a12...], ...]`.
+     */
+    int queryarr (std::string_view name, std::vector<std::vector<double>>& ref) const;
+    int queryarr (std::string_view name, std::vector<std::vector<float>>& ref) const;
+    int queryarr (std::string_view name, std::vector<std::vector<int>>& ref) const;
+    int queryarr (std::string_view name, std::vector<std::vector<std::string>>& ref) const;
+
+    /**
+     * \brief Get vector of vector. It's an error if it is not found.  The
+     * vector of vector is in the format of `[[a00, a01, a02...], [a10, a11, a12...], ...]`.
+     */
+    template <typename T>
+    void getarr (std::string_view name, std::vector<std::vector<T>>& ref) const
+    {
+        if (this->queryarr(name, ref) == 0) {
+            amrex::ErrorStream() << "ParmParse::getarr: " << name
+                                 << " not found in database\n";
+            ParmParse::dumpTable(amrex::ErrorStream());
+            amrex::Abort();
+        }
+    }
+
     /**
     * \brief Construct an initial ParmParse object from the argc and argv
     * passed in to main().  An error will be signalled if another