Configuration Language

Configuration Parsing

erbsland::conf::Parser reads one closed source and returns a typed erbsland::conf::Document. Each parser instance is reentrant and can be used independently in one thread. Use a separate instance in each concurrently executing thread.

Parsing Files and Text

The convenience methods cover the common file and in-memory cases:

using namespace el::text::literals;

el::conf::Parser parser;
auto fromFile = parser.parseFileOrThrow(el::path::Path{"settings.elcl"_el});
auto fromText = parser.parseTextOrThrow("[server]\nport = 8443\n"_el);

The equivalent source-level API is useful when an application implements its own source:

auto source = el::conf::Source::fromString("enabled = yes\n"_el);
auto document = parser.parseOrThrow(source);

parseOrThrow reports every failure as erbsland::conf::ConfError. parse returns a null document instead and stores its erbsland::conf::ConfErrorContext for erbsland::conf::Parser::lastError. Regular-expression literals are retained without compilation, so invalid pattern syntax is reported later as re::RegExError when the expression is compiled or first used.

Customization

Includes are resolved by a erbsland::conf::SourceResolver and approved by an erbsland::conf::AccessCheck. The defaults implement restricted file-based includes. A erbsland::conf::SignatureValidator can be installed for signed documents. Set these collaborators before starting a parse; null resolver or access-check values disable include handling.

Configuration Documents

A erbsland::conf::Document is the root of a parsed configuration value tree. It provides the complete erbsland::conf::Value interface and can also produce a flat map from absolute name paths to values. Values retain their source location, allowing errors and diagnostics to point back to the input after parsing has finished.

Programmatic Construction

erbsland::conf::DocumentBuilder creates the same tree structure without parsing text. Sections must be introduced before values are added to them; intermediate section maps are created where required. The builder rejects name collisions and invalid document structures with a syntax error.

using namespace erbsland::text::literals;

erbsland::conf::DocumentBuilder builder;
builder.addSectionMap("server"_el);
builder.addText("name"_el, "gateway"_el);
builder.addInteger("port"_el, 8443);
auto document = builder.getDocumentAndReset();

Single names are relative to the most recently added section. A multi-component name path selects its section explicitly. Index and text-index components cannot be used by this builder. Scalar overloads accept the same Core types returned by Value. Regular expressions must be compiled before they are added, and a null re::RegExPtr is rejected.

Configuration Sources

A erbsland::conf::Source supplies UTF-8 configuration text line by line. A source object is deliberately lightweight and closed when created. The parser opens it once, reads until the end, then closes it and releases any external resources. Returned lines are owning Core strings and remain valid after subsequent reads. Sources also provide best-effort excerpts for diagnostics. In-memory sources scan only the requested area, while stream sources retain the five most recently read lines and may read up to two immediately following context lines when an error excerpt is requested.

Built-in Sources

Use erbsland::conf::Source::fromFile for a lazy file source and erbsland::conf::Source::fromString for in-memory text:

using namespace el::text::literals;

auto fileSource = el::conf::Source::fromFile(erbsland::path::Path{"settings.elcl"_el});
auto textSource = el::conf::Source::fromString("answer = 42\n"_el);

el::conf::Parser parser;
auto document = parser.parseOrThrow(textSource);

Custom sources should defer I/O and heavy allocation to open(), report I/O failures as configuration errors, include newline sequences in returned lines, and make an empty line value signal the end of input. Each source has a stable erbsland::conf::SourceIdentifier for locations and access decisions.

Configuration Source Resolution

Include directives describe a source to load relative to the source containing the directive. A erbsland::conf::SourceResolver receives this context and returns one or more closed source objects in deterministic order. It resolves names only; each result is still passed through the configured access check before the parser opens it.

The default erbsland::conf::FileSourceResolver implements file includes, including supported patterns and recursive requests. Relative paths are based on the including file. Its results work with erbsland::conf::FileAccessCheck, which applies the security boundary independently.

Applications can install another resolver with erbsland::conf::Parser::setSourceResolver, for example to address embedded resources or a database. A custom resolver should create lightweight sources and preserve a stable source identifier; it should not open or parse them itself.

Configuration Access Control

Every source requested by the parser is passed to an erbsland::conf::AccessCheck before it is opened. This includes the initial source. The check receives both the requested source and its parent source, when the request originated from an include directive.

The default erbsland::conf::FileAccessCheck accepts ordinary ELCL files in the directory of the initial file and, by default, its subdirectories. This prevents an include from silently escaping the configuration tree. Applications that load configurations from another trust boundary can install their own check with erbsland::conf::Parser::setAccessCheck.

A custom check returns the appropriate access result for each request. It may also throw a configuration erbsland::conf::ConfError when it needs to report a more specific reason. Setting a null access check disables includes together with source resolution; it is not a way to bypass access checks.

Configuration Names

ELCL addresses values with typed names. A regular name selects a named child, an index selects an element by its position, and text and text-index names represent the corresponding language forms. erbsland::conf::Name stores one such component without losing its type.

A erbsland::conf::NamePath is an ordered sequence of components. It is used for document lookup, validation rules, errors, and flat document maps. Builder APIs accept erbsland::conf::NamePathLike, allowing a single Core string, a erbsland::conf::Name, or a complete path where appropriate. Use erbsland::conf::toNamePath when an owning path is needed explicitly.

using namespace erbsland::text::literals;

const auto section = erbsland::conf::toNamePath("server"_el);
const auto value = document->value(section);

Configuration Locations

A erbsland::unit::CodeLocation stores zero-based line, column, and absolute code-point indices. Its textual representation uses customary one-based numbers for display. A erbsland::conf::Location combines a code location with a erbsland::conf::SourceIdentifier, so locations remain meaningful after the source has been closed.

Source identifiers contain a source name and path. The name describes the source kind or protocol, while the path identifies the concrete input. Their textual form is suitable for diagnostics, but callers should compare the structured identifier when identity matters.

Configuration Scalar Data

Configuration scalar values use the corresponding Core types directly:

• Text uses erbsland::text::String.

• Bytes use erbsland::mem::ByteBlock.

• Dates, times, date-times, and deltas use erbsland::time::Date, erbsland::time::Time or erbsland::time::TimeWithZone, erbsland::time::DateTime, and erbsland::time::CalendarDelta.

• Regular expressions use the immutable shared pointer erbsland::re::RegExPtr.

Regular-expression literals are stored with lazy compilation. Parsing retains their pattern, flags, and settings without invoking the regular-expression compiler. The first matching operation compiles the expression and may throw re::RegExError for an invalid pattern. Call re::RegEx::compileNow() when an application needs explicit validation before using configuration values.

Standalone ELCL times without a suffix are stored as floating Time values. Values with Z or a numeric offset are stored as TimeWithZone. Both use ValueType::Time. The asTime() family removes a zone, while the asTimeWithZone() family attaches TimeZone::local() to a floating value.

Date-times without a suffix are interpreted in the system-local zone at the complete civil date and time. This preserves historical shifts, daylight-saving state, gaps, and folds in the resulting UTC-backed DateTime. Every ELCL delta literal is stored as one independent CalendarDelta component, including month and year values. Ordinary ELCL value lists remain lists and are not implicitly combined into one delta.

Integers and floating-point values use the erbsland::conf::Integer and erbsland::conf::Float aliases. Validation rules use erbsland::text::CaseSensitivity to define their text matching mode.

Lists and matrices are structural value types rather than scalar classes. Access them through the typed operations of erbsland::conf::Value.

Configuration Values

Text values are exposed as erbsland::text::String, and lists of text use erbsland::text::StringList. Read-only strings are returned by value so callers can keep inexpensive, independent references to their content.

A erbsland::conf::Value is one node in a configuration tree. Its value type distinguishes scalar values, value lists and matrices, sections, section lists, and sections with text indexes. Typed accessors verify this type and return the corresponding scalar or child structure. Navigation accepts names and name paths, while iteration exposes children without flattening the tree.

The configuration scalar mapping is deliberately shared with the other Core domains: bytes use mem::ByteBlock; dates, times, date-times, and deltas use the matching time types; and regular expressions use re::RegExPtr. Regular-expression literals are compiled lazily, and copies share the same immutable compilation state. The non-throwing accessors return an empty byte block, invalid date or date-time, midnight, a zero delta, or nullptr when the requested value is missing or has another type. The ...OrThrow() variants report a type mismatch instead.

Values also retain their name, absolute name path, location, and validation metadata. Shared pointers express the ownership contract: callers may keep a value after discarding the parser or document handle, and const pointers provide read-only traversal. Core strings use copy-on-write ownership rather than borrowed views.

using namespace erbsland::text::literals;

const auto server = document->value("server"_el);
const auto port = server->value("port"_el)->asInteger();
const erbsland::text::String name = server->value("name"_el)->asText();

