ELCL Syntax and Formatting

Source Snapshots

Include <erbsland/all_conf_syntax.hpp> explicitly. The conf::syntax namespace is not included by all_conf.hpp and is not flattened into the root namespace.

syntax::Parser::parseText() returns a syntax::DocumentPtr owning a lossless, immutable snapshot. Unlike conf::Parser, it retains comments, spacing, spelling, delimiters and erroneous source. Includes, placeholders, signatures and embedded languages are not evaluated. Tokens partition the original text and expose half-open byte ranges and zero-based source locations. The token, statement, diagnostic and line accessors return const references to Core List collections. Tokens use shared syntax::TokenPtr ownership; retaining a token or copying its list keeps the tokens alive after the document is released. tokensForLine() supports line-oriented highlighting by returning a const reference to a stored list of the same token pointers, without constructing a list on each lookup. Invalid line indices return a shared empty list. Borrowed list references remain valid for the lifetime of the document. Statement token boundaries use ItemIndex.

TokenKind is the shared classification used by the lexer and syntax snapshots, and exposes its enum through raw(). It preserves the lexer names, including EndOfData and RegEx; toText() returns their standardized diagnostic spelling. Default construction produces Error. fromMultiLineOpen() and fromMultiLineClose() classify a repeated delimiter character, returning EndOfData for an unrecognized character. SectionName and SectionTextName identify names in section declarations after syntax context is resolved. toValueType() maps complete literals and multiline opening delimiters to their semantic value category. Other tokens, including multiline payload, return ValueType::Undefined. isValue() recognizes complete single-line literals; isPayload() recognizes multiline content tokens.

#include <erbsland/all_conf_syntax.hpp>

auto document = el::conf::syntax::Parser{}.parseText(source);
auto result = el::conf::syntax::Formatter{}.format(document);
auto formatted = result.text();

for (const auto &token : document->tokensForLine(el::LineIndex{0})) {
    auto originalText = token->text();
}

Parsing empty or malformed input still returns a non-null document. The formatter accepts the shared document directly and rejects null pointers with ParameterFailure. Formatting diagnostics are also exposed through a const List reference.

Diagnostics refer to the original input. Reparse formatted output to obtain updated highlighting coordinates. No renderer or incremental edit protocol is imposed on consumers.

Recovery

Expected input errors become diagnostics. Scanning resumes on a physical line boundary, preserving recognized tokens and the failed line suffix. Multiline values retain their delimiter and indentation context after a malformed line. Syntax recognition uses one decoder and character stream for the complete snapshot, sharing lexical productions with strict configuration parsing. Recovery happens within those productions, where continued-value context is available. An unindented statement ends a broken block and is processed again as a new statement.

The formatter preserves a damaged statement verbatim, including its multiline content, and formats valid surrounding statements. It does not invent missing delimiters or fix application-level configuration errors. Internal failures are not treated as source errors.

Statement name paths are resolved locally. Relative sections use the last absolute section; @include resets that context without opening another source. A malformed section invalidates the current section context. Values with no resolved path cannot match path selectors. Repeated list sections use their declaration path without occurrence indices.

Styles and Selectors

Format contains a complete base FormatStyle and ordered FormatRule objects. Each rule combines a Selector with a FormatStylePatch. Only explicitly set patch properties participate in the cascade.

Selectors combine their conditions with AND. Their path alternatives combine with OR. Supported conditions select statement kind, relative/list sections, declared section-name count greater than a threshold, meta assignments and value types. A section match does not implicitly select its values.

Name paths use component globs, sharing the filesystem path matcher. * stays inside one name; a complete ** component matches zero or more names. server.**.port matches both server.port and server.http.port. Quoted components preserve text-name identity and may contain literal dots. Regular names use ELCL normalization. Embedded recursive stars and runs of three stars are invalid.

Each property independently takes the most specific matching rule. Exact paths outrank globs, which outrank selectors without paths. Globs rank by literal component count, literal character count, then fewer recursive and ordinary wildcards. Further ties use the number of other conditions, then insertion order: later rules win. Only matching path alternatives contribute specificity.

Formatting Options

