https://github.com/skystrife/cpptoml
cpptoml is a header-only library for parsing TOML
https://github.com/skystrife/cpptoml
Last synced: 17 days ago
JSON representation
cpptoml is a header-only library for parsing TOML
- Host: GitHub
- URL: https://github.com/skystrife/cpptoml
- Owner: skystrife
- License: mit
- Created: 2013-05-20T10:44:32.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2023-10-07T16:28:09.000Z (about 2 years ago)
- Last Synced: 2025-09-30T22:10:49.281Z (about 1 month ago)
- Language: C++
- Size: 395 KB
- Stars: 599
- Watchers: 25
- Forks: 138
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- AwesomeCppGameDev - cpptoml - only library for parsing TOML (C++)
README
# cpptoml
A header-only library for parsing [TOML][toml] configuration files.
Targets: [TOML v0.5.0][currver] 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][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][ctoml] is a C++11 implementation of a TOML parser, but only
supports v0.2.0.
- [libtoml][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][tinytoml] is a C++11 implementation of a TOML parser, which
also supports v0.4.0 as of November 2015.
## Build Status
[](https://travis-ci.org/skystrife/cpptoml)
## Test Results
From [the toml-test suite][toml-test]:
```
126 passed, 0 failed
```
We also currently maintain (but hopefully not indefinitely!) a [fork of the
toml-test suite][toml-test-fork] 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:
```cpp
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:
```cpp
auto val = config->get_as("my-int");
// val is a cpptoml::option
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`:
```cpp
auto baz = config->get_as("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 tm`s to
`cpptoml::offset_datetime`s.
## 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:
```toml
[first-table]
key1 = 0.1
key2 = 1284
[first-table.inner]
key3 = "hello world"
```
Here's an idiomatic way of obtaining all three keys' values:
```cpp
auto config = cpptoml::parse_file("config.toml");
auto key1 = config->get_qualified_as("first-table.key1");
auto key2 = config->get_qualified_as("first-table.key2");
auto key3 = config->get_qualified_as("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:
```cpp
auto config = cpptoml::parse_file("config.toml");
auto first = config->get_table("first-table");
auto key1 = first->get_as("key1");
auto key2 = first->get_as("key2");
auto inner = first->get_table("inner");
auto key3 = inner->get_as("key3");
```
The function `get_table_qualified` also exists, so obtaining the inner
table could be written as
```cpp
auto inner2 = config->get_table_qualified("first-table.inner");
```
## Arrays of Values
Suppose you had a configuration file like the following:
```toml
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:
```cpp
auto config = cpptoml::parse_file("config.toml");
auto vals = config->get_array_of("arr");
// vals is a cpptoml::option>
for (const auto& val : *vals)
{
// val is an int64_t
}
```
`get_array_of` will return an `option>`, 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:
```cpp
auto nested = config->get_array_of("mixed-arr");
auto ints = (*nested)[0]->get_array_of();
// ints is a cpptoml::option>
auto strings = (*nested)[1]->get_array_of();
auto doubles = (*nested)[2]->get_array_of();
```
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:
```toml
[[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:
```cpp
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("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.
[currver]: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md
[toml]: https://github.com/toml-lang/toml
[toml-test]: https://github.com/BurntSushi/toml-test
[toml-test-fork]: https://github.com/skystrife/toml-test
[ctoml]: https://github.com/evilncrazy/ctoml
[libtoml]: https://github.com/ajwans/libtoml
[tinytoml]: https://github.com/mayah/tinytoml
[boost.toml]: https://github.com/ToruNiina/Boost.toml