A reader and writer for SOML, a config format for humans, in one C++26 header
Note
The format is a draft.
- One file,
soml.hpp, with only standard-library dependencies - Strict validation of duplicate keys, numeric and temporal ranges, UTF-8, control characters, and nesting
- Reference-compatible errors for every invalid conformance case, with code frames
- Exact int64 values, correctly rounded floats, calendar dates, and nanosecond instants and durations
- Typed decoding and encoding of structs, containers,
std::optional, enums, andstd::chronotypes, with C++26 static reflection where the compiler has it - Constant-expression support for checking configs with
static_assert - Errors return
std::expected; allocation and size-limit failures can throwstd::bad_allocorstd::length_error, and custom converter exceptions propagate - Bounds-checked parsing with a 100-level nesting limit, tested with sanitizers, allocation failures, fuzzing, and differential checks
Copy include/soml.hpp into your project, or use CMake:
include(FetchContent)
FetchContent_Declare(soml GIT_REPOSITORY https://github.com/soml-lang/soml-cplusplus GIT_TAG main)
FetchContent_MakeAvailable(soml)
target_link_libraries(app PRIVATE soml::soml)Requires C++26 (-std=c++26 or -std=c++2c), a 64-bit target, and a standard library with floating-point std::from_chars and std::to_chars (macOS 26 or later on Apple platforms). CMake integration requires CMake 4.3 or later. Tested with Apple Clang 21 (Xcode 27), LLVM Clang 23, and GCC 16, using libc++ and libstdc++. Static reflection requires GCC 16 with -freflection.
With CMake, Ninja, and a compiler with module scanning, enable SOML_MODULE before adding the library and link soml::module:
set(SOML_MODULE ON CACHE BOOL "Build the SOML module")
FetchContent_MakeAvailable(soml)
target_link_libraries(app PRIVATE soml::module)#include <string>
import soml;
int main() {
const auto document = soml::parse("port: 8080");
return document && (*document)["port"].value_or(0) == 8080 ? 0 : 1;
}Build with cmake -G Ninja -S . -B build/modules -DSOML_MODULE=ON -DCMAKE_CXX_COMPILER=clang++. Use LLVM Clang with clang-scan-deps, or GCC with module scanning support; tested with LLVM 23 and GCC 16. Apple Clang supports the header, but CMake cannot scan its modules. The library and consumers require C++26. Include standard headers before import soml;; GCC reflection also requires #include <meta> before importing and -freflection for both library and consumer.
With SOML_INSTALL=ON, installation exports both targets and the module source, letting CMake build the consumer's compiler-specific interface. Header and module translation units can be linked together; soml::fields, soml::enum_names, and soml::converter remain customizable.
Local recipes package the header target soml::soml; they are not published to a registry. Use CMake directly for the named module.
For Conan 2, create the package and run its consumer test:
conan profile detect
conan create . -s compiler.cppstd=26Consumers require soml/0.1.0, select C++26, and use Conan's CMakeDeps and CMakeToolchain generators. In CMake, call find_package(soml CONFIG REQUIRED) and link soml::soml.
For vcpkg, run from this checkout:
vcpkg install soml --overlay-ports=packaging/vcpkg --no-binarycachingKeep this overlay in its repository location: it packages the current checkout. After changing the source, remove and reinstall soml; keep binary caching disabled because the source lives outside the overlay port directory. Configure consumers with the vcpkg toolchain, call find_package(soml CONFIG REQUIRED), and link soml::soml with a C++26 compiler.
#include <soml.hpp>
auto document = soml::parse(R"(
# The edge service.
name: 'api-gateway'
replicas: 3
launch-date: 2027-09-19
timeout: 1m30s
postgres: {host: 'db.internal', port: 5432}
)");
if (!document) {
std::println(stderr, "{}", document.error());
return 1;
}
std::println("{}", (*document)["name"].value_or("unnamed"));
//=> api-gateway
std::println("{}", (*document)["postgres"]["port"].value_or(0));
//=> 5432
std::println("{}", (*document)["timeout"].as<std::chrono::seconds>()->count());
//=> 90
std::println("{}", (*document)["missing"]["deeper"].value_or(8080));
//=> 8080soml::parse also accepts std::vector<char>, reading its exact size without a terminating NUL.
The result is a soml::value holding an object or array. It owns its strings, so the input can be freed after parsing.
value["key"] and value[index] return a soml::view, empty for missing entries or mismatched types, so lookups chain without intermediate checks. as<T>() returns std::optional<T>; value_or(fallback) returns the value or fallback. Conversions are strict: ints and floats stay distinct, and as<std::uint8_t>() is empty for 300.
Views, pointers from find and get_if, and as<std::string_view>() borrow the owner's storage. Keep it alive and avoid replacing or moving referenced values or strings. Adding members or items can invalidate references when storage reallocates; erasing an element invalidates references to it and following elements.
get_if<T>() gives a pointer to the value as one of its types, or nullptr:
const soml::value document = *soml::parse("a: 1\nb: [true, 'x']");
for (const auto& [key, item] : *document.get_if<soml::object>()) {
std::println("{}: {}", key, item.type());
}
//=> a: int
// b: arrayMembers are in the order they appear in the text.
const soml::value document = soml::object{
{"name", "api-gateway"},
{"replicas", 3},
{"timeout", soml::duration{90s}},
{"labels", soml::array{"prod", "eu-west"}},
};
std::print("{}", *soml::write(document));
//=> name: 'api-gateway'
// replicas: 3
// timeout: 1m30s
// labels: [
// 'prod'
// 'eu-west'
// ]soml::write preserves member order and otherwise follows canonical form: one entry per line, tabs, canonical spellings, and no commas or comments.
soml::write_canonical also sorts every object's keys, giving equal values identical bytes for hashing, signing, or comparison:
std::print("{}", *soml::write_canonical(document));
//=> labels: [
// 'prod'
// 'eu-west'
// ]
// name: 'api-gateway'
// replicas: 3
// timeout: 1m30sBoth return std::expected<std::string, soml::error> and validate UTF-8, carriage returns, NaN, dates, instants, duplicate keys, nesting, and the collection root. Errors name the path, such as servers[1].weight: NaN is not a SOML value.
Pass a soml::array or soml::object directly to write it without copying it into a soml::value first. This also works with the append overloads.
Append with soml::write(document, output) or soml::write_canonical(document, output), returning std::expected<void, soml::error>. Both render before appending, leaving the destination unchanged on invalid values or allocation failure:
std::string output = "# Generated configuration\n";
auto appended = soml::write(document, output);soml::format(text) preserves comments, member order, literal spelling, and an unbraced root. It applies the spec's formatting rules: tabs, one space between tokens, no trailing whitespace, and one final LF. Inline containers stay inline.
auto formatted = soml::format("port: 0x1F90 # HTTP\n");
//=> "port: 0x1F90 # HTTP\n"
auto changed = soml::edit("port: 8080 # HTTP\n", {"port"}, 9090);
//=> "port: 9090 # HTTP\n"
auto added = soml::edit("server: {host: 'localhost'}\n", {"server", "port"}, 8080);
//=> "server: {host: 'localhost', port: 8080}\n"
auto removed = soml::edit("a: 1\nb: 2\n", {"a"}, std::nullopt);
//=> "b: 2\n"Both return std::expected<std::string, soml::error>. Editing changes the requested member or item and its owned comments and commas. New values use the writer's spelling and stay inline in an inline parent. Use nullptr to write SOML null, or std::nullopt to remove a value. Compare the result with the input to detect a change.
A path contains owning string keys and std::size_t indexes, such as {"servers", std::size_t{0}, "port"}. Pass a stored std::vector<soml::path_segment> or other contiguous range as a span. Missing members and intermediate objects are added. Setting an index at an array's size appends; larger indexes fail. Empty paths, keys on arrays, indexes on objects, and paths through scalars fail. Removing a missing value leaves the source unchanged.
Formatting and editing are runtime APIs. They validate input with the parser, then record source spans separately, so ordinary parsing incurs no layout cost.
struct postgres {
std::string host;
std::uint16_t port = 5432;
};
struct config {
std::string name;
int replicas = 1;
std::chrono::seconds timeout{30};
std::vector<std::string> labels;
postgres database;
};
auto result = soml::decode<config>(R"(
name: 'api-gateway'
timeout: 1m30s
labels: ['prod', 'eu-west']
database: {host: 'db.internal'}
)");
std::println("{} {} {} {}", result->replicas, result->timeout.count(), result->database.host, result->database.port);
//=> 1 90 db.internal 5432
std::print("{}", *soml::encode(*result));
//=> name: 'api-gateway'
// replicas: 1
// timeout: 1m30s
// labels: [
// 'prod'
// 'eu-west'
// ]
// database: {
// host: 'db.internal'
// port: 5432
// }Missing members keep their defaults. Unknown keys are errors; pass {.ignore_unknown_keys = true} to skip them. Typo suggestions are best effort for keys up to 200 bytes, keeping diagnostics bounded for untrusted input. Values that do not fit also fail. Errors name the path and source position:
std::println("{}", soml::decode<config>("database: {port: 70000}").error());
//=> database.port: The int 70000 is outside the range of the type, 0 to 65535 at line 1, column 18
std::println("{}", soml::decode<config>("replicas: 3\nreplica: 4").error());
//=> replica: Unknown key replica, which the type has no field for. Did you mean replicas? at line 2, column 1soml::encode_canonical writes canonical form, and soml::from_value and soml::to_value convert between a type and a soml::value. Decoding from text requires a movable or copyable result; from_value also supports immovable results.
from_value<T>(std::move(document)) and to_value(std::move(source)) transfer owned strings and containers, including those nested in typed containers, optionals, and structs. decode transfers ownership from its temporary parsed document. encode(std::move(source)) and encode_canonical(std::move(source)) also allow ownership transfer during conversion. Lvalues and const rvalues are copied. Moved sources remain valid with unspecified values, including after a failed conversion; a native type mismatch leaves the source unchanged.
Rvalue encoding can also move values reached through reference members. Pass an lvalue when those values should retain their contents.
With GCC 16 and -freflection, structs need nothing more. Annotations change the keys:
struct [[=soml::kebab_case]] server {
int max_connections = 100; // Read from `max-connections`.
[[=soml::key("log")]] level log_level = level::info;
};Without static reflection, list the fields once:
template<>
inline constexpr auto soml::fields<config> = std::tuple{
soml::field{"name", &config::name},
soml::field{"replicas", &config::replicas},
soml::field{"timeout", &config::timeout},
soml::field{"labels", &config::labels},
soml::field{"database", &config::database},
};Enums are read and written by name: from reflection, or from soml::enum_names:
template<>
inline constexpr auto soml::enum_names<level> = std::array{
std::pair{level::debug, "debug"sv},
std::pair{level::info, "info"sv},
};Any other type gets a soml::converter specialization with from_value and to_value. The built-in types:
| C++ | SOML |
|---|---|
bool |
bool |
| Every integer type, except the character types | int, range-checked both ways |
double, float, long double |
float, never an int |
std::nullptr_t |
null |
std::string |
string (std::string_view is written, and value.as<std::string_view>() reads one in place) |
soml::date (std::chrono::year_month_day) |
date, with strict calendar validation and years 0001 through 9999 |
std::chrono::duration |
duration, rounded to the nearest nanosecond with ties to even, then range-checked; built-in integer counts up to 64 bits |
std::chrono::sys_time |
instant, range-checked; built-in integer counts up to 64 bits; precision rules below |
soml::instant, soml::value, soml::object |
as themselves |
std::optional<T> |
null, or a missing member |
std::vector, std::deque, std::list, std::array |
array (a std::array needs exactly its size) |
std::map, std::unordered_map, std::flat_map with string keys |
object |
| Enums | string |
| Structs | object |
Sequence and map decoding require default-constructible, move-constructible containers with move-constructible elements. Mapped values must also be move-assignable. Map decoding rejects distinct SOML keys when the target map treats them as equivalent.
soml::to_value(float) and typed encoding use the float's shortest round-trip decimal, so 0.1f writes as 0.1. Direct soml::value{0.1f} construction preserves the exact widened binary value. Decoding into float uses ordinary C++ narrowing and may depend on the floating-point rounding mode. A wider long double decodes binary64 exactly and narrows when encoded: precision may be lost, finite magnitudes above double's maximum and nonzero values that round to zero are rejected. NaN is rejected; infinities are supported.
A soml::date preserves its year, month, and day without conversion through an instant. Quoted date text stays a string. Native year_month_day values can be invalid; typed encoding and every writer reject invalid dates and years outside 0001 through 9999.
Integer representations for std::chrono::duration and std::chrono::sys_time must be built-in integer types of at most 64 bits. Custom periods whose nanosecond conversion ratios overflow std::intmax_t are unsupported. Decoding an integral duration count requires an exact conversion, so 1.5s is an error for std::chrono::seconds. Floating duration counts may lose precision when decoding. Encoding rounds to the nearest nanosecond with ties to even, then checks the range. Floating counts are first scaled using long double arithmetic, which may lose precision. Constructing a soml::value directly accepts only soml::duration; use soml::to_value for other duration types so overflow is refused. Decoding an instant into an integral sys_time count must be exact; a floating count may lose precision. Encoding sys_time requires an integral count and floors subnanosecond times to nanoseconds, including negative times. Encoded durations and instants must fit their SOML ranges.
const std::string_view text = "name: 'api'\nport: 80 80\n";
const soml::error error = soml::parse(text).error();
std::println("{}", error);
//=> Expected a line break before the next entry, but found “8” at line 2, column 10
std::println("{}", error.code_frame(text));
//=> 1 | name: 'api'
// > 2 | port: 80 80
// | ^A soml::error has:
code:syntaxortoo_deepwhen reading,invalid_valueortoo_deepwhen writing,type_mismatch,out_of_range, orunknown_keywhen decoding into a type, andinvalid_valueorout_of_rangewhen encoding one.message: what is wrong, in the reference implementation's words.offset,line, andcolumnfor a parsing ordecodeerror: the byte offset, and the 1-based line and column, with the column counted in Unicode scalar values. Decoding positions point to the value, or the key for an unknown key. They are 0 forfrom_valueand writing errors, or unresolved or ambiguous paths.pathfor a writing or decoding error, such asservers[1].port.
description() gives the message with its path and position when available, which is also what std::format gives. C1 and bidirectional controls and Unicode line and paragraph separators appear as U+FFFD without changing the original message or path. code_frame(text) shows up to three lines with a caret; invalid UTF-8, controls other than tabs and line feeds, bidirectional marks, and Unicode line and paragraph separators appear as U+FFFD.
The first error in the text is reported, except that whole-input checks run first: invalid UTF-8, then a byte order mark, then a raw control character.
soml::parse, soml::write, soml::write_canonical, soml::decode, and soml::encode work in constant expressions. Their allocated values cannot escape the expression, but extracted scalars can:
static_assert(soml::parse("port: 8080")->find("port")->as<int>() == 8080);
static_assert(!soml::parse("port: 0x1g"));The conformance suite also runs in constant expressions. For documents near the 100-level nesting limit, pass -fconstexpr-depth=4096.
With #embed, a config file in the source tree can be checked when the program is built:
constexpr char8_t config_text[] = {
#embed "config.soml"
};
static_assert(soml::parse(std::u8string_view{config_text, sizeof(config_text)}).has_value());Use char8_t because #embed emits bytes from 0 to 255, which may not fit a char. For configs larger than a few kilobytes, raise the constexpr limit: -fconstexpr-steps=100000000 with Clang or -fconstexpr-ops-limit=1000000000 with GCC. Clang currently warns that C++ #embed is an extension.
| SOML | C++ |
|---|---|
| null | std::nullptr_t |
| bool | bool |
| int | std::int64_t |
| float | double, finite or infinite |
| string | std::string, UTF-8 |
| date | soml::date, an alias for std::chrono::year_month_day: Gregorian components, with no time or timezone |
| instant | soml::instant: seconds since 1970-01-01T00:00:00Z and nanoseconds, with conversions to and from std::chrono::sys_time, which cannot hold the years 0001 to 9999 in nanoseconds |
| duration | soml::duration, which is std::chrono::nanoseconds |
| array | soml::array, which is std::vector<soml::value> |
| object | soml::object: members in order, with find, contains, operator[], insert_or_assign, and erase |
soml::value is a std::variant of these, in this order, which variant() gives for std::visit. Equality is the spec's: members in any order, and 0.0 equal to -0.0.
For large objects, move a std::vector<soml::member> into soml::object for O(n log n) construction. Duplicate keys keep their first position and last value, as with the initializer-list constructor. Individual insert_or_assign calls use linear lookup.
std::vector<soml::member> members{{"host", "localhost"}, {"port", 8080}};
soml::object settings{std::move(members)};Parsing bounds-checks input, limits nesting to 100 levels, and takes linear or n log n time and linear memory. Limit the size of untrusted files. Duplicate-key checks sort keys, avoiding hash flooding. A value uses 32 bytes with libc++ or 40 with libstdc++; a member uses 56 or 72. Long strings and containers may allocate separately. At the nesting limit, reading and writing use about 24 KB of stack in optimized builds or 130 KB in unoptimized builds.
A float below 10^-307 takes about 0.5 µs with libc++: the library converts it itself because libc++'s std::from_chars can take up to a millisecond.
Diagnostic messages display invisible and unassigned characters by their Unicode 17.0 code points. The character tables are regenerated with python3 tools/generate-unicode.py from checksum-verified Unicode data.
Word-sized scanning uses bounded std::memcpy; reinterpret_cast only views byte and UTF-8 buffers through char, which may alias their storage. Time conversions use checked 128-bit arithmetic. These operations are tested with sanitizers. With -fno-exceptions, standard-library allocation failure terminates instead of throwing.
- A struct with a base class is not read by static reflection, which would leave out the base's members. Give it
soml::fields. - A
std::chrono::sys_timewith a floating-point count can be read from an instant, but not written, because its value may not be a whole number of nanoseconds. - Object lookup is a linear scan, which is the fastest choice for the small objects of a config file. Copy a huge object into a map to look it up often.
-ffast-math: the compiler may then assume that no value is NaN, so the writer may not detect a NaN in a value built in code.
Processor time per document on an Apple M4 Pro, Apple Clang 21 with -O2, for the shared benchmark fixtures, each with the same data in SOML, JSON, and TOML: service (3 KB), platform (35 KB, a quarter comments), and earthquakes (733 KB, instants and floats). Reading builds each library's tree, and writing indents it as a person would. simdjson reads into an immutable tape and has no such writer.
| soml.hpp, SOML | nlohmann/json, JSON | simdjson, JSON | toml++, TOML | |
|---|---|---|---|---|
| Read service | 7.6 µs | 14.8 µs | 925 ns | 40.0 µs |
| Write service | 4.0 µs | 7.7 µs | – | 13.5 µs |
| Read platform | 54.4 µs | 103.8 µs | 5.9 µs | 382.2 µs |
| Write platform | 23.4 µs | 51.3 µs | – | 82.6 µs |
| Read earthquakes | 2.07 ms | 3.91 ms | 262.2 µs | 10.55 ms |
| Write earthquakes | 1.57 ms | 2.03 ms | – | 5.42 ms |
Measured on 2026-10-27. Each result is the fastest of five runs of at least 100 ms of processor time.
Reading also checks every rule of the spec, such as UTF-8, duplicate keys, and the ranges of ints, floats, dates, instants, and durations. Run it with cmake -S . -B build/bench -DSOML_BENCH_COMPARE=ON && cmake --build build/bench --target soml-bench && build/bench/soml-bench, which downloads the other libraries at pinned releases and checks them by hash.
The benchmark also decodes complete service and earthquake fixtures into nested structs with owning strings and vectors, durations, instants, and optional members. It verifies every source value before timing and uses soml::fields, requiring no reflection:
| Fixture | Parse and decode | Convert an already parsed value | Struct to value |
|---|---|---|---|
| service | 9.1 µs | 1.6 µs | 1.9 µs |
| earthquakes | 2.73 ms | 763.2 µs | 427.0 µs |
Editing replaces one array item with a complete fixture, preserving the other item. The benchmark validates the result before timing:
| Fixture | Inline parent | Multiline parent |
|---|---|---|
| service | 3.8 µs | 5.0 µs |
| platform | 20.0 µs | 26.7 µs |
| earthquakes | 1.45 ms | 1.71 ms |
To benchmark without downloading comparison libraries, use -DSOML_BENCH=ON.
The standalone benchmark also validates and times integer arrays, whole-float arrays, duplicate-heavy object batches, ordered object equality, key distance, ASCII string classification after an early quote, and code-frame windows on long lines. Bulk object construction compacts duplicates in place, saving an allocation while retaining the input vector's capacity.
| Operation | Time |
|---|---|
| Write 4096 integers | 49.5 µs |
| Write 4096 whole floats | 85.8 µs |
| Compact 4096 members to 128 | 288.8 µs |
| Compare 128 ordered members | 490 ns |
| Compare 126 matching members and a reordered suffix | 505 ns |
| Key distance with a transposition | 27 ns |
| Classify 1 MB after an early quote | 64.8 µs |
| Frame the start of a 1 MB line | 478 ns |
The hot paths skip already checked work: scanners jump directly to the first special byte of each word, short exponent floats use bounded arithmetic, and ordered objects avoid sorting and scratch allocations. Typed decoding moves owned strings and containers out of its temporary document, and optional reads avoid constructing errors that would be discarded.
cmake -S . -B build && cmake --build build && ctest --test-dir build --output-on-failureThe CI workflow tests Apple Clang, LLVM, GCC reflection, sanitizers, installed header/module consumers, and Conan/vcpkg recipes on the Xcode 27 runner.
Tests cover the APIs, README examples, each allocation failing in turn, and conformance (requires Node.js). The improvements suite adds deterministic generated cases for integer rendering, batch construction, object equality, key distance, and nested edits, alongside focused ownership, Unicode, and formatting checks. The hardening suite checks malformed UTF-8, conversion identities, unusual edit keys, temporal boundaries, and diagnostic controls. The refinement suite checks exact diagnostic windows, mixed valid and invalid UTF-8 escaping, fractional spellings, enum bounds, and bounded typo suggestions. Allocation tests also verify storage reuse and allocation budgets. Other configurations:
# AddressSanitizer, UndefinedBehaviorSanitizer, and the standard library's hardening
cmake -S . -B build/sanitize -DCMAKE_BUILD_TYPE=Debug -DSOML_SANITIZE=ON
# GCC, with static reflection
cmake -S . -B build/gcc -DCMAKE_CXX_COMPILER=g++-16
# libFuzzer, with Homebrew's LLVM on macOS
cmake -S . -B build/fuzz -DSOML_FUZZ=ON -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ && cmake --build build/fuzz --target soml-fuzz
mkdir -p build/fuzz/corpus && find tests/conformance -name '*.soml' | while read -r file; do cp "$file" "build/fuzz/corpus/$(echo "$file" | tr / _)"; done
build/fuzz/soml-fuzz -dict=fuzz/soml.dict -max_len=4096 build/fuzz/corpus
# Differential testing against ../soml-javascript (needs Node.js 26 or later)
SOML_TAGGED=build/soml-tagged node tests/differential.js 20000 1tests/conformance is a copy of the suite in the soml spec repository:
valid/**/name.somlmust parse to the value inname.json, and serialize withsoml::write_canonicalto exactlyname.canonical.soml.invalid/**/name.somlmust be rejected, at the line and column, and with the message, intests/conformance/invalid-reasons.json.valid/**/name.formatted.somlmust matchsoml::formatexactly; formatting must preserve values and be idempotent.edit/checks exact edited text and invalid paths throughsoml::edit.
To update the copy, check out the spec repository next to this one and run ../soml/sync-conformance.sh tests/conformance.