Regular section and value names default to Title Case with spaces. Each has independent case and separator settings. Quoted names and identifiers inside text values default to Keep. Enabling their normalization changes only text that parses completely as one regular identifier, but can change case-sensitive names or application text. Selectors match the original names; such changes can affect selector matching on a later pass.

Section indentation is the zero-based opening-bracket column. Finite prefixes are filled with dashes, reserving the required opening list star. Infinite indentation right-aligns the header. A finite suffix counts decoration characters, including the optional closing star; infinite suffix fills to the width. Both infinite center the header, placing an odd spare dash on the right. Inline comments reserve their own space. Header content is never truncated.

valueWrapping() controls placement of complete non-multiline values without splitting their contents:

Keep retains whether a value starts on the assignment line or a continuation line.
SameLine joins the value onto its assignment line, even beyond the soft width limit.
NextLine places the value on an indented continuation line.
NextLineIfFits moves an overlong assignment only when the complete continuation line fits the limit (the default).
WhenTooLong moves overlong assignments even when the continuation still exceeds the limit.

Trailing value comments move with their value and participate in the width calculation. Blank lines and comments between the separator and its value prevent reflow. Multiline text, code, regular expressions, byte payloads, matrices, and bulleted lists retain their structural layout. Style patches can override value placement independently of the other properties.

Vectors support Keep, Compact and Multiline. Compact layout uses one comma-separated assignment if it fits, otherwise one value per continued line. Matrices retain rows and support Keep or Align. Alignment falls back to minimal spacing when aligned rows exceed the width. Comments remain attached to their original values or rows.

Separators support : or = and independent space-count or column positioning before the separator and value. Passed columns use minimum safe spacing. Continuations support a positive number of spaces or tabs. Structural indentation changes preserve additional payload indentation.

Defaults are 118 code points per line, bracket column four, suffix fill, spaces inside section brackets and around dots, a closing list star, separator column 29, one space after separators and bullets, four-space continuations, and retained list layouts. Default rules give relative sections bracket column six and suffix width four, and meta values lowercase names with name: value spacing.

Line width is a soft limit measured in code points, counting a tab as one. Indivisible literals and comments may exceed it. Blank lines, ordering, newline conventions and final-newline presence are preserved. Added lines use the current statement’s newline convention, falling back to the document’s first newline or LF. Changed signed source produces a warning; signing remains a separate operation. Default formatting is idempotent.

Interface

struct Diagnostic

A source diagnostic; ranges always refer to the original input.

Public Members

ConfErrorCategory category: The failure category.

text::String message: Human-readable description.

unit::ByteRange range: Affected bytes, or an empty range for missing input.

unit::CodeLocation location: Original source location.

bool warning = {false}: Whether this diagnostic is advisory.

class Document

An immutable, lossless syntax snapshot with locally resolved statement paths.

Public Functions

inline const text::String &text() const noexcept: Get the unmodified original source.

inline const util::List<TokenPtr> &tokens() const noexcept: Get all source tokens in order, excluding an end sentinel.

inline const util::List<Statement> &statements() const noexcept: Get all recognized statements in source order.

inline const util::List<Diagnostic> &diagnostics() const noexcept: Get source diagnostics.

inline const util::List<unit::ByteRange> &lines() const noexcept: Get source line ranges, including their newline bytes.

inline const SourceIdentifierPtr &sourceIdentifier() const noexcept: Get the source identifier.

inline bool hasErrors() const noexcept: Test whether any input errors were detected.

const util::List<TokenPtr> &tokensForLine(unit::LineIndex line) const noexcept

Find the tokens intersecting a source line.

Parameters:: line – Zero-based line index.
Returns:: A stored list, or a shared empty list when the line does not exist.

using erbsland::conf::syntax::DocumentPtr = std::shared_ptr<Document>: Shared ownership of a syntax document.

class Format

A base style and ordered rules, resolved independently for each property.

Public Functions

Format(): Create repository defaults, including relative-section and meta-value rules.

inline const FormatStyle &baseStyle() const noexcept: Get the base style.

Format &setBaseStyle(FormatStyle style): Replace the base style.

