spec.hpp #

spec.hpp defines classes for specifying the version of TOML.

`toml::semantic_version` #

semantic_version is a class that stores version information.

namespace toml
{
struct semantic_version
{
    constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;

    std::uint32_t major;
    std::uint32_t minor;
    std::uint32_t patch;
};

constexpr semantic_version
make_semver(std::uint32_t major, std::uint32_t minor, std::uint32_t patch) noexcept;

constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;

std::ostream& operator<<(std::ostream& os, const semantic_version& ver);
} //toml

Member Functions #

Constructor #

constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;

Constructs a semantic_version instance with the specified major, minor, and patch version numbers.

Non-Member Functions #

Comparison Operators #

constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;

Compares two semantic_version instances according to semantic versioning rules.

Stream Operator #

std::ostream& operator<<(std::ostream& os, const semantic_version& ver);

Outputs the version in the format {major}.{minor}.{patch}.

`to_string` #

std::string to_string(const semantic_version& ver);

Converts the version to a string in the format {major}.{minor}.{patch}.

`toml::spec` #

spec is a class that stores TOML version information.

struct spec
{
    constexpr static spec default_version() noexcept;

    constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;

    constexpr explicit spec(const semantic_version& semver) noexcept;

    semantic_version version; // toml version

    // diff from v1.0.0 -> v1.1.0
    bool v1_1_0_allow_control_characters_in_comments;
    bool v1_1_0_allow_newlines_in_inline_tables;
    bool v1_1_0_allow_trailing_comma_in_inline_tables;
    bool v1_1_0_allow_non_english_in_bare_keys;
    bool v1_1_0_add_escape_sequence_e;
    bool v1_1_0_add_escape_sequence_x;
    bool v1_1_0_make_seconds_optional;

    // library extensions
    bool ext_hex_float;  // allow hex float
    bool ext_num_suffix; // allow number suffix
    bool ext_null_value; // allow null value
};

Member Functions #

Constructor #

constexpr explicit spec(const semantic_version& semver) noexcept;

Constructs a spec with the specified TOML version.

Supports TOML v1.0.0 and TOML v1.1.0.

`default_version()` #

constexpr static spec default_version() noexcept;

Constructs a spec with the default version.

Used as the default value for toml::parse and toml::format.

In toml11 v4.0.0, the value is v1.0.0.

`v(major, minor, patch)` #

constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;

Constructs a spec with the specified version.

Member Variables #

Each flag is automatically set to true when the specified version includes the corresponding feature.

You can modify these flags to change the behavior of toml::parse and toml::format.

Some features of TOML v1.1.0 are still under fairly lengthy discussion and may still be reverted.
If they are indeed reverted, toml11 will remove those features in a minor version upgrade or move them to a corresponding later version.
As such, any features related to future versions should be considered unstable.

Example #

auto spec = toml::spec::v(1, 0, 0);
// Allow newlines in inline tables in addition to v1.0.0 features.
// Other v1.1.0 features are not enabled.
spec.v1_1_0_allow_newlines_in_inline_tables = true;

auto input = toml::parse("input_file.toml", spec);

`v1_1_0_allow_control_characters_in_comments` #

bool v1_1_0_allow_control_characters_in_comments;

Allows most control characters in comments.

Added in TOML v1.1.0.

`v1_1_0_allow_newlines_in_inline_tables` #

bool v1_1_0_allow_newlines_in_inline_tables;

Allows newlines in inline tables.

Added in TOML v1.1.0.

`v1_1_0_allow_trailing_comma_in_inline_tables` #

bool v1_1_0_allow_trailing_comma_in_inline_tables;

Allows trailing commas in inline tables.

Added in TOML v1.1.0.

`v1_1_0_add_escape_sequence_e` #

bool v1_1_0_add_escape_sequence_e;

Allows \e to represent the ESC character.

Added in TOML v1.1.0.

`v1_1_0_add_escape_sequence_x` #

bool v1_1_0_add_escape_sequence_x;

Allows \xHH to represent a single byte character.

Added in TOML v1.1.0.

`v1_1_0_make_seconds_optional` #

bool v1_1_0_make_seconds_optional;

Makes the seconds component in time optional.

Unspecified seconds default to 0.

Added in TOML v1.1.0.

`ext_hex_float` #

bool ext_hex_float;

This is a language extension specific to toml11.

It is initialized to false regardless of the specified version. You must explicitly set it to true if you want to use it.

Allows hexadecimal representation of floating-point numbers.

The hexadecimal representation conforms to the printf format specifier %a/%A.

hexf = 0xC0FFEEp-10

toml::format will format using hexadecimal notation only if the passed toml::spec has ext_hex_float set to true. If the format specifier indicates hex but the toml::spec passed to toml::format has ext_hex_float set to false, the hexadecimal specification is ignored, and the number is output in decimal notation with maximum precision.

`ext_num_suffix` #

bool ext_num_suffix;

This is a language extension specific to toml11.

It is initialized to false regardless of the specified version. You must explicitly set it to true if you want to use it.

Allows the addition of suffixes to decimal integers and floating-point numbers. This does not apply to hexadecimal, octal, or binary notations.

There must be an _ separator between the number and the suffix.

The suffix cannot start with a digit to avoid confusion with the numeric part.

distance = 10_m   # valid
distance = 10_2m  # invalid
distance = 10_2_m # valid

The suffix is stored in the format information as std::string suffix. The _ separating the number from the suffix is not included in the suffix.

toml::value distance = toml::find(input, "distance");
assert(distance.as_integer_fmt().suffix == std::string("m"));

toml::format will format the value with the suffix only if the passed toml::spec has ext_num_suffix set to true.

The suffix follows the grammar defined as:

non-digit-graph = ALPHA / non-ascii
graph           = ALPHA / DIGIT / non-ascii
suffix          = _ non-digit-graph *( graph / ( _ graph ) )

`ext_null_value` #

bool ext_null_value;

This is a language extension specific to toml11.

Allows the use of null as a value.

A toml::value specified as null will have no value, and is_empty() will return true.

toml::format will format it as null only if the passed toml::spec has ext_null_value set to true. Otherwise, toml::format will terminate with an error.

spec.hpp #

toml::semantic_version #

Member Functions #

Constructor #

Non-Member Functions #

Comparison Operators #

Stream Operator #

to_string #

toml::spec #

Member Functions #

Constructor #

default_version() #

v(major, minor, patch) #

Member Variables #

Example #

v1_1_0_allow_control_characters_in_comments #

v1_1_0_allow_newlines_in_inline_tables #

v1_1_0_allow_trailing_comma_in_inline_tables #

v1_1_0_add_escape_sequence_e #

v1_1_0_add_escape_sequence_x #

v1_1_0_make_seconds_optional #

ext_hex_float #

ext_num_suffix #

ext_null_value #

`toml::semantic_version` #

`to_string` #

`toml::spec` #

`default_version()` #

`v(major, minor, patch)` #

`v1_1_0_allow_control_characters_in_comments` #

`v1_1_0_allow_newlines_in_inline_tables` #

`v1_1_0_allow_trailing_comma_in_inline_tables` #

`v1_1_0_add_escape_sequence_e` #

`v1_1_0_add_escape_sequence_x` #

`v1_1_0_make_seconds_optional` #

`ext_hex_float` #

`ext_num_suffix` #

`ext_null_value` #