Use erbsland::conf::Document::toFlatValueMap when a complete absolute-path index is more convenient than tree traversal.

Configuration Signing

Signing APIs use erbsland::path::Path for source and destination files and Core strings for textual signature data. erbsland::conf::Signer reads the complete source, validates its UTF-8 encoding and line limits, calculates the document digest, and asks a user-supplied erbsland::conf::SignatureSigner to create the signature text.

The output is a copy of the source with an initial signature line inserted or replaced. The signer preserves the document’s line-ending convention and the byte-level digest rules used by the parser. It does not validate ELCL syntax, so applications should parse a document successfully before signing it.

using namespace erbsland::text::literals;

auto implementation = std::make_shared<MySignatureSigner>();
erbsland::conf::Signer signer{implementation};
signer.sign(
    erbsland::path::Path{"settings.elcl"_el},
    erbsland::path::Path{"settings.signed.elcl"_el},
    "Release Service"_el);

Configuration Signature Validation

When a document contains signature metadata, the parser calculates the document digest and passes the signature, digest, signing-person text, and source information to the configured erbsland::conf::SignatureValidator. The validator is responsible for interpreting the signature text and checking it against the application’s trust policy.

No validator is installed by default. Unsigned documents can then be parsed, while signed documents are rejected because their authenticity cannot be established. Install a validator with erbsland::conf::Parser::setSignatureValidator before parsing signed input.

Validation is performed on the exact signature data produced by the parser. Implementations must not normalize digest or signature bytes, and should return the defined validation result or throw a configuration error when the failure needs additional diagnostic context.

Configuration Errors

Configuration diagnostics use erbsland::text::String for messages and erbsland::path::Path for affected files. A erbsland::conf::ConfErrorContext combines a short title, a detailed description, a configuration error category, and any available code location, name path, file path, and source excerpt. erbsland::conf::ConfError carries this context through the Core exception and diagnostic interfaces.

The exception reason and what() text are the short title. Use the diagnostic interface when presenting an error to a user; its structured text document contains the description and every available context field. Path, stream, and decoding failures remain attached as causes and are rendered by erbsland::err::DiagnosticHelper. The diagnostic’s toString() method renders the same text document through erbsland::text::PlainTextRenderer. Structured and styled consumers can render that document without maintaining a separate diagnostic representation.

The throwing parser entry points propagate this structured error. The non-throwing entry points return a null document and retain the same error in erbsland::conf::Parser::lastError.

using namespace erbsland::text::literals;

erbsland::conf::Parser parser;
auto document = parser.parseText("value: ?"_el);
if (document == nullptr) {
    const auto context = parser.lastError();
    auto error = erbsland::conf::ConfError{context};
    // Present error.diagnostic() to the user.
}

Error categories distinguish syntax, encoding, I/O, limits, signatures, validation, and internal failures. Code should normally preserve the original category when adding context around an error.

Interface

class AccessCheck

The interface to access check implementations.

Subclassed by erbsland::conf::FileAccessCheck

Public Functions

virtual AccessCheckResult check(const AccessSources &sources) = 0

The check function is called for every source, including the initial source that is passed to the parse() function call.

You can either grant or deny access to this source. If you deny the access to the source, the parser will throw a ConfError with ConfErrorCategory::Access. Instead of returning AccessResult::Denied, you can also throw a ConfError with ConfErrorCategory::Access.

Parameters:

sources – The sources that are verified.

Throws:

ConfError – Alternatively, throw a ConfError with the ConfErrorCategory::Access.

Returns:

Return either AccessResult::Granted or AccessResult::Denied.

using erbsland::conf::AccessCheckPtr = std::shared_ptr<AccessCheck>

Shared pointer for AccessCheck.

enum class erbsland::conf::AccessCheckResult : uint8_t

The result of an access check.

Values:

enumerator Granted

If the access is granted.

enumerator Denied

If the access is denied.

struct AccessSources

The source identifiers to verify in the access function.

This structure names the individual source elements for the access function.

Public Members

SourceIdentifierPtr source

The source to verify.

SourceIdentifierPtr parent

The parent source that resolved this new source or nullptr if source is the root document.

SourceIdentifierPtr root

The root document. The root document is always present.

class ConfError : public erbsland::err::RuntimeError

An error raised while processing configuration data.

Public Functions

explicit ConfError(ConfErrorContext context, const std::exception_ptr &cause = {}) noexcept

Create an error from its complete context.

Parameters:

• context – The context of the error.

• cause – An optional cause of the error.

ConfError(ConfErrorCategory category, text::String title, text::String description, const std::exception_ptr &cause = {})

Create an error with an explicit title and description.

Parameters:

• category – The category of the error.

• title – The title of the error (What went wrong?)

• description – The description of the error (Why did it happen?)

• cause – An optional cause of the error.

ConfError(ConfErrorCategory category, text::String title, text::String description, const Location &location, const std::exception_ptr &cause = {})

Create an error with an explicit title and configuration location.

Parameters:

• category – The category of the error.

• title – The title of the error (What went wrong?)

• description – The description of the error (Why did it happen?)

• location – The location of the error.

• cause – An optional cause of the error.

ConfError(ConfErrorCategory category, text::String title, text::String description, path::Path filePath, const std::exception_ptr &cause = {})

Create an error with an explicit title and file path.

Parameters:

• category – The category of the error.

• title – The title of the error (What went wrong?)

• description – The description of the error (Why did it happen?)

• filePath – The file path of the error.

• cause – An optional cause of the error.

ConfError(ConfErrorCategory category, text::String title, text::String description, const SourcePtr &source, const Location &location, const std::exception_ptr &cause = {})

Create an error with an explicit title and source-aware location.

Parameters:

• category – The category of the error.

• title – The title of the error (What went wrong?)

• description – The description of the error (Why did it happen?)

• source – The source of the error.

• location – The location of the error.

• cause – An optional cause of the error.

ConfError(ConfErrorCategory category, text::String description, const SourcePtr &source, const Location &location, const std::exception_ptr &cause = {})

Create an error with the standard title and source-aware location.

Parameters:

• category – The category of the error.

• description – The description of the error (Why did it happen?)

• source – The source of the error.

• location – The location of the error.

• cause – An optional cause of the error.

ConfError(const ValuePtr &value, text::String title, text::String description, const std::exception_ptr &cause = {})

Create a validation error based on the information from the given value.

Parameters:

• value – The value that caused the error. Used to determine the source and location.

• title – The title of the error (What went wrong?)

• description – The description of the error (Why did it happen?)

• cause – An optional cause of the error.

ConfError(const ValuePtr &value, text::String description, const std::exception_ptr &cause = {})

Create a validation error with the default title based on the information from the given value.

Parameters:

• value – The value that caused the error. Used to determine the source and location.

• description – The description of the error.

• cause – An optional cause of the error.

template<typename ...Args>
inline ConfError(ConfErrorCategory category, text::String description, Args&&... args) noexcept

Create an error with the standard title for a category.

Parameters:

• category – The category of the error.

• description – The description of the error (Why did it happen?)

• args – Arguments in random order.

virtual err::DiagnosticConstPtr diagnostic() const override

Convert the error with all its details into a structured diagnostic.

inline const ConfErrorContext &context() const noexcept

Access the complete error context.

inline ConfErrorCategory category() const noexcept

Access the error category.

inline const text::String &title() const noexcept

Access the diagnostic title.

inline const text::String &description() const noexcept

Access the diagnostic description.

inline unit::CodeLocation location() const noexcept

Access the optional diagnostic location.

inline NamePath namePath() const noexcept

Access the optional diagnostic name path.

inline path::Path filePath() const noexcept

Access the optional diagnostic file path.

ConfError withLocation(const Location &location) const

Return this error with a replacement location.

ConfError withNamePathAndLocation(const NamePath &namePath, const Location &location) const

Return this error with a replacement name path and location.

ConfError withDescriptionPrefix(const text::String &prefix) const

Return this error with a description prefix.

ConfError withDescription(text::String description) const

Return this error with a replacement description.

ConfError withCodeSnippet(const std::optional<text::CodeSnippet> &codeSnippet) const

Return this error with a replacement code snippet.

class ConfErrorCategory

The category of an error.

Public Types

enum Enum

The underlying enum type representing distinct categories of errors.

Values:

enumerator IO

A problem occurred while reading data from an I/O stream.

enumerator Encoding

The document contains a problem with UTF-8 encoding.

enumerator UnexpectedEnd

The document ended unexpectedly.

enumerator Character

The document contains a control character that is not allowed.

enumerator Syntax

The document has a syntax error.

enumerator LimitExceeded

The size of a name, text, or buffer exceeds the permitted limit.

enumerator NameConflict

The same name has already been defined earlier in the document.

enumerator Indentation