Format &addRule(FormatRule rule): Add a rule; later rules win equal-specificity ties.

Format &clearRules() noexcept: Remove all rules, including default rules.

FormatStyle resolve(const Statement &statement) const

Resolve a complete style for one statement.

Parameters:: statement – Original source statement.
Returns:: Effective formatting properties.

class FormatResult

Formatted source and diagnostics referring to the original input.

Public Functions

inline FormatResult(text::String text, util::List<Diagnostic> diagnostics)

Construct a formatting result.

Parameters:

text – Formatted text.
diagnostics – Source errors and formatting warnings.

inline const text::String &text() const noexcept: Get formatted source text.

inline const util::List<Diagnostic> &diagnostics() const noexcept: Get diagnostics in original-source coordinates.

struct FormatRule

A selector and the properties it contributes to the cascade.

Public Members

Selector selector: Statement selection.

FormatStylePatch style: Explicit overrides.

class FormatStyle

Complete formatting properties with repository-style defaults.

Public Functions

inline unit::CpCount maximumLineLength() const noexcept: Soft maximum line width.

FormatStyle &setMaximumLineLength(unit::CpCount value) noexcept

Set soft maximum line width.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordCase sectionNameCase() const noexcept: Case of regular section names.

FormatStyle &setSectionNameCase(WordCase value) noexcept

Set case of regular section names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordSeparator sectionNameSeparator() const noexcept: Word separator in section names.

FormatStyle &setSectionNameSeparator(WordSeparator value) noexcept

Set word separator in section names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordCase valueNameCase() const noexcept: Case of regular value names.

FormatStyle &setValueNameCase(WordCase value) noexcept

Set case of regular value names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordSeparator valueNameSeparator() const noexcept: Word separator in value names.

FormatStyle &setValueNameSeparator(WordSeparator value) noexcept

Set word separator in value names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordCase textNameCase() const noexcept: Opt-in case of quoted identifier names.

FormatStyle &setTextNameCase(WordCase value) noexcept

Set opt-in case of quoted identifier names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordSeparator textNameSeparator() const noexcept: Word separator in quoted identifier names.

FormatStyle &setTextNameSeparator(WordSeparator value) noexcept

Set word separator in quoted identifier names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordCase textIdentifierCase() const noexcept: Opt-in case of identifiers in text values.

FormatStyle &setTextIdentifierCase(WordCase value) noexcept

Set opt-in case of identifiers in text values.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline WordSeparator textIdentifierSeparator() const noexcept: Word separator in text identifiers.

FormatStyle &setTextIdentifierSeparator(WordSeparator value) noexcept

Set word separator in text identifiers.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline unit::CpCount sectionIndent() const noexcept: Opening bracket column, or infinite for right alignment.

FormatStyle &setSectionIndent(unit::CpCount value) noexcept

Set opening bracket column, or infinite for right alignment.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline unit::CpCount sectionSuffix() const noexcept: Trailing decoration width, or infinite for fill.

FormatStyle &setSectionSuffix(unit::CpCount value) noexcept

Set trailing decoration width, or infinite for fill.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline bool sectionStar() const noexcept: Emit the optional closing star on list sections.

FormatStyle &setSectionStar(bool value) noexcept

Set emit the optional closing star on list sections.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline bool spaceAfterOpen() const noexcept: Space after a section opening bracket.

FormatStyle &setSpaceAfterOpen(bool value) noexcept

Set space after a section opening bracket.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline bool spaceBeforeClose() const noexcept: Space before a section closing bracket.

FormatStyle &setSpaceBeforeClose(bool value) noexcept

Set space before a section closing bracket.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline bool spaceAroundDot() const noexcept: Spaces around section path separators.

FormatStyle &setSpaceAroundDot(bool value) noexcept

Set spaces around section path separators.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline ValueWrapping valueWrapping() const noexcept: Get the placement policy for non-multiline values.

FormatStyle &setValueWrapping(ValueWrapping value) noexcept: Select the placement policy for non-multiline values.

inline VectorStyle vectorStyle() const noexcept: Vector layout policy.

