A TOML parser implementation for data serialization and deserialization in Fortran.
- the TOML standard
- currently supported TOML v1.0.0 specification
- TOML Fortran documentation
The TOML Fortran library is available via various distribution channels. If your channel is not found here, please checkout the instructions for building from source. You can also find these instructions in the user documentation at Installing TOML Fortran.
This project is packaged for the mamba package manager and available on the conda-forge channel. To install the mamba package manager we recommend the mambaforge installer. If the conda-forge channel is not yet enabled, add it to your channels with
mamba config --add channels conda-forge
mamba config --set channel_priority strict
Once the conda-forge channel has been enabled, TOML Fortran can be installed with mamba:
mamba install toml-f
It is possible to list all of the versions of TOML Fortran available on your platform with mamba:
mamba repoquery search toml-f --channel conda-forge
A port for FreeBSD is available and can be installed using
pkg install textproc/toml-f
In case no package is available build the port using
cd /usr/ports/textproc/toml-f
make install clean
For more information see the toml-f port details.
Please let us know if you are packaging TOML Fortran. Other available distributions of TOML Fortran currently include
- Homebrew tap at grimme-lab/homebrew-qc
- Easy-build config at easybuilders/easybuild-easyconfigs
- spack package in develop
An overview of the availability of TOML Fortran in distributions tracked by Repology is provided here:
To build this project from the source code in this repository you need to have
-
a Fortran compiler supporting Fortran 2008
- GFortran 5 or newer
- Intel Fortran 18 or newer
- NAG 7 or newer
-
One of the supported build systems
- meson version 0.55 or newer
- CMake version 3.9 or newer
- Fortran package manager (fpm) version 0.2.0 or newer
Get the source by cloning the repository
git clone https://github.com/toml-f/toml-f
cd toml-f
To integrate TOML Fortran in your meson project checkout the Integrate with meson recipe.
To build this project with meson a build-system backend is required, i.e. ninja version 1.7 or newer. Setup a build with
meson setup _build --prefix=/path/to/install
You can select the Fortran compiler by the FC environment variable.
To compile the project run
meson compile -C _build
We employ a validator suite to test the standard compliance of this implementation.
To use this testing a go installation is required.
The installation of the validator suite will be handled by meson automatically without installing into the users go workspace.
Run the tests with
meson test -C _build --print-errorlogs
The binary used for transcribing the TOML documents to the testing format is _build/test/toml2json and can be used to check on per test basis.
Finally, you can install TOML Fortran using
meson install -C _build
To integrate TOML Fortran in your CMake project checkout the Integrate with CMake recipe.
While meson is the preferred way to build this project it also offers CMake support. Configure the CMake build with
cmake -B _build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install
Similar to meson the compiler can be selected with the FC environment variable.
You can build the project using
cmake --build _build
You can run basic unit tests using
ctest --test-dir _build
The validation suite is currently not supported as unit test for CMake builds and requires a manual setup instead using the toml2json binary.
Finally, you can install TOML Fortran using
cmake --install _build
To integrate TOML Fortran in your fpm project checkout the Using the Fortran package manager recipe.
The Fortran package manager (fpm) supports the addition of TOML Fortran as a dependency.
In the package manifest, fpm.toml, you can add TOML Fortran dependency via:
[dependencies]
toml-f.git = "https://github.com/toml-f/toml-f"Then build and test normally.
fpm build
fpm test
A more detailed example is described in example 1.
The user documentation is available at readthedocs. Additionally, the FORD generated API documentation is available here.
To build the user documentation locally we use sphinx, install the dependencies you can use the mamba package manager
mamba create -n sphinx --file doc/requirements.txt
mamba activate sphinx
The documentation is build with
sphinx-build doc _doc
You can inspect the generated documentation by starting a webserver
python3 -m http.server -d _doc
And open the down URL in a browser.
The documentation of TOML Fortran can be fully translated. Before adding a translation, reach out to the repository maintainers by creating and issue or starting a discussion thread.
To start a new translation you need the sphinx-intl package which can be installed with mamba
mamba install -n sphinx sphinx-intl
To add a new language to the translation extract the text with sphinx-build and create the respective locales with sphinx-intl using the commands shown below.
sphinx-build -b gettext doc _gettext
sphinx-intl update -l en -p _gettext -d doc/locales
Replace the argument to the language flag -l with your target language, the language keys are listed here.
The same workflow can be used for updating existing locales.
The translation files are available in doc/locales and can be translated using a translation-editor, like gtranslator or poedit.
After a new translation is merged, a maintainer will create a new translation for the readthedocs to ensure it shows up at the pages.
The API documentation is generated with FORD. We are looking for a better tool to automatically extract the documentation, suggestions and help with this effort are welcome.
The required programs can be installed with mamba
mamba create -n ford ford
mamba activate ford
To generate the pages use
ford docs.md -o _ford
You can inspect the generated documentation by starting a webserver
python3 -m http.server -d _ford
To make use this library use the tomlf module in your projects.
You can access the individual modules but those are not considered part of the public API and might change between versions.
An example program to load and dump a TOML file would look like this:
use tomlf
implicit none
character(len=*), parameter :: nl = new_line("a")
type(toml_table), allocatable :: table
character(kind=tfc, len=:), allocatable :: input_string
type(toml_serializer) :: ser
input_string = &
& '# This is a TOML document.' // nl // &
& 'title = "TOML Example"' // nl // &
& '[owner]' // nl // &
& 'name = "Tom Preston-Werner"' // nl // &
& 'dob = 1979-05-27T07:32:00-08:00 # First class dates' // nl // &
& '[database]' // nl // &
& 'server = "192.168.1.1"' // nl // &
& 'ports = [ 8001, 8001, 8002 ]' // nl // &
& 'connection_max = 5000' // nl // &
& 'enabled = true' // nl // &
& '[servers]' // nl // &
& ' # Indentation (tabs and/or spaces) is allowed but not required' // nl // &
& ' [servers.alpha]' // nl // &
& ' ip = "10.0.0.1"' // nl // &
& ' dc = "eqdc10"' // nl // &
& ' [servers.beta]' // nl // &
& ' ip = "10.0.0.2"' // nl // &
& ' dc = "eqdc10"' // nl // &
& '[clients]' // nl // &
& 'data = [ ["gamma", "delta"], [1, 2] ]' // nl // &
& '# Line breaks are OK when inside arrays' // nl // &
& 'hosts = [' // nl // &
& ' "alpha",' // nl // &
& ' "omega"' // nl // &
& ']'
call toml_loads(table, input_string)
if (allocated(table)) then
call table%accept(ser)
call table%destroy ! not necessary
end if
endHere the TOML document is provided as string, notice that you have to add a newline character by using the intrinsic function new_line("a") to get the lines correctly.
Alternatively, a file can be loaded from any connected, formatted unit using the same overloaded function.
For the standard input the intrinsic input_unit should be passed.
If the TOML file is successfully parsed the table will be allocated and can be written to the standard output by passing the toml_serializer as visitor to the table.
For more details checkout the documentation pages. If you find an error in the documentation or a part is incomplete, please open an issue or start a discussion thread.
This is a volunteer open source projects and contributions are always welcome. Please, take a moment to read the contributing guidelines on how to get involved in TOML-Fortran.
TOML-Fortran is free software: you can redistribute it and/or modify it under the terms of the Apache License, Version 2.0 or MIT license at your opinion.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an as is basis, without warranties or conditions of any kind, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in TOML-Fortran by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.