README.md

cpptoml

A header-only library for parsing TOML configuration files.

Targets: TOML v0.5.0 as of August 2018.

This includes support for the new DateTime format, inline tables, multi-line basic and raw strings, digit separators, hexadecimal integers, octal integers, binary integers, and float special values.

Alternatives:

• Boost.toml is a C++ implementation of a TOML parser using the Boost library. As of writing, it supports v0.5.0 as well.
• ctoml is a C++11 implementation of a TOML parser, but only supports v0.2.0.
• libtoml is a C implementation of a TOML parser, which can be linked to from your C++ programs easily. As of April 2016, it supports v0.4.0.
• tinytoml is a C++11 implementation of a TOML parser, which also supports v0.4.0 as of November 2015.

Build Status

Test Results

From the toml-test suite:

126 passed, 0 failed

We also currently maintain (but hopefully not indefinitely!) a fork of the toml-test suite that adds tests for features and clarifications that have been added to the TOML spec more recently than toml-test has been updated. We pass every test there.

148 passed, 0 failed

Compilation

Requires a well conforming C++11 compiler. On OSX this means clang++ with libc++ and libc++abi (the default clang installed with XCode's command line tools is sufficient).

On Linux, you should be able to use g++ >= 4.8.x, or clang++ with libc++ and libc++abi (if your package manager supplies this; most don't).

Compiling the examples can be done with cmake:

mkdir build
cd build
cmake ../
make

Example Usage

To parse a configuration file from a file, you can do the following:

auto config = cpptoml::parse_file("config.toml");

parse_file() returns a (shared pointer to a) cpptoml::table, which you can then query. It will throw an instance of cpptoml::parse_exception in the event that the file failed to parse, and the exception message should contain the line number the error occurred as well as a description of the error.

Obtaining Basic Values

You can find basic values like so:

auto val = config->get_as<int64_t>("my-int");
// val is a cpptoml::option<int64_t>

if (val)
{
    // *val is the integer value for the key "my-int"
}
else
{
    // "my-int" either did not exist or was not an integer
}

To simplify things, you can specify default a default value using the value_or function on the option:

auto baz = config->get_as<double>("baz").value_or(0.5);
// baz is now the double value for key "baz", if it exists, or 0.5 otherwise

cpptoml has extended support for dates and times beyond the TOML v0.4.0 spec. Specifically, it supports

• Local Date (local_date), which simply represents a date and lacks any time information, e.g. 1980-08-02;
• Local Time (local_time), which simply represents a time and lacks any date or zone information, e.g. 12:10:03.001;
• Local Date-time (local_datetime), which represents a date and a time, but lacks zone information, e.g. 1980-08-02T12:10:03.001;
• and Offset Date-time (offset_datetime), which represents a date, a time, and timezone information, e.g. 1980-08-02T12:10:03.001-07:00

Here are the fields of the date/time objects in cpptoml:

• year (local_date, local_datetime, offset_datetime)
• month (local_date, local_datetime, offset_datetime)
• day (local_date, local_datetime, offset_datetime)
• hour (local_time, local_datetime, offset_datetime)
• minute (local_time, local_datetime, offset_datetime)
• second (local_time, local_datetime, offset_datetime)
• microsecond (local_time, local_datetime, offset_datetime)
• hour_offset (offset_datetime)
• minute_offset (offset_datetime)

There are convenience functions cpptoml::offset_datetime::from_zoned() and cpptoml::offset_datetime::from_utc() to convert struct tms to cpptoml::offset_datetimes.

Nested Tables

If you want to look up things in nested tables, there are two ways of doing this. Suppose you have the following structure:

[first-table]
key1 = 0.1
key2 = 1284

[first-table.inner]
key3 = "hello world"

Here's an idiomatic way of obtaining all three keys' values:

auto config = cpptoml::parse_file("config.toml");
auto key1 = config->get_qualified_as<double>("first-table.key1");
auto key2 = config->get_qualified_as<int>("first-table.key2");
auto key3 = config->get_qualified_as<std::string>("first-table.inner.key3");

(Note that, because the TOML spec allows for "." to occur in a table name, you won't always be able to do this for any nested key, but in practice you should be fine.)

A slightly more verbose way of getting them would be to first obtain the individual tables, and then query those individual tables for their keys like so:

auto config = cpptoml::parse_file("config.toml");

auto first = config->get_table("first-table");
auto key1 = first->get_as<double>("key1");
auto key2 = first->get_as<int>("key2");

auto inner = first->get_table("inner");
auto key3 = inner->get_as<std::string>("key3");

The function get_table_qualified also exists, so obtaining the inner table could be written as

auto inner2 = config->get_table_qualified("first-table.inner");

Arrays of Values

Suppose you had a configuration file like the following:

arr = [1, 2, 3, 4, 5]
mixed-arr = [[1, 2, 3, 4, 5], ["hello", "world"], [0.1, 1.1, 2.1]]

To obtain an array of values, you can do the following:

auto config = cpptoml::parse_file("config.toml");

auto vals = config->get_array_of<int64_t>("arr");
// vals is a cpptoml::option<std::vector<int64_t>>

for (const auto& val : *vals)
{
    // val is an int64_t
}

get_array_of will return an option<vector<T>>, which will be empty if the key does not exist, is not of the array type, or contains values that are not of type T.

For nested arrays, it looks like the following:

auto nested = config->get_array_of<cpptoml::array>("mixed-arr");

auto ints = (*nested)[0]->get_array_of<int64_t>();
// ints is a cpptoml::option<std::vector<int64_t>>

auto strings = (*nested)[1]->get_array_of<std::string>();
auto doubles = (*nested)[2]->get_array_of<double>();

There is also a get_qualified_array_of for simplifying arrays located inside nested tables.

Arrays of Tables

Suppose you had a configuration file like the following:

[[table-array]]
key1 = "hello"

[[table-array]]
key1 = "can you hear me"

Arrays of tables are represented as a separate type in cpptoml. They can be obtained like so:

auto config = cpptoml::parse_file("config.toml");

auto tarr = config->get_table_array("table-array");

for (const auto& table : *tarr)
{
    // *table is a cpptoml::table
    auto key1 = table->get_as<std::string>("key1");
}

More Examples

You can look at the files files parse.cpp, parse_stdin.cpp, and build_toml.cpp in the root directory for some more examples.

parse_stdin.cpp shows how to use the visitor pattern to traverse an entire cpptoml::table for serialization.

build_toml.cpp shows how to construct a TOML representation in-memory and then serialize it to a stream.