The indentation of a continued line does not match the previous line.

enumerator Unsupported

The requested feature/version is not supported by this parser.

enumerator Signature

The document’s signature was rejected.

enumerator Access

The document was rejected due to an access check.

enumerator Validation

The document did not meet one of the validation rules.

enumerator Internal

The parser encountered an unexpected internal error.

enumerator ValueNotFound

A value with a given name-path couldn’t be found.

enumerator TypeMismatch

A value exists but has the wrong type for a conversion.

Public Functions

constexpr ConfErrorCategory() = default

Create an internal error category.

inline constexpr ConfErrorCategory(Enum value) noexcept

Create a new error category.

Parameters:

value – The error category enum.

inline ConfErrorCategory &operator=(Enum value) noexcept

Assign a new enum value to this error category.

Parameters:

value – The enum value to assign.

Returns:

Reference to this error category.

inline explicit constexpr operator Enum() const noexcept

Convert to the underlying enum value.

Returns:

The enum representation of this error category.

inline explicit operator int() const noexcept

Convert to the integer error code.

Returns:

The numeric code of this error category.

text::String toText() const noexcept

Get the text representation of this error category.

Returns:

A text representation of this error category.

int toCode() const noexcept

Get the code for this error category.

Returns:

The error code.

class ConfErrorContext

Complete user-facing context for a configuration error.

Public Functions

ConfErrorContext() = default

Create an empty internal-error context.

inline ConfErrorContext(ConfErrorCategory category, text::String title, text::String description) noexcept

Create a context with an explicit title and description.

ConfErrorContext(ConfErrorCategory category, text::String title, text::String description, const SourcePtr &source, const Location &location)

Create a context with an explicit title and source-aware location.

ConfErrorContext(ConfErrorCategory category, text::String description, const SourcePtr &source, const Location &location)

Create a context with the standard title and source-aware location.

template<typename ...Args>
inline ConfErrorContext(ConfErrorCategory category, text::String description, Args&&... args) noexcept

Create a context with the standard title for a category.

inline const text::String &title() const noexcept

Get the error title.

inline ConfErrorContext &setTitle(text::String title) noexcept

Set the error title.

inline const text::String &description() const noexcept

Get the error description.

inline ConfErrorContext &setDescription(text::String description) noexcept

Set the error description.

inline ConfErrorCategory category() const noexcept

Get the error category.

inline ConfErrorContext &setCategory(ConfErrorCategory category) noexcept

Set the error category.

inline const std::optional<unit::CodeLocation> &location() const noexcept

Get the optional source location.

inline ConfErrorContext &setLocation(unit::CodeLocation location) noexcept

Set the source location.

inline const std::optional<NamePath> &namePath() const noexcept

Get the optional configuration name path.

inline ConfErrorContext &setNamePath(NamePath namePath) noexcept

Set the configuration name path.

inline const std::optional<path::Path> &filePath() const noexcept

Get the optional source file path.

inline ConfErrorContext &setFilePath(path::Path filePath) noexcept

Set the source file path.

inline const std::optional<text::CodeSnippet> &codeSnippet() const noexcept

Get the optional source excerpt.

inline ConfErrorContext &setCodeSnippet(text::CodeSnippet codeSnippet) noexcept

Set the source excerpt.

ConfErrorContext withLocation(const Location &location) const

Return a copy enriched with location.

ConfErrorContext withNamePathAndLocation(const NamePath &namePath, const Location &location) const

Return a copy enriched with a name path and location.

ConfErrorContext withDescriptionPrefix(const text::String &prefix) const

Return a copy whose description has prefix.

ConfErrorContext withDescription(text::String description) const

Return a copy with description.

ConfErrorContext withCodeSnippet(const std::optional<text::CodeSnippet> &codeSnippet) const

Return a copy with the optional source excerpt.

Public Static Functions

static text::String defaultTitle(ConfErrorCategory category) noexcept

Get the standard title for an error category.

class Document : public erbsland::conf::Value

A configuration document.

Subclassed by erbsland::conf::impl::Document

Public Types

using FlatValueMap = std::map<NamePath, ConstValuePtr>

The flat map type mapping name paths to constant value pointers.

Maps each name path to the corresponding constant value in the document.

Public Functions

virtual FlatValueMap toFlatValueMap() const noexcept = 0

Convert the value structure of this document into a flat map of values.

Returns:

A flat map with all sections and values of this document.

using erbsland::conf::DocumentPtr = std::shared_ptr<Document>

Shared pointer for Document.

class DocumentBuilder

Builds Configuration Documents Programmatically The document builder allows building the value trees of configuration documents programmatically.

It expects a logical sequence of sections and values and raises exceptions on name collisions. Details:

• The correct document syntax is fully checked when adding values. If the resulting document would become erroneous, a ConfError (Syntax) is thrown.

• Values can only be added to existing sections.

• If you use a single name, when adding a value, it is automatically added to the last section.

• If you use more than one name in the name path, it is added to the specified section.

• When creating sections, this builder automatically creates intermediate sections and converts existing ones into section maps.

• Name paths can be specified as text Name or NamePath objects. Limitations:

• You must not use indexes or text-indexes in name paths to access specific elements in lists.

• This builder interface does not support adding locations to the elements. Example usage:

  DocumentPtr buildDocument() {
      DocumentBuilder builder;
      builder.addSectionMap("main"_el);
      builder.addValue("value"_el, "hello"_el);
      return builder.getDocumentAndReset();
  }
  

Public Functions

DocumentBuilder() = default

Create a new empty document builder.

inline void addSectionMap(const NamePathLike &namePath)

Add a section map with the given name path to the document.

Parameters:

namePath – The name path of the element.

inline void addSectionList(const NamePathLike &namePath)

Add a section list with the given name path to the document.

Parameters:

namePath – The name path of the element.

template<typename T>
inline void addValue(const NamePathLike &namePath, const T &value)

Add a value to the document.

Parameters:

• namePath – The name path of the element.

• value – The value for the new element.

inline void addInteger(const NamePathLike &namePath, const Integer value)

Add an integer value to the document.

Parameters:

• namePath – The name path of the element.

• value – The integer value to add.

inline void addBoolean(const NamePathLike &namePath, const bool value)

Add a boolean value to the document.

Parameters:

• namePath – The name path of the element.

• value – The boolean value to add.

inline void addFloat(const NamePathLike &namePath, const Float value)

Add a float value to the document.

Parameters:

• namePath – The name path of the element.

• value – The floating-point value to add.

inline void addText(const NamePathLike &namePath, const text::String &value)

Add a text value to the document.

Parameters:

• namePath – The name path of the element.

• value – The text value to add.

inline void addDate(const NamePathLike &namePath, const time::Date &value)

Add a date value to the document.

Parameters:

• namePath – The name path of the element.

• value – The date value to add.

inline void addTime(const NamePathLike &namePath, const time::Time &value)

Add a floating time value to the document.

Parameters:

• namePath – The name path of the element.

• value – The time value to add.

inline void addTimeWithZone(const NamePathLike &namePath, const time::TimeWithZone &value)

Add a time-with-zone value to the document.

Parameters:

• namePath – The name path of the element.

• value – The time value to add.

inline void addDateTime(const NamePathLike &namePath, const time::DateTime &value)

Add a date-time value to the document.

Parameters:

• namePath – The name path of the element.

• value – The date-time value to add.

inline void addBytes(const NamePathLike &namePath, const mem::ByteBlock &value)

Add a byte array value to the document.

Parameters:

• namePath – The name path of the element.

• value – The byte array value to add.

inline void addCalendarDelta(const NamePathLike &namePath, const time::CalendarDelta &value)

Add a calendar delta value to the document.

Parameters:

• namePath – The name path of the element.

• value – The time delta value to add.

inline void addRegEx(const NamePathLike &namePath, const re::RegExPtr &value)

Add a regular expression value to the document.

Parameters:

• namePath – The name path of the element.

• value – The regular expression to add.

Throws:

err::ParameterError – If value is null.

inline void reset()

Reset the builder and discard the current document.

This will reset the builder into its initial state and discard any document that is currently being built.

inline DocumentPtr getDocumentAndReset()

Get the document and reset the builder.

This will finalize and return the currently built document and reset the builder into its initial state.

Returns:

The built document.

class FileAccessCheck : public erbsland::conf::AccessCheck

A basic file access check.

By default, the CanonicalizePath, SameDirectory, Subdirectories features are activated.

• If neither SameDirectory, Subdirectories or AnyDirectory is set, all file sources are rejected.

• If a file is included from a non-file source and AnyDirectory is not set, the source is rejected.

Public Types

enum Feature

The feature flags controlling file access restrictions.

Values:

enumerator SameDirectory

Allow included sources to be in the same directory as the including document (recommended, default).