FormatStyle &setVectorStyle(VectorStyle value) noexcept

Set vector layout policy.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline MatrixStyle matrixStyle() const noexcept: Matrix column alignment policy.

FormatStyle &setMatrixStyle(MatrixStyle value) noexcept

Set matrix column alignment policy.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline unit::CpCount spacesAfterStar() const noexcept: Spaces after a list bullet.

FormatStyle &setSpacesAfterStar(unit::CpCount value) noexcept

Set spaces after a list bullet.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline text::Char separator() const noexcept: Assignment separator, colon or equals.

FormatStyle &setSeparator(text::Char value) noexcept

Set assignment separator, colon or equals.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline PositionMode separatorPositionMode() const noexcept: Placement mode for the assignment separator.

FormatStyle &setSeparatorPositionMode(PositionMode value) noexcept

Set placement mode for the assignment separator.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline unit::CpCount separatorPosition() const noexcept: Spaces or target column before the separator.

FormatStyle &setSeparatorPosition(unit::CpCount value) noexcept

Set spaces or target column before the separator.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline PositionMode valuePositionMode() const noexcept: Placement mode for the first value.

FormatStyle &setValuePositionMode(PositionMode value) noexcept

Set placement mode for the first value.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline unit::CpCount valuePosition() const noexcept: Spaces or target column after the separator.

FormatStyle &setValuePosition(unit::CpCount value) noexcept

Set spaces or target column after the separator.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline IndentationStyle indentationStyle() const noexcept: Continuation indentation character.

FormatStyle &setIndentationStyle(IndentationStyle value) noexcept

Set continuation indentation character.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline unit::CpCount indentationCount() const noexcept: Positive continuation indentation count.

FormatStyle &setIndentationCount(unit::CpCount value) noexcept

Set positive continuation indentation count.

Parameters:: value – New property value.
Returns:: This object for chaining.

class FormatStylePatch

Explicitly specified formatting properties; omitted properties inherit.

Public Functions

inline std::optional<unit::CpCount> maximumLineLength() const noexcept: Soft maximum line width.

FormatStylePatch &setMaximumLineLength(unit::CpCount value) noexcept

Set soft maximum line width.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordCase> sectionNameCase() const noexcept: Case of regular section names.

FormatStylePatch &setSectionNameCase(WordCase value) noexcept

Set case of regular section names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordSeparator> sectionNameSeparator() const noexcept: Word separator in section names.

FormatStylePatch &setSectionNameSeparator(WordSeparator value) noexcept

Set word separator in section names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordCase> valueNameCase() const noexcept: Case of regular value names.

FormatStylePatch &setValueNameCase(WordCase value) noexcept

Set case of regular value names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordSeparator> valueNameSeparator() const noexcept: Word separator in value names.

FormatStylePatch &setValueNameSeparator(WordSeparator value) noexcept

Set word separator in value names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordCase> textNameCase() const noexcept: Opt-in case of quoted identifier names.

FormatStylePatch &setTextNameCase(WordCase value) noexcept

Set opt-in case of quoted identifier names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordSeparator> textNameSeparator() const noexcept: Word separator in quoted identifier names.

FormatStylePatch &setTextNameSeparator(WordSeparator value) noexcept

Set word separator in quoted identifier names.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordCase> textIdentifierCase() const noexcept: Opt-in case of identifiers in text values.

FormatStylePatch &setTextIdentifierCase(WordCase value) noexcept

Set opt-in case of identifiers in text values.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<WordSeparator> textIdentifierSeparator() const noexcept: Word separator in text identifiers.

FormatStylePatch &setTextIdentifierSeparator(WordSeparator value) noexcept

Set word separator in text identifiers.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<unit::CpCount> sectionIndent() const noexcept: Opening bracket column, or infinite for right alignment.

FormatStylePatch &setSectionIndent(unit::CpCount value) noexcept

Set opening bracket column, or infinite for right alignment.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<unit::CpCount> sectionSuffix() const noexcept: Trailing decoration width, or infinite for fill.

FormatStylePatch &setSectionSuffix(unit::CpCount value) noexcept

