TOML DFN format

[wpbonelli]

Just collecting some existing discussion and further thoughts here

After chatting on the initial format in modflowpy/flopy#2333 (comment) it sounds like we want blocks at the top level, rather than variables, and to omit explicit child attributes in favor of attaching children directly to the parent. So the example would become

name = "prt-oc"
multi = false
stress = false
advanced = false

[options.budget_filerecord]
type = "record"

[options.budget_filerecord.budget]
type = "keyword"
reader = "urword"
optional = false
longname = "budget keyword"
description = "keyword to specify that record corresponds to the budget."

[options.budget_filerecord.fileout]
type = "keyword"
reader = "urword"
optional = false
longname = "file keyword"
description = "keyword to specify that an output filename is expected next."

[options.budget_filerecord.budgetfile]
type = "string"
reader = "urword"
optional = false
longname = "file keyword"
description = "name of the output file to write budget information."

...

Period block specifications could look like

...

[period.iper]
type = "integer"
block_index = true
reader = "urword"
optional = false
longname = "stress period number"
description = "integer value specifying the stress period number for which the data specified in the PERIOD block apply. IPER must be less than or equal to NPER in the TDIS Package and greater than zero. The IPER value assigned to a stress period block must be greater than the IPER value assigned for the previous PERIOD block. The information specified in the PERIOD block applies only to that stress period."

[period.perioddata]
type = "list"
reader = "urword"
optional = false

[period.perioddata.releasesetting]
type = "record"
reader = "urword"
optional = false

[period.perioddata.releasesetting.all]
type = "keyword"
reader = "urword"
description = "keyword to indicate release of particles at the start of all time steps in the period."

[period.perioddata.releasesetting.first]
type = "keyword"
reader = "urword"
description = "keyword to indicate release of particles at the start of the first time step in the period. This keyword may be used in conjunction with other keywords to release particles at the start of multiple time steps."

[period.perioddata.releasesetting.frequency]
type = "integer"
reader = "urword"
description = "release particles at the specified time step frequency. This keyword may be used in conjunction with other keywords to release particles at the start of multiple time steps."

[period.perioddata.releasesetting.steps]
type = "integer"
shape = "(<nstp)"
reader = "urword"
description = "release particles at the start of each step specified in STEPS. This keyword may be used in conjunction with other keywords to release particles at the start of multiple time steps."
...

Setting `block_index` for an integer top-level block variable can indicate transient data, otherwise the block is handled normally

This has not been implemented yet in the referenced PR or here. It could maybe be prototyped here, moved to flopy3 when ready, and then moved to devtools once we're confident in it.