Last modified 2 months ago Last modified on 04.10.2017 21:41:45

TOML

Description

toml is an Erlang library application for parsing TOML configuration language. It supports parsing 0.4.0 version of the TOML specification.

Since TOML is a format for configuration files instead of general purpose serialization, toml library focuses on reading the configuration parameters.

toml:parse/2 and toml:read_file/2 allow user to provide a validation callback, which can check correctness of a value (e.g. if a listen address in listen="host:port" has proper format) and even convert such values to a usable Erlang data structure. All this happens at the time of reading a configuration file, so any errors can be rejected in uniform manner.

In smaller scale, toml:get_value/3 returns values as tuples tagged with value type. This allows to fail early and with clear error on an obviously invalid parameter:

# [spool]
# directory = 1024
{string, SpoolDir} = toml:get_value(["spool"], "directory", Config).

Configuration usually consists of flags and parameters and not of complex, nested data structures, so toml leans towards simple sections (or tables, how TOML calls them) and simple access to values in them. Still, all the TOML specification is supported, so nested structures are available.

For details on usage, see local copy of API documentation.

Usage example

Let's assume an input file called config.toml has following content:

lipsum = "lorem ipsum dolor sit amet"

[apples]
count = 2

[berry.black]
has_some = true

Configuration from this file can be retrieved in following manner:

{ok, Config} = toml:read_file("config.toml").
{string, Val1} = toml:get_value([], "lipsum", Config).
{integer, Val2} = toml:get_value(["apples"], "count", Config).
{boolean, Val3} = toml:get_value(["berry", "black"], "has_some", Config).
none = toml:get_value([], "oranges", Config).

Known limitations

  • Types conveying time only store 1s precision (fraction of a second is truncated)

TODO

  • more precise error reporting
  • to_list()
  • mutator functions (set_value(), update(), delete())
  • serialization and writing to disk

How to download

Canonical repository location is at jarowit.

git clone http://dozzie.jarowit.net/code/erlang-toml.git

There is a supplementary location at GitHub.

git clone https://github.com/dozzie/toml

How to install

Installation process is tested for building RPM/DEB packages. If you want to make mess in your system by omitting package system, you are on your own. The application, however, uses rebar to build its code, so it should be pretty standard as for Erlang.

You need casual package building tools for your distribution, either rpm-build (RPMs) or dpkg-dev with fakeroot (DEBs).

manual build

The process boils down to run rebar compile. *.beam files will be stored in ./ebin directory.

The EDoc documentation can be generated using rebar doc.

Red Hat

  1. Prepare source RPM (non-root privileges are fine here)
    make srpm
    
  2. Build binary RPM (unless you've taken care of building as non-root, you need to be root here)
    rpmbuild --rebuild erlang-toml-*.src.rpm
    
  3. Install package with its dependencies (exact path should be printed by previous step); most probably it will be located in /usr/src/redhat/RPMS/noarch/erlang-toml-*.rpm

Debian

  1. Build binary package
    dpkg-buildpackage -b -uc
    
  2. Install package (../erlang-toml*.deb) with its dependencies