Example: If the including document has the path config/main.elcl documents that are in the directory config, like config/other.elcl are accepted. If this feature is disabled, documents in the same directory as the including document are rejected.

enumerator Subdirectories

Allow included sources in subdirectories of the parent document (recommended, default).

Example: If the including document has the path config/main.elcl documents that are in subdirectories of config, like config/sub/other.elcl are accepted. If this feature is disabled, documents in subdirectories of the including document are rejected.

enumerator AnyDirectory

Not Recommended: Allow included sources in any directory.

Included sources can be anywhere in the filesystem and on shares. Paths can point anywhere.

enumerator OnlyFileSources

Only allow file sources and reject everything else.

If this feature is enabled, this access check only accepts file sources. Sources of any other type e.g. “text” sources are rejected. If this feature is disabled, which is the default, this check only focuses on “file” sources and grants access to any other sources. Granting non-file source is designed to allow chaining multiple checks.

enumerator LimitSize

Limit the maximum size of a file to 100MB (recommended, default).

enumerator RequireSuffix

Only allow file sources with an .elcl suffix.

If this feature is set, this access check only accepts file sources with an .elcl suffix.

enumerator _featureCount

Public Functions

FileAccessCheck() = default

Default constructor.

void enable(Feature feature)

Enable a feature.

void disable(Feature feature)

Disable a feature.

bool isEnabled(Feature feature) const

Test if a feature is enabled.

virtual AccessCheckResult check(const AccessSources &sources) override

The check function is called for every source, including the initial source that is passed to the parse() function call.

You can either grant or deny access to this source. If you deny the access to the source, the parser will throw a ConfError with ConfErrorCategory::Access. Instead of returning AccessResult::Denied, you can also throw a ConfError with ConfErrorCategory::Access.

Parameters:

sources – The sources that are verified.

Throws:

ConfError – Alternatively, throw a ConfError with the ConfErrorCategory::Access.

Returns:

Return either AccessResult::Granted or AccessResult::Denied.

Public Static Functions

static inline FileAccessCheckPtr create()

Create a custom file access check instance.

using erbsland::conf::FileAccessCheckPtr = std::shared_ptr<FileAccessCheck>

Shared pointer for FileAccessCheck.

class FileSourceResolver : public erbsland::conf::SourceResolver

A file source resolver.

The file source resolver supports the recommended format to include files. It works with relative and absolute paths and also has support for wildcards. Here are a few examples:

&at;include "file:example.elcl"              # File in the same directory.
&at;include "file:sub/example.elcl"          # File in a subdirectory of the current configuration file.
&at;include "file:../example.elcl"           # File in the parent directory (if access rules allow it)
&at;include "file:/usr/local/example.elcl"   # Absolute path.

Public Types

enum Feature

Features of the file source resolver.

Values:

enumerator RecursiveWildcard

Support for recursive wildcards.

enumerator FilenameWildcard

Support for filename wildcards.

enumerator AbsolutePaths

Support for absolute paths.

enumerator WindowsUNCPath

Support for Windows UNC paths.

enumerator FileProtocol

Support for the file: protocol prefix.

enumerator _featureCount

Public Functions

void enable(Feature feature)

Enable a feature.

void disable(Feature feature)

Disable a feature.

bool isEnabled(Feature feature) const

Test if a feature enabled.

virtual SourceListPtr resolve(const SourceResolverContext &context) override

Resolve Sources This function is called when the parser encounters an include meta-command.

The raw and unprocessed text of the command and the source of the parsed document are given as arguments to this function. This function must either return a list of sources that match the expression or throw a ConfError exception. If an exception is thrown, the parsing will be stopped and the thrown exception will be passed to the caller of parse(). If a list is returned, the parser will parse the sources in the given order and include the parsed contents in the document. The returned sources should be in a closed state. The parser will open them in the sequence they are parsed.

Parameters:

context – The resolve context.

Throws:

ConfError – Throw ConfError with ConfErrorCategory::Syntax if the include text does not match the required format.

Returns:

A list of sources (see SourceList) to include in the document.

Public Static Functions

static inline FileSourceResolverPtr create()

Create a new instance of the file source resolver.

using erbsland::conf::FileSourceResolverPtr = std::shared_ptr<FileSourceResolver>

Shared pointer for FileSourceResolver.

using erbsland::conf::Float = double

Floating-point type used throughout the parser.

using erbsland::conf::Integer = int64_t

Signed integer type used throughout the parser.

class Location

Represents the location in a parsed document.

Public Functions

Location() = default

Creates an undefined location.

Can be tested with isUndefined().

inline explicit Location(SourceIdentifierPtr sourceIdentifier, const unit::CodeLocation codeLocation = {}) noexcept

Create a new location object.

Parameters:

• sourceIdentifier – The source identifier.

• codeLocation – The location in the document.

Location(const Location&) = default

Default copy constructor.

Location(Location&&) = default

Default move constructor.

Location &operator=(const Location&) = default

Default copy assignment.

Location &operator=(Location&&) = default

Default move assignment.

inline bool operator==(const Location &other) const noexcept

Compare this location to another for equality.

Parameters:

other – The location to compare.

Returns:

true if both the source identifier and position are equal.

inline bool operator!=(const Location &other) const noexcept

Compare this location to another for inequality.

Parameters:

other – The location to compare.

Returns:

true if the locations are not equal, false otherwise.

inline bool isUndefined() const noexcept

Test if this location is undefined.

Returns:

true if undefined, false otherwise.

inline const SourceIdentifierPtr &sourceIdentifier() const noexcept

The source identifier for this location.

inline constexpr unit::CodeLocation codeLocation() const noexcept

Get the code location.

text::String toText() const

Get this location as a text.

The location is formatted as: (source identifier):(line):(column). If no source identifier is specified, it is replaced by the text <unknown>.

Returns:

A string with this location information.

template<typename T>
class Matrix

A 2D matrix with per-row column counts.

Public Functions

Matrix() = default

Create an empty matrix.

inline Matrix(const unit::ItemCount rowCount, const unit::ItemCount columnCount)

Create a matrix with a given size.

Parameters:

• rowCount – The number of rows.

• columnCount – The number of columns.

Throws:

err::OutOfRangeError – if the matrix exceeds cMaximumValueCount.

inline unit::ItemCount rowCount() const noexcept

Get the number of rows in this matrix.

inline unit::ItemCount columnCount() const noexcept

Get the number of columns in this matrix.

inline unit::ItemCount actualColumnCount(const unit::ItemIndex row) const noexcept

Get the actual column count for the given row.

Parameters:

row – The row index.

Returns:

The number of columns defined in the row.

inline bool isDefined(const unit::ItemIndex row, const unit::ItemIndex column) const noexcept

Test if a value was defined in the original nested list.

Parameters:

• row – The row index.

• column – The column index.

Returns:

true if the value was defined.

inline auto value(const unit::ItemIndex row, const unit::ItemIndex column, const T &defaultValue = {}) const noexcept -> T

Access a value by row and column.

Parameters:

• row – The row index.

• column – The column index.

• defaultValue – The default value for missing cells.

Returns:

The value or the default value if it was not defined.

inline const T &valueOrThrow(const unit::ItemIndex row, const unit::ItemIndex column) const

Access a value by row and column and throw on bounds errors.

Parameters:

• row – The row index.

• column – The column index.

Throws:

err::OutOfRangeError – if the row or column is outside the matrix.

Returns:

The value or a default value if it was not defined.

inline void setValue(const unit::ItemIndex row, const unit::ItemIndex column, const T &value)

Set a value.

Parameters:

• row – The row index.

• column – The column index.

• value – The value to set.

Throws:

err::OutOfRangeError – if the row or column is outside the matrix.

inline void setRow(const unit::ItemIndex row, const std::vector<T> &values)

Set values for a complete row.

Parameters:

• row – The row index.

• values – The values to set.

Throws:

err::OutOfRangeError – if the row is outside the matrix.

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.

Predefined Meta-Names

static const Name &meta(Meta metaName)

Access a predefined mena-name.

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 ConfVersion

enumerator Signature

enumerator Include

enumerator Features

enumerator _count

enum class VR : uint8_t

An enum to address validation-rules constants.

Values:

enumerator ReservedAny

enumerator ReservedTemplate

enumerator ReservedName

enumerator ReservedEntry

enumerator ReservedKey

enumerator ReservedDependency

enumerator UseTemplate

enumerator Type

enumerator CaseSensitive

enumerator KeyName

enumerator KeyKey

enumerator DepMode

enumerator DepSource

enumerator DepTarget

enumerator DepError

enumerator _count

using MetaNameArray = std::array<const Name, metaNameCount>

The array-type to return all meta-names.

using VrNameArray = std::array<const Name, static_cast<std::size_t>(VR::_count)>

The array-type to return all VR names.

