The entry barrier for using the TOML Fortran library was always a bit too high in my opinion, especially since the generated API docs are not really that user friendly. Therefore, I created a couple of how to guides on TOML Fortran based on the usage of the library in fpm, mainly focusing on tables (Working with tables — TOML Fortran) and building round-tripping data types (Serializable base class — TOML Fortran). If you want to know about something in particular, feel free to post them here.
There is also a translated German version available, because I wanted to try the translation feature of readthedocs (translating software related guides can be really hard, I hope it is not too bad). This seems to work nicely, in case anyone is interested to improve or contribute translations, let me know.
I’m currently looking into writing a complete tutorial for building an application and designing the configuration / input file using TOML Fortran. I haven’t decided on the domain yet, either package management or computational chemistry are candidates at the moment. Suggestions and ideas for such a complete walk-through are of course welcome.
On another note, TOML Fortran is now available in six package managers (fpm, spack, conda/mamba, homebrew, easybuild, and FreeBSD ports).
I have a small guide on building the documentation in the README, the biggest difference in the localization infrastructure compared to the fpm pages is that the translations are completely managed via readthedocs and are available via the version tab in the sidebar
Means there is no need to manually add a new language in the repository other than having the po files, once the translation is available in the repo I will activate it in the readthedocs project (there is a translations header in the sidebar there as well) and it will be build with the pages.
I’m looking into writing a complete walk-through for building a configuration file with TOML Fortran:
The tutorial should cover the usage of TOML Fortran, but will mainly discuss the design of a configuration file for the chosen application and how this can be realized in actual code. The idea is to teach by example here using a generally interesting topic for the learner and also introduce the usage of the library.
As a computational chemist, I’m tempted to write about creating a minimalistic atomistic simulation program and its input format (computational chemistry is a domain where every program usually comes with a handcrafted parser). But I’m open for other ideas for the domain to cover, the final program must of course be fully usable, preferably with fpm and the configuration should reflect usual requirements in the respective domain.
Nice timing! On Wednesday, I started to play around with the examples of toml-f. I’m seeking an alternative for the configuration of our climate model, which currently consists of a ksh script, which builds another script from a template which then gets executed by slurm on our supercomputers. Both the ksh script and the template contain configuration. Additionally, there are many namelists. It would be nice to have all options in one file. The options are mainly:
paths
compiler options
selection of algorithms
options for the algorithms
options for model in general (grid, number of iterations, etc.)
job settings (nodes, cpus, time…)
I doubt everything will fit into one toml which gets parsed by Fortran. But having all options in one place would be much of an improvement.
I would be pleased, if your example program covered some of these points.
That is indeed an interesting idea, having a central configuration file in TOML where multiple programs or steps from a workflow, if I understand the main purpose correctly. One way to archive this is to put all program configurations not in the top-level but a subtable with their name, the advantage is that many languages have TOML parsers (see Home · toml-lang/toml Wiki · GitHub) and can all read from the same configuration file.
Maybe some structure like here works, the model entry will probably be the most sophisticated depending on how customizable the program is.
[environment] # Calculation environment settings
path = "..."
[job] # Options for slurm submission and program settings
nproc = ...
queue = "..."
[model] # Actual model
grid = [..., ...]
max-iter = ...
Would be interested in the details on the setup and how you want to apply TOML as central configuration format. If you have any question on TOML Fortran, let me know.
I agree @awvwgk , having more simple tutorials to learn-by-example on real Serialization formats (JSON, YAMl, TOML) would be nice.
The example in our blog on Namelist was a little bit too complex IMHO for a large audience -because it was directed to our lab audience-, we should make one simpler and better written, at least for starters.
I enabled previews for the documentation pages, you can checkout Asdrubal’s work at https://toml-f--86.org.readthedocs.build/es/86/ if you speak Spanish and provide feedback at the linked PR.
