features on toml11

parsing files

Mon, 01 Jan 0001 00:00:00 +0000

Parsing Files and Strings #

In toml11, you can parse files, strings, and byte arrays using toml::parse or toml::try_parse.

Upon success, these functions return a toml::value. Although the parsed file is always a table, the return type is not toml::table. This is because toml::value contains metadata about the file, whereas toml::table is merely an alias for std::unordered_map<std::string, toml::value>. To include metadata, a toml::value is returned instead of a toml::table. The toml::value corresponding to the root of the file will always hold a table_type.

getting values

Mon, 01 Jan 0001 00:00:00 +0000

Retrieving Values #

This section explains how to access the values stored in toml::value.

Accessing Values Using Member Functions #

`is_something` and `as_something` #

toml::value has member functions like is_boolean() and is_integer() which allow you to check the type of the stored value.

Additionally, it has member functions like as_boolean() and as_integer() that allow you to access the value of that type.

For a complete list, refer to the toml::value reference.

error message

Mon, 01 Jan 0001 00:00:00 +0000

Outputting Error Messages #

toml11 provides error messages that include location information within the file when using functions like toml::parse, toml::get<T>/find<T>, and as_integer(), among others.

For instance, if a syntax error in an integer is detected during parsing, an error message might look like this:

[error] bad integer: `_` must be surrounded by digits
 --> internal string at line 64 in file main.cpp
 |
 1 | a = 123__456
 | ^-- invalid underscore
Hint: valid : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755
Hint: invalid: _42, 1__000, 0123

Or, if a type different from the one actually stored is requested:

serializing values

Mon, 01 Jan 0001 00:00:00 +0000

Outputting TOML Files #

Using toml::format, you can convert a toml::value to a string.

#include <toml.hpp>
#include <cassert>

int main()
{
 const toml::value v(toml::table{
 {"a", 42},
 {"b", "foo"},
 });
 const std::string s = toml::format(v);

 const toml::value u = toml::parse_str(s);

 assert(u.at("a").as_integer() == 42);
 assert(u.at("b").as_string() == "foo");

 return 0;
}

If the toml::value contains a table_type, it is interpreted as the root table of the file.

If a toml::value containing anything other than table_type is passed, only that value is formatted.

configuring types

Mon, 01 Jan 0001 00:00:00 +0000

Customizing Types #

The toml::value class uses std::int64_t for integer_type and std::unordered_map<key_type, value_type> for table_type.

However, in some cases, you may want to use boost::multiprecision::int128_t or std::map.

To accommodate this, toml::value is implemented with template parameters that allow you to change the stored types.

Just as std::string is actually an alias for std::basic_string<char, std::char_traits<char>, std::allocator<char>>, toml::value is an alias for toml::basic_value<toml::type_config>.

Here, we will explain the types contained in toml::type_config and how to define a different config type.

toml literal

Mon, 01 Jan 0001 00:00:00 +0000

`_toml` Literal #

With the ""_toml literal, you can format TOML files inline.

#include <toml.hpp>

int main()
{
 using namespace toml::literals::toml_literals;

 const auto v = "a = 42"_toml;

 assert(v.at("a").as_integer() == 42);

 return 0;
}

When including line breaks, raw string literals come in handy.

#include <toml.hpp>

int main()
{
 using namespace toml::literals::toml_literals;

 const auto v = R"(
 a = 42
 b = "foo"
 )"_toml;

 assert(v.at("a").as_integer() == 42);
 assert(v.at("b").as_string() == "foo");

 return 0;
}

If a value is written on its own, that value is returned.

toml spec

Mon, 01 Jan 0001 00:00:00 +0000

TOML Language Version #

You can specify the version of the TOML language and individual feature flags to use with toml::parse or toml::format through toml::spec.

Specifying TOML Version #

You can construct a toml::spec from toml::semantic_version.

#include <toml.hpp>

int main()
{
 toml::spec spec(toml::semantic_version(1, 1, 0));
 return 0;
}

However, to make this shorter, the toml::spec::v() function is provided.

#include <toml.hpp>

int main()
{
 toml::spec spec = toml::spec::v(1, 1, 0);
 return 0;
}

If not specified explicitly, toml::spec::default_version() is used to construct with default values.

extension

Mon, 01 Jan 0001 00:00:00 +0000

TOML Language Extensions #

The TOML language is currently at version v1.0.0, but several new features have been discussed and merged, with ongoing discussions for v1.1.0.

Among the proposed features, some were deemed to have limited use cases, some faced implementation challenges in their proposed form, and others were not adopted at all.

In toml11, we have experimentally implemented a selection of these features. Please note that these features are supported in toml11 but are not supported by other parsers and are unlikely to be supported in the future.

features on toml11

parsing files

Parsing Files and Strings #

getting values

Retrieving Values #

Accessing Values Using Member Functions #

is_something and as_something #

error message

Outputting Error Messages #

serializing values

Outputting TOML Files #

configuring types

Customizing Types #

toml literal

_toml Literal #

toml spec

TOML Language Version #

Specifying TOML Version #

extension

TOML Language Extensions #

`is_something` and `as_something` #

`_toml` Literal #