Set trailing decoration width, or infinite for fill.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<bool> sectionStar() const noexcept: Emit the optional closing star on list sections.

FormatStylePatch &setSectionStar(bool value) noexcept

Set emit the optional closing star on list sections.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<bool> spaceAfterOpen() const noexcept: Space after a section opening bracket.

FormatStylePatch &setSpaceAfterOpen(bool value) noexcept

Set space after a section opening bracket.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<bool> spaceBeforeClose() const noexcept: Space before a section closing bracket.

FormatStylePatch &setSpaceBeforeClose(bool value) noexcept

Set space before a section closing bracket.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<bool> spaceAroundDot() const noexcept: Spaces around section path separators.

FormatStylePatch &setSpaceAroundDot(bool value) noexcept

Set spaces around section path separators.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<ValueWrapping> valueWrapping() const noexcept: Get the explicitly selected non-multiline value placement policy.

FormatStylePatch &setValueWrapping(ValueWrapping value) noexcept: Override the placement policy for non-multiline values.

inline std::optional<VectorStyle> vectorStyle() const noexcept: Vector layout policy.

FormatStylePatch &setVectorStyle(VectorStyle value) noexcept

Set vector layout policy.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<MatrixStyle> matrixStyle() const noexcept: Matrix column alignment policy.

FormatStylePatch &setMatrixStyle(MatrixStyle value) noexcept

Set matrix column alignment policy.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<unit::CpCount> spacesAfterStar() const noexcept: Spaces after a list bullet.

FormatStylePatch &setSpacesAfterStar(unit::CpCount value) noexcept

Set spaces after a list bullet.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<text::Char> separator() const noexcept: Assignment separator, colon or equals.

FormatStylePatch &setSeparator(text::Char value) noexcept

Set assignment separator, colon or equals.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<PositionMode> separatorPositionMode() const noexcept: Placement mode for the assignment separator.

FormatStylePatch &setSeparatorPositionMode(PositionMode value) noexcept

Set placement mode for the assignment separator.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<unit::CpCount> separatorPosition() const noexcept: Spaces or target column before the separator.

FormatStylePatch &setSeparatorPosition(unit::CpCount value) noexcept

Set spaces or target column before the separator.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<PositionMode> valuePositionMode() const noexcept: Placement mode for the first value.

FormatStylePatch &setValuePositionMode(PositionMode value) noexcept

Set placement mode for the first value.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<unit::CpCount> valuePosition() const noexcept: Spaces or target column after the separator.

FormatStylePatch &setValuePosition(unit::CpCount value) noexcept

Set spaces or target column after the separator.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<IndentationStyle> indentationStyle() const noexcept: Continuation indentation character.

FormatStylePatch &setIndentationStyle(IndentationStyle value) noexcept

Set continuation indentation character.

Parameters:: value – New property value.
Returns:: This object for chaining.

inline std::optional<unit::CpCount> indentationCount() const noexcept: Positive continuation indentation count.

FormatStylePatch &setIndentationCount(unit::CpCount value) noexcept

Set positive continuation indentation count.

Parameters:: value – New property value.
Returns:: This object for chaining.

void applyTo(FormatStyle &style) const noexcept

Apply specified properties to a complete style.

Parameters:: style – Style to update.

class Formatter

Format a syntax snapshot without evaluating or altering its semantic values by default.

Public Functions

Formatter() = default: Use repository formatting defaults.

inline explicit Formatter(Format format)

Use a custom format.

Parameters:: format – Base style and selector rules.

FormatResult format(const DocumentPtr &document) const

Format valid statements while retaining damaged statements verbatim.

Parameters:: document – Original source snapshot.
Throws:: err::ParameterFailure – If the document is null or a selected style has invalid counts or separators.
Returns:: Formatted text with original-source diagnostics.

enum class erbsland::conf::syntax::IndentationStyle : uint8_t

Formatting choice for IndentationStyle.

Values:

enumerator Spaces: Indent with spaces.

enumerator Tabs: Indent with tabs.

enum class erbsland::conf::syntax::MatrixStyle : uint8_t

Formatting choice for MatrixStyle.

Values:

