Name and Name-Path

Interface

class Name

Represents a single name.

A regular name is always converted into its normalized lower-case form.
A text-name is kept as is.
An index-name is neither normalized nor range checked.

Tested:: NameTest

Predefined Meta-Names

static const Name &meta(Meta metaName)

Parameters:: metaName – The meta-name enum.

static const Name &metaVersion(): Get the “version” meta-name.

static const Name &metaSignature(): Get the “signature” meta-name.

static const Name &metaInclude(): Get the “include” meta-name.

static const Name &metaFeatures(): Get the “features” meta-name.

Public Types

enum class Meta : std::size_t

An enum to address predefined meta-names.

Values:

enumerator Version

enumerator Signature

enumerator Include

enumerator Features

enumerator _count

using MetaNameArray = std::array<const Name, metaNameCount>: The array-type to return all meta-names.

Public Functions

Name() = default: Default constructor.

~Name() = default: Default destructor.

std::strong_ordering operator<=>(const Name &other) const = default

Compare two names lexicographically.

Parameters:: other – The other name to compare.
Returns:: A three-way comparison result.

bool operator==(const Name &other) const = default

Test two names for equality.

Parameters:: other – The other name to compare.
Returns:: true if both names compare equal.

inline NameType type() const noexcept: Get the type of this name.

inline bool empty() const noexcept

Test if this is an empty regular name.

An empty name is not valid and created by the default constructor.

Returns:: true if this name is empty and of type Regular, false otherwise.

inline bool isRegular() const noexcept

Test if this name is of type Regular.

Returns:: true if the name type is Regular, false otherwise.

inline bool isText() const noexcept

Test if this name is of type Text.

Returns:: true if the name type is Text, false otherwise.

inline bool isIndex() const noexcept

Test if this name is of type Index.

Returns:: true if the name type is Index, false otherwise.

inline bool isTextIndex() const noexcept

Test if this name is of type TextIndex.

Returns:: true if the name type is TextIndex, false otherwise.

inline bool isMeta() const noexcept

Test if this is a meta name (regular and starts with ‘@’).

Returns:: true if the name is Regular, non-empty, and begins with an ‘@’ character.

String asText() const noexcept

Get the value as text.

Returns:: The value as text. An index is converted into text.

std::size_t asIndex() const noexcept

Get the value as an index.

Returns:: The value as index, or zero for Root, Regular and Text.

std::size_t pathTextSize() const noexcept: Fast, get the size of the path text.

String toPathText() const noexcept: Create a representation of the name for a name path.

inline std::size_t hash() const noexcept: Get a hash value for this name.

Public Static Functions

static Name createRegular(const String &name)

Create a regular name.

Converts any valid name into its normalized form.
Spacing around the name is not allowed.

Parameters:: name – The name in any valid format. No spacing around the name is allowed.
Throws:: Error – (Syntax, LimitExceeded, Encoding) If there is any problem with the name.

static Name createText(const String &text)

Create a text name.

Parameters:: text – The text name (without the double quotes).
Throws:: Error – (Syntax, LimitExceeded, Encoding) If there is any problem with the name.

static Name createText(String &&text)

Create a text name.

Parameters:: text – The text name (without the double quotes).
Throws:: Error – (Syntax, LimitExceeded, Encoding) If there is any problem with the name.

static Name createIndex(std::size_t index): Create an index name (for list elements).

static Name createTextIndex(std::size_t index): Create a text index name (for text names in a section).

static String normalize(const String &text)

Normalizes and verifies a regular name.

Tests if the name only contains valid characters.
Tests if the name does not exceed the length limit.

Throws:: Error – (Syntax, LimitExceeded, Encoding) in case of any problem.
Returns:: The normalized name.

static void validateText(const String &text)

Verifies a text name.

Test for encoding errors and not allowed zero code-points.
Test if the text exceeds the size limit.

Throws:: Error – (LimitExceeded, Encoding) in case of any problem.

static const MetaNameArray &allMetaNames(): Access a list of all supported meta-names.

class NamePath

A name-path.

This class represents a name path that points to elements in a configuration document. It allows building paths freely, using individual name elements.

