Skip to content

Latest commit

 

History

History
353 lines (236 loc) · 12.3 KB

README.md

File metadata and controls

353 lines (236 loc) · 12.3 KB
Raw

TOML parser for Fortran projects

License Release Build docs Documentation Status codecov

A TOML parser implementation for data serialization and deserialization in Fortran.

TOML-Fortran

Installation

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.

Conda package

Conda Conda

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

FreeBSD port

FreeBSD port

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.

Alternative distributions

Please let us know if you are packaging TOML Fortran. Other available distributions of TOML Fortran currently include

An overview of the availability of TOML Fortran in distributions tracked by Repology is provided here:

Packaging status

Building from source

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

Get the source by cloning the repository

git clone https://github.com/toml-f/toml-f
cd toml-f

Building with meson

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

Building with CMake

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

Building with fpm

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.

Documentation

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.

Translating the documentation

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.

Generating the API docs

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

Usage

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
end

Here 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.

Contributing

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.

License

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.