enumerator Keep: Preserve row spacing.

enumerator Align: Align value columns.

class Parser

Parse complete source snapshots without evaluating configuration directives.

Public Functions

DocumentPtr parseText(text::String text, SourceIdentifierPtr identifier = {}) const

Parse text, retaining source errors as diagnostics.

Parameters:

text – Original UTF-8 source snapshot.
identifier – Optional source identity, defaulting to an in-memory source.

Returns:

A lossless document, including when the input contains syntax errors.

enum class erbsland::conf::syntax::PositionMode : uint8_t

Formatting choice for PositionMode.

Values:

enumerator Spaces: A fixed number of separating spaces.

enumerator Column: A zero-based target code-point column.

class Selector

Conditions selecting statements; conditions combine with AND and path alternatives with OR.

Public Functions

Selector &setKind(Statement::Kind value): Select the statement kind.

Selector &setListSection(bool value): Select list or map sections.

Selector &setRelativeSection(bool value): Select relative or absolute sections.

Selector &setMinimumSectionNames(std::size_t value): Select headers declaring more than this many names.

Selector &setMetaValue(bool value): Select meta or ordinary assignments.

Selector &setValueTypes(std::vector<ValueType> values): Select any of these recognized value types.

Selector &addPath(const text::String &pattern)

Add an alternative normalized name-path glob.

Parameters:: pattern – Glob text; a whole-component ** crosses name boundaries.
Throws:: err::ParseError – If the pattern is malformed.

std::optional<std::array<int, 6>> match(const Statement &statement) const

Get matching specificity, or no value when any condition fails.

Parameters:: statement – Statement to inspect.
Returns:: Path specificity followed by the count of other conditions.

class Statement

One section declaration or assignment, including all its continued lines.

Public Types

enum class Kind

Statement categories.

Values:

enumerator Section

enumerator Assignment

Public Functions

inline Kind kind() const noexcept: Get the statement category.

inline bool hasErrors() const noexcept: Test whether formatting must preserve this statement verbatim.

inline bool isListSection() const noexcept: Test whether this is a list section.

inline bool isRelativeSection() const noexcept: Test whether the section path was relative.

inline bool isMetaValue() const noexcept: Test whether this is a meta assignment.

inline std::size_t sectionNameCount() const noexcept: Get the number of names written in a section header.

inline const std::optional<NamePath> &namePath() const noexcept: Get the locally resolved path, when available.

inline ValueType valueType() const noexcept: Get the recognized assignment value type.

inline unit::ByteRange range() const noexcept: Get the original source range including its final newline.

inline unit::ItemIndex firstToken() const noexcept: Get the first token index.

inline unit::ItemIndex endToken() const noexcept: Get the exclusive last token index.

class Token

An owning, unmodified source slice with its lexical classification.

Public Functions

inline TokenKind kind() const noexcept: Get the lexical classification.

inline const text::String &text() const noexcept: Get the source text, including delimiters.

inline unit::ByteRange range() const noexcept: Get the half-open original byte range.

inline unit::CodeLocation location() const noexcept: Get the original starting location.

inline const text::String &decodedText() const noexcept: Get decoded text for names and textual literals; empty for other tokens.

using erbsland::conf::syntax::TokenPtr = std::shared_ptr<Token>: Shared ownership of a syntax token.

class TokenKind

Source token classification, independent of decoded values.

Public Types

enum Value

The lexical token classifications.

Values:

enumerator EndOfData: The end of the data.

enumerator LineBreak: A line-break.

enumerator Spacing: A block of spacing.

enumerator Indentation: A block with indentation.

enumerator Comment: A comment.

enumerator RegularName: A regular name.

enumerator TextName: A text name.

enumerator MetaName: A metaname.

enumerator NameValueSeparator: A value separator :

enumerator ValueListSeparator: A value list separator ,

enumerator MultiLineValueListSeparator: A multi-line value separator *

enumerator NamePathSeparator: A name path separator. .

enumerator Integer: An integer literal.

enumerator Boolean: A boolean literal.

enumerator Float: A floating point literal.

enumerator Text: A single line text.

