# TOML Fortran recipes **URL:** \ **Category:** Announcements\ **Created:** [June 17, 2022, 3:00pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784 "2022-06-17T15:00:03Z")\ **Posts on this page:** 8\ **Page:** 1
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [June 17, 2022, 3:00pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/1 "2022-06-17T15:00:03Z")
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](https://toml-f.readthedocs.io/en/latest/how-to/table.html)) and building round-tripping data types ([Serializable base class — TOML Fortran](https://toml-f.readthedocs.io/en/latest/how-to/serde.html)). 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). > **[GitHub - toml-f/toml-f: TOML parser implementation for data serialization and...](https://github.com/toml-f/toml-f)** > > TOML parser implementation for data serialization and deserialization in Fortran - GitHub - toml-f/toml-f: TOML parser implementation for data serialization and deserialization in Fortran ---
**Author:** ![alozada](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/alozada/32/298_2.png) [@alozada](https://fortran-lang.discourse.group/u/alozada)\ **Post date:** [June 17, 2022, 4:21pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/2 "2022-06-17T16:21:36Z")
> [@awvwgk](#): > > in case anyone is interested to improve or contribute translations, let me know. I’ll start a Spanish translation, what do you think? ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [June 17, 2022, 4:32pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/3 "2022-06-17T16:32:46Z")
You are very welcome to add one. I have a small guide on building the documentation in the [README](https://github.com/toml-f/toml-f#documentation), 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 ![image](https://global.discourse-cdn.com/free1/uploads/fortran_lang/original/2X/a/a48d1bb9fd405dfc9f8224958356c2f88ea9b61a.png) 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](https://readthedocs.org/projects/toml-f/) (there is a translations header in the sidebar there as well) and it will be build with the pages. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [June 19, 2022, 9:53am UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/4 "2022-06-19T09:53:47Z")
I’m looking into writing a complete walk-through for building a configuration file with TOML Fortran: > > > Provide a complete walk-through for building a configuration file for an applica…tion, discussing advantages and disadvantages of certain data structures, would also be a good choice for a tutorial. I don't have something particular in mind yet for a topic, either package management or computational chemistry might be themes I would chose for such a guide. > > Relevant points (not all might be covered): > > \- naming of tables / keys (lowercase-dashed, snake\\\_case, camelCase) > \- name for array of tables, singular vs. plural > \- nesting tables, reusable input parser > \- versioning the format, automatic updates on breaking changes > \- error reporting for user, error handler vs. full context > \- reporting full input for reproducibility (filling in defaults, version migrations) > \- interacting with other input sources (command line arguments, global configuration file \`~/.\rc\`) > > Potential examples (suggestions are welcome): > > \- atomistic simulation program > - tasks like single point, geometry optimization, molecular dynamics, frequency calculation, ... > - post processing and analysis, logging > - needs a FF, SQM or DFT package as backend to be runable (maybe \[tblite\](https://tblite.readthedocs)?) 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. Let me know what you think. ---
**Author:** ![Carltoffel](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/carltoffel/32/1680_2.png) [@Carltoffel](https://fortran-lang.discourse.group/u/Carltoffel)\ **Post date:** [June 19, 2022, 2:23pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/5 "2022-06-19T14:23:37Z")
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. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [June 19, 2022, 3:10pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/6 "2022-06-19T15:10:32Z")
> [@Carltoffel](#): > > 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. 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](https://github.com/toml-lang/toml/wiki)) 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. ```ini [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. > [@Carltoffel](#): > > Additionally, there are many namelists. Another idea could be a tutorial for migrating from a namelist based input to an equivalent TOML. There is a guide from the COOP Blog linking to TOML Fortran mainly explaining namelists ([Working nicely with Fortran Namelists · The COOP Blog](https://cerfacs.fr/coop/fortran-namelist-workedex), by @Dauptain I think), which seems to regularly direct visitors to the TOML Fortran repository. I could imagine using their namelist examples and create a tutorial for writing the corresponding TOML parser ([Tutorial for converting from namelist to TOML · Issue #85 · toml-f/toml-f · GitHub](https://github.com/toml-f/toml-f/issues/85)). ---
**Author:** ![Dauptain](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/dauptain/32/680_2.png) [@Dauptain](https://fortran-lang.discourse.group/u/Dauptain)\ **Post date:** [June 19, 2022, 8:10pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/7 "2022-06-19T20:10:00Z")
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. ---
**Author:** ![awvwgk](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/awvwgk/32/154_2.png) [@awvwgk](https://fortran-lang.discourse.group/u/awvwgk)\ **Post date:** [June 25, 2022, 1:39pm UTC](https://fortran-lang.discourse.group/t/toml-fortran-recipes/3784/8 "2022-06-25T13:39:17Z")
> [@alozada](#): > > I’ll start a Spanish translation, what do you think? Thanks for starting the translation. I enabled previews for the documentation pages, you can checkout Asdrubal’s work at [https://toml-f--86.org.readthedocs.build/es/86/](https://toml-f--86.org.readthedocs.build/es/86/) if you speak Spanish and provide feedback at the linked PR.