extension

# 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.

Additionally, these features are disabled by default. To use them, you must explicitly set the corresponding feature flags to `true`. This design choice ensures that non-standard features are only used intentionally.

Some of these features may eventually be merged into the TOML language itself. If a feature is officially adopted, the corresponding experimental implementation in toml11 may be removed in a minor version update after the official feature is implemented.

## `null` #

This feature allows the use of `null` as a value in TOML files.

    a = null
    b = [ 1, 2, 3, null, 5]

To enable this, set the `ext_null_value` flag in `toml::spec` to `true`.

When parsed, it will be treated as `toml::value_t::empty`, similar to a default-constructed value. However, the location information within the file will be set.

`null` is parsed only in the context of values. Therefore, if `null` is used as a key, it will be interpreted as the string `"null"`, as it has been in the standard TOML.

    #include <toml.hpp>

    int main()
    {
        toml::spec spec;
        spec.ext_null_value = true;

        const auto v = toml::parse_str("a = null", spec);

        assert(v.at("a").is_empty());
        assert(v.at("a").is(toml::value_t::empty));

        return 0;
    }

## Hexadecimal Format for Floating-Point Numbers #

This feature allows the use of hexadecimal format for floating-point numbers in TOML files.

    a = 0x1.91eb851eb851fp+1 # 3.14

To enable this, set the `ext_hex_float` flag in `toml::spec` to `true`.

The format follows the `printf` specification for `%a/%A`.

    #include <toml.hpp>

    int main()
    {
        toml::spec spec;
        spec.ext_hex_float = true;

        const auto v = toml::parse_str("a = 0x1.91eb851eb851fp+1", spec);

        assert(v.at("a").is_floating());
        assert(v.at("a").as_floating() == 3.14);

        return 0;
    }

## Suffixes for Integers and Floating-Point Numbers #

This feature allows the use of suffixes for numbers in TOML files. It can be applied to integers and floating-point numbers in decimal notation.

This is particularly useful for displaying units.

    a = 86_400_sec
    b = 3.1416_rad
    c = 10_μm

However, these are purely suffixes and do not perform any unit conversion. If unit conversion is needed, users should implement it by referencing the suffix.

To enable this, set the `ext_num_suffix` flag in `toml::spec` to `true`.

The suffix must be separated from the number by an underscore (`_`).

For clarity, the suffix cannot start with a digit.

    distance = 100_m  # valid
    distance = 10_0m  # invalid
    distance = 10_0_m # valid

The suffix is stored as `std::string suffix` in the format information.

    #include <toml.hpp>

    int main()
    {
        toml::spec spec;
        spec.ext_hex_float = true;

        const auto v = toml::parse_str("a = 86_400_sec", spec);

        assert(v.at("a").is_integer());
        assert(v.at("a").as_integer() == 86400);
        assert(v.at("a").as_integer_fmt().suffix == "sec");

        return 0;
    }