enumerator MultiLineTextOpen: The start of a multi-line text.

enumerator MultiLineTextClose: The end of a multi-line text.

enumerator MultiLineText: A line of multi-line text.

enumerator Code: A single line code.

enumerator MultiLineCodeOpen: The start of multi-line code.

enumerator MultiLineCodeLanguage: The language identifier.

enumerator MultiLineCodeClose: The end of multi-line code.

enumerator MultiLineCode: A line of multi-line code.

enumerator RegEx: A single line regex.

enumerator MultiLineRegexOpen: The start of multi-line regex.

enumerator MultiLineRegexClose: The end of multi-line regex.

enumerator MultiLineRegex: A line of multi-line regex.

enumerator Bytes: A single line block of bytes.

enumerator MultiLineBytesOpen: The start of multi-line bytes.

enumerator MultiLineBytesFormat: The format multi-line bytes.

enumerator MultiLineBytesClose: The end of multi-line bytes.

enumerator MultiLineBytes: A line of multi-line bytes.

enumerator Date: A date.

enumerator Time: A time.

enumerator DateTime: A date/time.

enumerator TimeDelta: A time-delta.

enumerator SectionMapOpen: The start of a section map.

enumerator SectionMapClose: The end of a section map.

enumerator SectionListOpen: The start of a section list block.

enumerator SectionListClose: The end of a section list block.

enumerator Error: Unrecognized source retained after a line error.

enumerator SectionName: A regular name in a section declaration.

enumerator SectionTextName: A quoted name in a section declaration.

Public Functions

constexpr TokenKind() noexcept = default: Create an error classification.

inline constexpr TokenKind(const Value value) noexcept

Create a token classification from its raw value.

Parameters:: value – The lexical classification.

bool isValue() const noexcept: Test whether this token is a complete single-line literal.

bool isPayload() const noexcept: Test whether this token contains multiline literal payload.

inline constexpr Value raw() const noexcept: Get the raw lexical classification.

ValueType toValueType() const noexcept

Map a complete literal or multiline opening delimiter to its value category.

Returns:: The value type, or ValueType::Undefined for all other tokens, including multiline payload.

text::String toText() const noexcept

Convert this classification to its standardized diagnostic name.

Returns:: The token name, or empty text for an unknown raw value.

Public Static Functions

static inline constexpr TokenKind fromMultiLineOpen(const text::Char character) noexcept

Convert a multi-line opening delimiter character to its classification.

Parameters:: character – The repeated delimiter character (", backtick, / or <).
Returns:: The opening token kind, or EndOfData for an unrecognized character.

static inline constexpr TokenKind fromMultiLineClose(const text::Char character) noexcept

Convert a multi-line closing delimiter character to its classification.

Parameters:: character – The repeated delimiter character (", backtick, / or >).
Returns:: The closing token kind, or EndOfData for an unrecognized character.

enum class erbsland::conf::syntax::ValueWrapping

Placement policy for values without multiline literal payloads or list bullets.

Values:

enumerator Keep: Preserve whether the value starts on the assignment line or the next line.

enumerator SameLine: Put the complete value on the assignment line, even if it exceeds the soft limit.

enumerator NextLine: Put the complete value on an indented continuation line.

enumerator NextLineIfFits: Move an overlong value only when its continuation line fits the soft limit.

enumerator WhenTooLong: Move an overlong value even when its continuation line also exceeds the limit.

enum class erbsland::conf::syntax::VectorStyle : uint8_t

Formatting choice for VectorStyle.

Values:

enumerator Keep: Preserve row layout.

enumerator Compact: Use one line when it fits.

enumerator Multiline: Use one value per continued line.

enum class erbsland::conf::syntax::WordCase : uint8_t

Formatting choice for WordCase.

Values:

enumerator Keep: Preserve spelling.

enumerator Lower: Lowercase words.

enumerator Title: Capitalize each word.

enumerator Upper: Uppercase words.

enum class erbsland::conf::syntax::WordSeparator : uint8_t

Formatting choice for WordSeparator.

Values:

enumerator Space: Separate words with spaces.

enumerator Underscore: Separate words with underscores.