ParmParse: Add TOML-like features

[WeiqunZhang]

Add new TOML-like features:

• Multi-line string using """.
• Array using square brackets.
• Table using [table] as header.

[WeiqunZhang]

Note that this PR contains #4944.

[WeiqunZhang]

https://github.com/WeiqunZhang/amrex/blob/c6386f87bb8ff6b63e4eb4fc484f7226d0337b69/Tests/TOML/config.toml

Here is a file that can be read by both ParmParse and TOML.

[WeiqunZhang]

@ax3l, let me know what you think

[WeiqunZhang]

Re: table header (e.g., [warpx]), right now it will pollute files included with FILE=.... Is this the desired behavior?

[WeiqunZhang]

As for command line, we definitely do not want it affected the tables in inputs files.

[ax3l]

Awesome, thank you!!

The PR seems to have some commits from #4944, is that intentional?

[WeiqunZhang]

Yes, it was intentional since this is still a draft. I have rebased the commit on top of #4944 to avoid future conflicts and run the latest clang-tidy.

[WeiqunZhang]

Re: table header (e.g., [warpx]), right now it will pollute files included with FILE=.... Is this the desired behavior?

For example, suppose we have

# this is file file_a
abc = 3 # Its full name depends on its environment.

[amrex]
ppp = 1

What do we expect?

[warpx]
def = 4

FILE = file_a

x = 3  # Is this warpx.x? It depends.

and

[warpx]
def = 4
[warpx.boundary]
xyz = 5

FILE = file_a

x = 3 # Is this warpx.x? It depends.

Currently, FILE will inherit and affect the table environment of where it's included, as if the file is directly copy-pasted. I think this can be very confusing. I think it should have its own clean environment.

[ax3l]

Yeah, if FILE means just "adding" defines from the other file, so without wrapping into a prefix, that would be clean.
We would also like to avoid that this adds a new unexpected scope if there is a table in that file. So literal copy-paste #include-like behavior is indeed what we should avoid.

In practice, at least WarpX CI workflows only include on the top to keep things simple.

[BenWibking]

This would be useful for our code as well. However, I am still confused about table vs non-table environments. For instance, in this example:

[quokka]
cfl = 0.3

max_time = 1.0

does the blank line end the [quokka] table environment above?

[WeiqunZhang]

No it does not.

[ax3l]

Right, here are the details:
https://toml.io/en/v1.0.0#table

In particular: (1-2 pages scrolling)

The top-level table, also called the root table, starts at the beginning of the document and ends just before the first table header (or EOF). Unlike other tables, it is nameless and cannot be relocated.

Everything else after a table header stays in that header, independent of extra empty newlines.

Note that you cannot continue a table in TOML11, but we could allow this in AMReX. TOML:

Like keys, you cannot define a table more than once. Doing so is invalid.

[ax3l]

Note there is also a cool way to define arrays in TOML, which can be extended, but that is not what we do here for key-value pairs of parm-parse:
https://toml.io/en/v1.0.0#array-of-tables

The arrays are about long or nested list values.

[WeiqunZhang]

Note that you cannot continue a table in TOML11, but we could allow this in AMReX.

Yes, we will allow it. For example.

# Allowed in ParmParse, but do NOT do this if TOML compatibility is needed.
[a]
k = 1

[a.b]           
k = 2

# Allowed in ParmParse, but do NOT do this if TOML compatibility is needed.
[a]
k = 1

[a]
b = 2

# Allowed in ParmParse, but do NOT do this if TOML compatibility is needed.
a = 1
a = 2

[WeiqunZhang]

I have removed #4944 from this PR. It's clean and ready for review now.

[ax3l]

Thank you. That's great!