spec.hpp

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