Note that, unlike in configuration documents where relative and absolute paths differ by a leading separator, both forms use the same text representation in this API. This lack of differentiation exists because the API treats both forms the same. Addressing a value is always done using relative paths, and the element on which you call the “value” method decides if you start to resolve the path from the root or from a branch in the document.

Tested:: NamePathTest, NamePathLexerTest

Public Types

using iterator = NameList::const_iterator: Iterator over the names in the path.

using const_iterator = NameList::const_iterator: Constant iterator over the names in the path.

using value_type = Name : The element type of the name path.

using reference = const Name&: Reference to a name element.

using const_reference = const Name&: Constant reference to a name element.

using size_type = std::size_t: Unsigned integer type for sizes.

using difference_type = std::ptrdiff_t: Signed integer type for differences.

using pointer = const Name*: Pointer to a name element.

using const_pointer = const Name*: Constant pointer to a name element.

using reverse_iterator = std::reverse_iterator<iterator>: Reverse iterator over the names in the path.

using const_reverse_iterator = std::reverse_iterator<const_iterator>: Constant reverse iterator over the names in the path.

using const_iterator_category = std::forward_iterator_tag: Category type of constant iterators.

using iterator_category = std::forward_iterator_tag: Category type of iterators.

Public Functions

inline NamePath(const Name &name)

Create a name path with one single name.

Parameters:: name – The name.

inline NamePath(Name &&name)

Create a name path with one single name.

Parameters:: name – The name.

inline explicit NamePath(NameList names)

Create a name path from the given sequence of names.

Parameters:: names – A list of names.

inline explicit NamePath(const std::span<const Name> names)

Create a name path from the given sequence of names.

Parameters:: names – A span of names.

inline explicit NamePath(const NameList::const_iterator begin, const NameList::const_iterator end)

Create a name path from the given sequence of names.

Parameters:

begin – The start iterator.
end – The stop iterator.

NamePath() = default: Default constructor.

~NamePath() = default: Default destructor.

std::strong_ordering operator<=>(const NamePath&) const = default: Default comparison.

bool operator==(const NamePath&) const = default: Default comparison.

inline bool empty() const noexcept: Test if this is an empty path.

inline std::size_t size() const noexcept: Get the number of elements in this path.

inline const Name &at(const std::size_t index) const: Access one name in the name path.

inline const Name &front() const: Access the first element.

inline const Name &back() const: Access the last element.

inline bool containsIndex() const noexcept

Test if this path contains an index (index or text-index).

Returns:: true if this path contains any index or text-index element, false otherwise.

inline NameList::const_iterator begin() const noexcept: Get an iterator to the first name in the path.

inline NameList::const_iterator end() const noexcept: Get an iterator to the end of the path.

inline std::span<const Name> view() const noexcept: Access a view of all elements.

inline auto parent() const noexcept: Get the parent path.

template<typename Fwd> inline void append(Fwd &&name) noexcept

Append a name to this path.

Parameters:: name – The name to append to this path.

inline void append(const NamePath &namePath) noexcept

Append another name path to this path.

Parameters:: namePath – The name path to append.

inline void prepend(const NamePath &namePath) noexcept

Prepend another name path in front of this path.

Parameters:: namePath – The name path to prepend.

String toText() const noexcept

Convert this name path into a string.

Returns:: The name path in text form, or an empty string for an empty path or if the path is not valid.

Public Static Functions

static NamePath fromText(const String &text)

Convert a name path from a text.

Convert name paths for accessing value elements, therefore, it supports the name path extensions for the API. Create a name path from the given text: e.g. “main.server[2].path”, or just “main”, “[1]”, “"text"”, “""[1]” as the path may start at any value element in the value-tree.

Parameters:: text – The path in its text form.
Throws:: Error – (Syntax, Encoding, Limit) In case of any problem with the name.

enum class erbsland::conf::NameType : uint8_t

The type of name.

Tested:: NameTypeTest

Values:

enumerator Regular: A regular name: name.

enumerator Text: A text name: “text”.

enumerator Index: An index name: [<index>].

enumerator TextIndex: A text index name: “”[<index>].

using erbsland::conf::NamePathLike = std::variant<Name, NamePath, String, std::size_t>: A name-path or convertible value.

NamePath erbsland::conf::toNamePath(const NamePathLike &namePathLike): Convert a name-path like value into a name path.