Public Functions

inline Name()

Create an empty regular name that can be used as a placeholder.

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.

inline bool operator==(const Name &other) const

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.

text::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.

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.

bool isReservedValidationRule() const noexcept

Test if this name is a reserved validation-rules name.

bool isEscapedReservedValidationRule() const noexcept

Test if this name is an escaped reserved validation-rules name.

Name withReservedVRPrefixRemoved() const noexcept

Get this name with the reserved prefix removed.

Public Static Functions

static Name createRegular(text::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:

ConfError – (Syntax, LimitExceeded, Encoding) If there is any problem with the name.

static Name createText(text::String text)

Create a text name.

Parameters:

text – The text name (without the double quotes).

Throws:

ConfError – (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 text::String normalize(const text::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:

ConfError – (Syntax, LimitExceeded, Encoding) in case of any problem.

Returns:

The normalized name.

static void validateText(const text::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:

ConfError – (LimitExceeded, Encoding) in case of any problem.

static const MetaNameArray &allMetaNames()

Access a list of all supported meta-names.

static const Name &emptyInstance() noexcept

Return an empty instance of a name.

static const Name &vrName(VR vrName)

Access a predefined VR name.

static const VrNameArray &allVrNames()

Access a list with all VR 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.

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 Index = std::size_t

Type used for indexing elements.

using Count = std::size_t

Type used for element counts.

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.

std::strong_ordering operator<=>(const NamePath&) const = default

Default comparison.

bool operator==(const NamePath&) const = default

Default comparison.

bool empty() const noexcept

Test if this is an empty path.

Count size() const noexcept

Get the number of elements in this path.

const Name &at(Index index) const

Access one name in the name path.

Index find(const Name &name) const noexcept

Find the first element that equals the given name.

Parameters:

name – The name to search for.

Returns:

The index of the first matching element, or npos if there is no match.

const Name &front() const

Access the first element.

const Name &back() const

Access the last element.

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.

bool containsText() const noexcept

Test if this path contains a text-name.

Returns:

true if this path contains a text-name element, false otherwise.

NameList::const_iterator begin() const noexcept

Get an iterator to the first name in the path.

NameList::const_iterator end() const noexcept

Get an iterator to the end of the path.

std::span<const Name> view() const noexcept

Access a view of all elements.

NamePath parent() const noexcept

Get the parent path.

NamePath subPath(Index pos = 0, Count count = npos) const noexcept

Return a sub-path from this path.

If the given index range is invalid, it returns an empty path.

Parameters:

• pos – The start index.

• count – The maximum number of elements to include.

Returns:

The resulting sub-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.

void append(const NamePath &namePath) noexcept

Append another name path to this path.

Parameters:

namePath – The name path to append.

void prepend(const NamePath &namePath) noexcept

Prepend another name path in front of this path.

Parameters:

namePath – The name path to prepend.

void popBack() noexcept

Remove the last element of this path.

void clear() noexcept

Clear the path.

text::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 text::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:

ConfError – (Syntax, Encoding, Limit) In case of any problem with the name.

Public Static Attributes

static constexpr Index npos = std::numeric_limits<Index>::max()

Marker returned by search functions when no element was found.

using erbsland::conf::NamePathLike = std::variant<Name, NamePath, text::String, std::size_t>

A name-path or convertible value.

using erbsland::conf::NamePathList = std::vector<NamePath>

A list of name paths.

NamePath erbsland::conf::toNamePath(const NamePathLike &namePathLike)

Convert a name-path like value into a name path.

enum class erbsland::conf::NameType : uint8_t

The type of name.

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

inline text::String erbsland::conf::toString(const NameType nameType) noexcept

Convert a name type to its descriptive text.

Parameters:

nameType – The name type to convert.

Returns:

The descriptive text for the name type.

class Parser

This parser reads the Erbsland Configuration Language.

Multithreading: This parser is reentrant, and therefore it can be used in multiple threads, as long each thread uses an individual instance of the parser.

Convenience Methods

These methods are convenience methods to call parse or parseOrThrow.

They construct a Source from the given parameters and call parse or parseOrThrow using this source.

inline DocumentPtr parseFileOrThrow(path::Path path)

Parse the given file into a configuration document and throw an exception on error.

inline DocumentPtr parseFile(path::Path path)

Parse the given file into a configuration document and return a null pointer on error.

inline DocumentPtr parseTextOrThrow(text::String text)

Parse the given text into a configuration document and throw an exception on error.

inline DocumentPtr parseText(text::String text)

Parse the given text into a configuration document and return a null pointer on error.

Public Functions

Parser() = default

Create a new parser with the default settings.

void setSourceResolver(const SourceResolverPtr &sourceResolver) noexcept

Set a custom source resolver used to resolve include directives while parsing.

By default, an instance of FileSourceResolver is used, which supports file-based includes, as specified in the format recommended in the documentation.

Parameters:

sourceResolver – The custom source resolver, or nullptr to disable the include meta-command.

void setAccessCheck(const AccessCheckPtr &accessCheck) noexcept

Set a custom access check.

By default, an instance of FileAccessCheck with default options is used. This instance limits included files to the same directory and subdirectories of the including configuration.

Parameters:

accessCheck – An instance of a source access check implementation, or nullptr to disable the include meta-command.

void setSignatureValidator(const SignatureValidatorPtr &signatureValidator) noexcept

Set a signature validator.

By default, no signature validator is set. This allows parsing all unsigned configuration documents. Documents with a signature meta-value get rejected by the parser.

Parameters:

signatureValidator – An instance of a signature validator implementation, or nullptr to disable signature validation.

DocumentPtr parseOrThrow(const SourcePtr &source)

Parse the given source into a configuration document and throw an exception on any error.

Parameters:

source – The source to parse. Should be closed.

Throws:

• ConfError – if there was any problem with the parsed source or document.

• err::ParameterError – if source is nullptr.

Returns:

The root node of the parsed configuration tree.

DocumentPtr parse(const SourcePtr &source)

Parse the given source into a configuration document.

Parameters:

source – The source to parse. Should be closed.

Throws:

err::ParameterError – if source is nullptr.

Returns:

The root node of the parsed configuration tree or nullptr on any parsing error. Use lastError() to access the last error.

ConfErrorContext lastError() const noexcept

Access the last error.

Returns:

The context of the last error, or an empty context if no parse error is available.

class SignatureSigner

The signer interface to create new signatures when signing documents.

Public Functions

virtual text::String sign(const SignatureSignerData &data) = 0

Create the signature text when signing a document.

Parameters:

data – The data from the document to create the signature from.

Returns:

The text that shall be added to the \@signature meta-value in the stored document. This text must be shorter than 3980 bytes to fit into a single line of the configuration.

using erbsland::conf::SignatureSignerPtr = std::shared_ptr<SignatureSigner>

Shared pointer for SignatureSigner.

struct SignatureSignerData

The data for the signer implementation.

Public Members

SourceIdentifierPtr sourceIdentifier

The source identifier of the document.

text::String signingPersonText

The raw and unprocessed text for the signer that was passed to the sign method.

text::String documentDigest

The cryptographic hash of the document.

The hash always has the format <type> <hash as a lowercase hex byte sequence>. As the responsibility of the application is only the verification of the signature, decoding of this text shouldn’t be necessary. Instead, the application should compare and sign/verify this text as it is.

class SignatureValidator

The interface for signature validation.

Public Functions

virtual SignatureValidatorResult validate(const SignatureValidatorData &data) = 0

The method for validating the signature.

The parser calls this method to validate the signature of a document. The function is called for every document, no matter if it has a signature or not.

Parameters:

data – The data with the details to validate the signature.

Returns:

The validation result.

using erbsland::conf::SignatureValidatorPtr = std::shared_ptr<SignatureValidator>

Shared pointer for SignatureValidator.

struct SignatureValidatorData

The data from the parser to verify the signature of a document.

Public Members

SourceIdentifierPtr sourceIdentifier

The source identifier of the verified document.

text::String signatureText

The raw and unprocessed text from the signature.

If a document has no \@signature line, this text is empty.

text::String documentDigest

The cryptographic hash of the document.

The hash always has the format <type> <hash as a lowercase hex byte sequence>. As the responsibility of the application is only the verification of the signature, decoding of this text shouldn’t be necessary. Instead, the application should compare and sign/verify this text as it is.

enum class erbsland::conf::SignatureValidatorResult : uint8_t

The result of the signature validation.

Values:

enumerator Accept

The signature is correct. Accept the document.

enumerator Reject

The signature is not correct. Reject the document.

class Signer

The tool to sign configuration documents.

Public Functions

explicit Signer(SignatureSignerPtr signatureSigner)

Create a new signer tool using the given implementation.

Parameters:

signatureSigner – The signature signer implementation to use.

void sign(path::Path sourcePath, path::Path destinationPath, text::String signingPersonText)

Sign a document.

This signs a given document. The signed document is not parsed, and therefore its syntax is not checked. It is recommended that you use Parser to verify the document before signing it.

• The encoding of the document is checked, as UTF-8 is fully decoded/encoded.

• The line lengths are checked, as the document is read line-by-line.

• An existing initial \@signature line is skipped and replaced in the destination.

Parameters:

• sourcePath – The path of the document to sign.

• destinationPath – The path where the signed document is stored.

• signingPersonText – The text identifying the signing person.

Throws:

ConfError – (IO, Encoding) in case of any problem with the signing process.

class Source

Interface for the data source to read the configuration.

Implementation notes:

• Constructing instances of source subclasses should be a lightweight operation, as sources may be created in batches, e.g. when an \@include directive with a recursive pattern is encountered.

• The constructor of a source shouldn’t throw exceptions, unless a program termination due to internal errors is favourable.

• Heavy allocations and API calls shall be made in the open() method.

• Any IO exceptions shall be raised in the open() and/or readLine() methods.

Subclassed by erbsland::conf::impl::StringSource, erbsland::conf::impl::TextStreamSource

Public Functions

inline text::String name() const noexcept

Get the name of the source.

The name of the source also specifies its type or protocol. In a source identifier, the source name is separated from the source path by a colon.

Returns:

The name of the source.

inline text::String path() const noexcept

Get the path of the source.

The path of the source specifies the location of the source. In a source identifier, the source path is separated from the source name by a colon.

Returns:

The path of the source.

virtual SourceIdentifierPtr identifier() const noexcept = 0

Get the source identifier.

Returns:

The source identifier.

virtual void open() = 0

Open the source.

The open method is only called once in the lifetime of a source. After a successful call of open(), the method isOpen() must return true.

Throws:

ConfError – (IO) If an error occurs while opening the source.

virtual bool isOpen() const noexcept = 0

Test if the source is open.

Returns:

true if the source is open, false otherwise.

virtual bool atEnd() const noexcept = 0

Test if the source reached its end.

Returns:

true if the source reached its end, false otherwise.

virtual text::String readLine() = 0

Reads a line from the source.

The read line must contain the ending newline sequence if there is any. The returned string is an owning COW value and remains valid after subsequent reads and after this source is destroyed. An empty string signals the end of the source.

Throws:

ConfError – (IO) If an error occurs while reading the line.

Returns:

The next line, or an empty string if no more data is available.

virtual std::optional<text::CodeSnippet> codeSnippet(unit::CodeLocation location) noexcept = 0

Get a best-effort source excerpt around a location.

A stream source may read up to two additional context lines if the affected line is already buffered.

Parameters:

location – The zero-based source location.

Returns:

Up to two context lines around the affected line, if available.

virtual void close() noexcept = 0

Closes the source.

Closes the source and releases any system resources associated with the source. After a call of close(), the method isOpen() must return false.

Public Static Functions

static SourcePtr fromFile(path::Path path) noexcept

Create a source for a file path.

The returned source does not open the file immediately. The file is opened on the first call to open().

Parameters:

path – The path to the file.

static SourcePtr fromString(text::String text) noexcept

Create a source from the given UTF-8 encoded string.

Parameters:

text – The string with the text. The source shares ownership of the string data.

class SourceIdentifier

Lightweight identifier for a configuration source.

Instances of this class are usually shared between locations so that the parser and higher layers can refer to the same source without copying the underlying name and path strings.

Public Functions

SourceIdentifier(text::String name, text::String path, PrivateTag) noexcept

Create a new source identifier with explicit name and path.

Parameters:

• name – The name of the source.

• path – The path of the source.

inline bool operator==(const SourceIdentifier &other) const noexcept

Compare this source identifier to another for equality.

Parameters:

other – The other identifier to compare.

Returns:

true if both identifiers have the same name and path.

inline bool operator!=(const SourceIdentifier &other) const noexcept

Compare this source identifier to another for inequality.

Parameters:

other – The other identifier to compare.

Returns:

true if the identifiers differ.

inline text::String name() const noexcept

Get the name of the source.

inline text::String path() const noexcept

Get the path of the source.

text::String toText() const noexcept

Get a text representation of this source identifier.

Returns:

A text representation of the identifier.

Public Static Functions

static SourceIdentifierPtr create(text::String name, text::String path) noexcept

Factory function to create a shared source identifier.

Parameters:

• name – The source name.

• path – The source path.

Returns:

Shared-pointer to the new instance.

static SourceIdentifierPtr createForFile(text::String path) noexcept

Create a new source identifier for a file.

Parameters:

path – The source path.

Returns:

Shared-pointer to the new instance.

static SourceIdentifierPtr createForText() noexcept

Create a new source identifier for text.

Returns:

Shared-pointer to the new instance.

static bool areEqual(const SourceIdentifierPtr &a, const SourceIdentifierPtr &b) noexcept

A helper function to easily compare two source identifier pointers.

Parameters:

• a – The first identifier.

• b – The second identifier.

Returns:

true if both identifier pointers are either nullptr, or compare to the same values.

class SourceResolver

The interface for any source resolver implementation.

Subclassed by erbsland::conf::FileSourceResolver

Public Functions

virtual SourceListPtr resolve(const SourceResolverContext &context) = 0

Resolve Sources This function is called when the parser encounters an include meta-command.

The raw and unprocessed text of the command and the source of the parsed document are given as arguments to this function. This function must either return a list of sources that match the expression or throw a ConfError exception. If an exception is thrown, the parsing will be stopped and the thrown exception will be passed to the caller of parse(). If a list is returned, the parser will parse the sources in the given order and include the parsed contents in the document. The returned sources should be in a closed state. The parser will open them in the sequence they are parsed.

Parameters:

context – The resolve context.

Throws:

ConfError – Throw ConfError with ConfErrorCategory::Syntax if the include text does not match the required format.

Returns:

A list of sources (see SourceList) to include in the document.

using erbsland::conf::SourceResolverPtr = std::shared_ptr<SourceResolver>

Shared pointer for SourceResolver.

struct SourceResolverContext

The context for resolving sources.

Public Members

text::String includeText

The raw and unprocessed text from the include-command.

SourceIdentifierPtr sourceIdentifier

The source identifier of the document with the include-command.

class TestFormat

Flags for rendering test output.

Public Types

enum Flag

The enumeration with the individual flags.

Values:

enumerator ShowContainerSize

Show the size of a container in the type.

If enabled, this will display the size of a container (e.g. SectionWithNames(size=20)) for all value types that can have children (sections, value lists).

enumerator ShowPosition

Show the position of a value.

Only when rendering value trees: If enabled, the position of a value is added in square brackets after the value (e.g. Integer(1)[1:2]).

enumerator ShowSourceIdentifier

Show the source identifier of a value.

Only when rendering value trees: If enabled, an identifier for the source is added after the value. The identifier is an upper case letter, like Integer(1)[A:1:2]. The value-tree is followed by a legend, like A:

enumerator _flagCount

Public Functions

TestFormat() = default

Create a test format with no flags set.

template<typename ...Args>
inline TestFormat(Args... flags) noexcept

Create a test format with the given flag set.

bool operator==(const TestFormat&) const = default

Compare for equality.

bool operator!=(const TestFormat&) const = default

Compare for unequality.

inline TestFormat operator|(const TestFormat &other) const noexcept

Combine two formats.

inline TestFormat operator|(const Flag flag) const noexcept

Combine two formats.

inline TestFormat &operator|=(const TestFormat &other) noexcept

Combine two formats.

inline TestFormat &operator|=(const Flag flag) noexcept

Combine two formats.

inline bool isSet(const Flag flag) const noexcept

Test if a flag is set.

class Value : public std::enable_shared_from_this<Value>

The base class and interface for all values.

Subclassed by erbsland::conf::Document, erbsland::conf::impl::Value

Access as Typed Value

These methods return the contained value if it has the requested type.

Otherwise, a default-constructed value of the corresponding type is returned, or in case of the ...OrThrow variants, a ConfError (TypeMismatch) is thrown. No type conversion or coercion is performed. For example,

• asInteger() returns the stored Integer if this value is of type Integer, or Integer{} otherwise.

• asText() returns the stored text::String only if this value is of type Text, not if it’s e.g. an Integer. To obtain a textual representation of any supported type (e.g. Integer → "42"), use toTextRepresentation().

virtual Integer asInteger() const noexcept = 0

Access as integer.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual Integer asIntegerOrThrow() const = 0

Access as integer.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual bool asBoolean() const noexcept = 0

Access as boolean.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual bool asBooleanOrThrow() const = 0

Access as boolean.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual Float asFloat() const noexcept = 0

Access as a floating-point value.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual Float asFloatOrThrow() const = 0

Access as a floating-point value.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual text::String asText() const noexcept = 0

Access as text.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual text::String asTextOrThrow() const = 0

Access as text.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual time::Date asDate() const noexcept = 0

Access as a time::Date instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual time::Date asDateOrThrow() const = 0

Access as a time::Date instance.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual time::Time asTime() const noexcept = 0

Access as a floating time::Time instance, removing any configured zone.

Returns:

The value of the requested type, or a default value if this value has a different type.

virtual time::Time asTimeOrThrow() const = 0

Access as a floating time::Time instance, removing any configured zone.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual time::TimeWithZone asTimeWithZone() const noexcept = 0

Access as a time::TimeWithZone instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual time::TimeWithZone asTimeWithZoneOrThrow() const = 0

Access as a time::TimeWithZone instance.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual time::DateTime asDateTime() const noexcept = 0

Access as a time::DateTime instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual time::DateTime asDateTimeOrThrow() const = 0

Access as a time::DateTime instance.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual mem::ByteBlock asBytes() const noexcept = 0

Access as a mem::ByteBlock array.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual mem::ByteBlock asBytesOrThrow() const = 0

Access as a mem::ByteBlock array.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual time::CalendarDelta asCalendarDelta() const noexcept = 0

Access as a time::CalendarDelta instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual time::CalendarDelta asCalendarDeltaOrThrow() const = 0

Access as a time::CalendarDelta instance.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual re::RegExPtr asRegEx() const noexcept = 0

Access as a compiled regular expression.

Returns:

The value of the requested type, or nullptr if this value has a different type.

virtual re::RegExPtr asRegExOrThrow() const = 0

Access as a compiled regular expression.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual ValueList asValueList() const noexcept = 0

Access as a value list.

@important This call does not convert a single value into a list with one element. Use the getList() methods if you like to have this behavior.

Returns:

A value list, or an empty list if this is no value list.

virtual ValueList asValueListOrThrow() const = 0

Access as a value list.

@important This call does not convert a single value into a list with one element. Use the getList() methods if you like to have this behavior.

Throws:

ConfError – (TypeMismatch) if the value is of another type.

Returns:

A value list.

template<typename T>
T asType() const noexcept

This is a convenience method, accessed this value as one of the supported types.

It is implemented calling the various to<Type>() methods. @important

• There are overloads for all integers, converting the signed 64-bit integer into the desired type.

• There are overloads for all float types, converting a double into a float if necessary.

• If the value exceeds the range of the target type:

  • for asType() saturation logic is used - returning the max/min possible value for the chosen type.

  • for asTypeOrThrow() a TypeMismatch exception is thrown.

• The overload for ValueList works exactly like asValueList() and therefore does not convert a single value into a list with one element. Use the getList() methods for this behavior.

Template Parameters:

T – The type to access this value as.

Returns:

The value or a default value.

template<typename T>
T asTypeOrThrow() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Get as Uniform Value Lists and Matrices

• Tries to get this value as uniform lists that consist of values of the same type.

• If this is a single value that matches the type, a list with one element is returned.

template<typename T>
std::vector<T> asList() const noexcept

Returns:

A list with values of this type, or an empty list on any problem.

template<typename T>
std::vector<T> asListOrThrow() const

Throws:

ConfError – In case of any type mismatch or syntax error in the name path.

Returns:

A list with values of this type.

template<typename T>
Matrix<T> asMatrix() const noexcept

Returns:

A matrix with values of this type, or an empty matrix on any problem.

template<typename T>
Matrix<T> asMatrixOrThrow() const

Throws:

ConfError – In case of any type mismatch or syntax error in the name path.

Returns:

A matrix with values of this type.

Get a Value of a Given Type

Tries to get a value at the given name-path with a given type.

• If the name path is not valid,

• or if there is no value at the name-path

• or the value does not have the expected type,

• a default value passed as defaultValue parameter is returned.

• … or, an exception is thrown for the ...OrThrow methods. If types are converted, the same logic as described in asType() or asTypeOrThrow() applies.

template<typename tExpectedType>
auto get(const NamePathLike &namePath, impl::value_get_default_param_t<tExpectedType> defaultValue = {}) const noexcept -> tExpectedType

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Template Parameters:

tExpectedType – The type to expect, e.g. text::String, Integer.

Returns:

the requested value or defaultValue.

template<typename tExpectedType>
inline tExpectedType getOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Template Parameters:

tExpectedType – The type to expect, e.g. text::String, Integer.

Returns:

The requested value.

Integer getInteger(const NamePathLike &namePath, Integer defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

Integer getIntegerOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

bool getBoolean(const NamePathLike &namePath, bool defaultValue = false) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

bool getBooleanOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

Float getFloat(const NamePathLike &namePath, Float defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

Float getFloatOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

text::String getText(const NamePathLike &namePath, text::String defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

text::String getTextOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

time::Date getDate(const NamePathLike &namePath, const time::Date &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

time::Date getDateOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

time::Time getTime(const NamePathLike &namePath, const time::Time &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

time::Time getTimeOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

auto getTimeWithZone(const NamePathLike &namePath, const time::TimeWithZone &defaultValue = {}) const noexcept -> time::TimeWithZone

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

time::TimeWithZone getTimeWithZoneOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

time::DateTime getDateTime(const NamePathLike &namePath, const time::DateTime &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

time::DateTime getDateTimeOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

mem::ByteBlock getBytes(const NamePathLike &namePath, const mem::ByteBlock &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

mem::ByteBlock getBytesOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

auto getCalendarDelta(const NamePathLike &namePath, const time::CalendarDelta &defaultValue = {}) const noexcept -> time::CalendarDelta

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

time::CalendarDelta getCalendarDeltaOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

re::RegExPtr getRegEx(const NamePathLike &namePath, const re::RegExPtr &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

re::RegExPtr getRegExOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

ValueList getValueList(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name, or index to resolve, relative to this value.

Returns:

The value list or an empty list if there is no matching value at namePath.

ValueList getValueListOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – If the value does not exist or has the wrong type.

Returns:

The requested value.

Get Uniform Value Lists or Matrices

• Tries to get uniform lists/matrices that consist of values of the same type.

• If there is a single value at the name path, a list with one element is returned.

template<typename T>
std::vector<T> getList(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name-path, name, or index of the value list.

Returns:

A list with values of this type, or an empty list on any problem.

template<typename T>
std::vector<T> getListOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name-path, name, or index of the value list.

Throws:

ConfError – In case of any type mismatch or syntax error in the name path.

Returns:

A list with values of this type.

template<typename T>
Matrix<T> getMatrix(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name-path, name, or index of the value list.

Returns:

A matrix with values of this type, or an empty matrix on any problem.

template<typename T>
Matrix<T> getMatrixOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name-path, name, or index of the value list.

Throws:

ConfError – In case of any type mismatch or syntax error in the name path.

Returns:

A matrix with values of this type.

Get a Section-Map or Section-List

Tries to get a section map or section list at the given path.

If the path does not exist (or contains syntax errors), either a nullptr is returned, or an exception is thrown (...OrThrow() methods).

ValuePtr getSectionWithNames(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Returns:

The section map/list or nullptr.

ValuePtr getSectionWithNamesOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – if the name path has syntax errors, or if there is no matching section at the value-path.

Returns:

The section map or section list.

ValuePtr getSectionWithTexts(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Returns:

The section map/list or nullptr.

ValuePtr getSectionWithTextsOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – if the name path has syntax errors, or if there is no matching section at the value-path.

Returns:

The section map or section list.

ValuePtr getSectionList(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Returns:

The section map/list or nullptr.

ValuePtr getSectionListOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

ConfError – if the name path has syntax errors, or if there is no matching section at the value-path.

Returns:

The section map or section list.

Tests for a Value Type

Test if a value is of a certain type.

inline bool isInteger() const noexcept

Returns:

true if the value has the tested type.

inline bool isBoolean() const noexcept

Returns:

true if the value has the tested type.

inline bool isFloat() const noexcept

Returns:

true if the value has the tested type.

inline bool isText() const noexcept

Returns:

true if the value has the tested type.

inline bool isDate() const noexcept

Returns:

true if the value has the tested type.

inline bool isTime() const noexcept

Returns:

true if the value has the tested type.

inline bool isDateTime() const noexcept

Returns:

true if the value has the tested type.

inline bool isBytes() const noexcept

Returns:

true if the value has the tested type.

inline bool isTimeDelta() const noexcept

Returns:

true if the value has the tested type.

inline bool isRegEx() const noexcept

Returns:

true if the value has the tested type.

inline bool isValueList() const noexcept

Returns:

true if the value has the tested type.

inline bool isDocument() const noexcept

Returns:

true if the value has the tested type.

inline bool isRoot() const noexcept

Returns:

true if the value has the tested type.

inline bool isSectionWithNames() const noexcept

Returns:

true if the value has the tested type.

inline bool isSectionWithTexts() const noexcept

Returns:

true if the value has the tested type.

inline bool isSectionList() const noexcept

Returns:

true if the value has the tested type.

inline bool isList() const noexcept

Test if this value is a list.

Tests if this value is a list, like a section list or value list with child-elements that can be iterated in a sequence.

Returns:

true if this value is a list.

inline bool isMap() const noexcept

Test if this value is a name-value map.

Tests if this value is a name-value map, like a section with names, section with texts, intermediate section, or a document.

Public Functions

virtual Name name() const noexcept = 0

The name.

virtual NamePath namePath() const noexcept = 0

The name path.

virtual bool hasParent() const noexcept = 0

Test if this value has a parent.

virtual ValuePtr parent() const noexcept = 0

The parent.

virtual ValueType type() const noexcept = 0

The type of this value.

virtual bool hasLocation() const noexcept = 0

Test if this value has location info.

virtual Location location() const noexcept = 0

Get the location info for this value.

virtual void setLocation(const Location &newLocation) noexcept = 0

Set the location info for this value.

virtual bool wasValidated() const noexcept = 0

Test if this value was validated.

Returns:

true if this value was validated using validation-rules.

virtual vr::RulePtr validationRule() const noexcept = 0

The rule that was used to validate this value.

Returns:

The rule or nullptr if this value was not validated.

virtual bool isSecret() const noexcept

Test if this value is a secret.

This is a convenience method, checking the assigned validation rule.

Returns:

true if the validation rule marks this value as secret. false otherwise or if this value wasn’t validated.

virtual bool isDefaultValue() const noexcept = 0

Test if this value is a default value from a validation-rules document.

virtual std::size_t size() const noexcept = 0

Get the number of children.

virtual bool hasValue(const NamePathLike &namePath) const noexcept = 0

Test if there is a child-value with the given index, name, or name-path.

Parameters:

namePath – A name-path, name, or index.

Returns:

true if there is a value (and the name-path is valid).

virtual ValuePtr value(const NamePathLike &namePath) const noexcept = 0

Get the child-value at the specified index, name, or name-path.

If no value is found at the given location, or the name-path contains syntax errors, the method returns a nullptr.

Parameters:

namePath – A name-path, name, or index.

Returns:

The child value.

virtual ValuePtr valueOrThrow(const NamePathLike &namePath) const = 0

Get the child-value at the specified index, name, or name-path.

If no value is found at the given location, or the name-path contains syntax errors, a ConfError exception is thrown.

Parameters:

namePath – A name-path, name, or index.

Throws:

ConfError – (NotFound, Syntax) if the value does not exist or the name-path contains syntax errors.

Returns:

The child value.

virtual ValueIterator begin() const noexcept = 0

Get an iterator to the first child value.

Returns:

The value iterator.

virtual ValueIterator end() const noexcept = 0

Get an iterator to the end of the child values.

Returns:

The value iterator.

ValueList toValueList() noexcept

Convert this value to a value list.

In contrast with asValueList, this method will not only return a value list if this is a value list, but also if this is a scalar value (Text, Integer, Float, Boolean, time::Date, time::Time, time::TimeWithZone, time::DateTime, mem::ByteBlock, time::CalendarDelta, re::RegExPtr). If this is a scalar value, a value list with a single element is returned (this element).

ConstValueList toValueList() const noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ValueMatrix toValueMatrix() noexcept

Convert this value to a value matrix.

This will return a matrix when this is a ValueList, a nested ValueList or a scalar value. For a nested value list, a matrix with the largest row and column count is returned. For a regular value list, a matrix with one column and the number of rows is returned. For a scalar value, a matrix with one row and one column is returned.

ConstValueMatrix toValueMatrix() const noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual text::String toTextRepresentation() const noexcept = 0

Convert this value to its text representation.

Converts the types: Text, Integer, Float, Boolean, time::Date, time::Time, time::TimeWithZone, time::DateTime, mem::ByteBlock, time::CalendarDelta, re::RegExPtr. Sections and lists result in an empty string.

Returns:

A string with the text or text representation.

text::String toTestText(TestFormat format = {}) const noexcept

Convert this value to its test adapter representation.

This is used by the test adapter to verify the value, as described in the language documentation. The general format is <Type>(<value>), where <Type> is one of the standardized type names and <value> the value representation as specified. For example, integer value 5 is converted into the text Integer(5). No additional info is added to sections.

Parameters:

format – The format of the output.

Returns:

The value in its test outcome representation.

text::String toTestValueTree(TestFormat format = {}) const noexcept

Convert this value into a visual value tree.

This method is useful for testing to get a visual representation of a parsed document, or a branch of the document.

Parameters:

format – The format of the output.

Returns:

A text with a visual tree representation of this value.

bool empty() const noexcept

Test if this container is empty.

Returns:

true if the container is empty.

ValuePtr firstValue() const noexcept

Get the first value of a container.

Returns:

The first value or a nullptr.

ValuePtr lastValue() const noexcept

Get the last value of a container.

Returns:

The last value or a nullptr.

class ValueIterator

Const iterator for the Value class.

This is a simple wrapper around the iterator of the internally used container.

Construction and Assignment

inline explicit constexpr ValueIterator(WrappedIterator it)

Create an iterator wrapping the given internal iterator.

Parameters:

it – The iterator to wrap.

Operators

reference operator*() const noexcept

Dereference operator.

Returns:

A shared pointer to the current value.

pointer operator->() const noexcept

Member access operator.

Returns:

A pointer to the current value.

ValueIterator &operator++() noexcept

Prefix increment. Advances the iterator to the next element.

ValueIterator operator++(int) noexcept

Postfix increment. Advances the iterator and returns the previous state.

ValueIterator &operator--() noexcept

Prefix decrement. Moves the iterator to the previous element.

ValueIterator operator--(int) noexcept

Postfix decrement. Moves the iterator to the previous element and returns the previous state.

bool operator==(const ValueIterator &other) const noexcept

Equality comparison.

Parameters:

other – The other iterator for comparison.

bool operator!=(const ValueIterator &other) const noexcept

Inequality comparison.

Parameters:

other – The other iterator for comparison.

class ValueType

The type of value.

Construction and Assignment

constexpr ValueType() = default

Create an undefined value type.

inline constexpr ValueType(const Enum value) noexcept

Create a new value type.

Parameters:

value – The enum value.

Operators

inline ValueType &operator=(const Enum value) noexcept

Assign an enum.

inline constexpr operator Enum() const noexcept

Cast back to the enum value.

Tests

inline constexpr bool isUndefined() const noexcept

Test if the type is undefined.

inline constexpr bool isMap() const noexcept

Test if this is any kind of value map (a section or document).

inline constexpr bool isList() const noexcept

Test if this is any kind of list (section list or value list).

inline constexpr bool isStructural() const noexcept

Test if this is a structural value.

Structural values are documents, sections and section lists that organize the content of the document.

inline constexpr bool isScalar() const noexcept

Test if this is a scalar value.

A scalar value represents a single value (not a section, section list or value list). Scalar values are: Integer, Boolean, Float, Text, Date, Time, DateTime, mem::ByteBlock, TimeDelta and RegEx.

inline constexpr bool isSingle() const noexcept

Deprecated:

Please use isScalar() for new code.

Public Types

enum Enum

The enum for this type.

Values:

enumerator Undefined

Undefined type.

enumerator Integer

An integer value.

enumerator Boolean

A boolean value.

enumerator Float

A floating-point value.

enumerator Text

A text value.

enumerator Date

A date value.

enumerator Time

A time value.

enumerator DateTime

A date-time value.

enumerator Bytes

Binary data.

enumerator TimeDelta

A time delta value.

enumerator RegEx

A regular expression value.

enumerator ValueList

A list of values.

enumerator SectionList

A list of sections.

enumerator IntermediateSection

An intermediate section.

enumerator SectionWithNames

A section with names.

enumerator SectionWithTexts

A section with texts.

enumerator Document

The document.

Public Functions

text::String toText() const noexcept

Convert this type into text.

text::String toValueDescription(bool withArticle) const

Convert this type into a value description for error messages.

This method creates a human-readable description of this value type, describing the value for error reporting and user facing texts.

Parameters:

withArticle – Add an English article to the text.

inline constexpr Enum raw() const noexcept

Access the underlying enum value.

Public Static Functions

template<typename T>
static inline constexpr ValueType from() noexcept

Get a value type for a single value, native type.

Please note that this method does not support sections or value lists.

static const std::array<ValueType, 17> &all() noexcept

Get an array with all value types.