Named-Key Parsing

Format describes the aliases, separators, value policy, and limits of a named-key entry list. Parser reads from a StringCharReader and returns Entry values. Entries may carry a recognized key, a keyed value, or a positional value. Invalid syntax raises a positioned err::ParseError.

The format must outlive its parser. Register normalized aliases with semantic integer identifiers before reading. readEntry() returns a terminal entry at the end; readAllEntries() excludes that entry.

Interface

class Entry

One entry produced by Parser.

Public Functions

Entry() = default

Create the terminal entry.

inline Entry(EntryKind kind, Char prefix, int keyIndex, String value) noexcept

Create an entry with all parsed fields.

inline bool isKey() const noexcept

Test if this is a key without a value.

inline bool isKeyWithValue() const noexcept

Test if this is a key with a value.

inline bool isValue() const noexcept

Test if this is a positional value.

inline bool isEnd() const noexcept

Test if this is the terminal entry.

inline bool hasValue() const noexcept

Test if this entry has a keyed or positional value.

inline EntryKind kind() const noexcept

Get the entry kind.

inline Char prefix() const noexcept

Get the optional key prefix.

inline int keyIndex() const noexcept

Get the key identifier, or -1 for non-key entries.

inline const String &value() const noexcept

Get the value, or an empty string for entries without a value.

enum class erbsland::text::named_key::EntryKind : uint8_t

The kind of one parsed named-key entry.

Values:

enumerator Key

A key without a value.

enumerator KeyWithValue

A key with an explicit or compact value.

enumerator Value

A positional value.

enumerator End

The configured end of the entry list.

class Format

The grammar and key table for Parser.

Public Types

using Keys = util::List<Key>

The list of key aliases.

Public Functions

Format() = default

Create the default named-key format.

Format &setKeys(std::initializer_list<Key> keys)

Replace all key aliases.

Format &setKeys(Keys keys)

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

Format &addKey(String name, int index)

Add one key alias.

std::optional<int> keyIndex(const String &key) const

Find a semantic key identifier from any supported spelling.

const String &keyName(int keyIndex) const

Get the first registered normalized alias for a semantic key identifier.

Parameters:

keyIndex – The semantic key identifier. Must be registered in this format.

inline const util::List<Key> &keys() const noexcept

Get all registered key aliases.

Format &setUniqueKeysRequired(bool enabled) noexcept

Require each semantic key at most once.

inline bool uniqueKeysRequired() const noexcept

Test if each semantic key is limited to one occurrence.

Format &setKeysWithoutValuesAllowed(bool enabled) noexcept

Allow recognized keys without values.

inline bool keysWithoutValuesAllowed() const noexcept

Test if recognized keys without values are allowed.

Format &setValuesAllowed(bool enabled) noexcept

Allow values attached to recognized keys.

inline bool valuesAllowed() const noexcept

Test if values attached to recognized keys are allowed.

Format &setValueListAllowed(bool enabled) noexcept

Allow a positional value list.

inline bool valueListAllowed() const noexcept

Test if a positional value list is allowed.

Format &setMaximumValues(unit::ItemCount maximum) noexcept

Set the maximum number of positional values.

inline unit::ItemCount maximumValues() const noexcept

Get the maximum number of positional values.

Format &setMaximumValueLength(unit::CpCount maximum) noexcept

Set the maximum value length in code points.

inline unit::CpCount maximumValueLength() const noexcept

Get the maximum value length in code points.

Format &setListSeparator(Char separator) noexcept

Set the entry-list separator.

inline Char listSeparator() const noexcept

Get the entry-list separator.

Format &setValueSeparator(Char separator) noexcept

Set the separator between a key and its value.

inline Char valueSeparator() const noexcept

Get the separator between a key and its value.

Format &setStopCharacter(Char character) noexcept

Set the required stop character, or end-of-data for an end-terminated list.

inline Char stopCharacter() const noexcept

Get the required stop character.

Format &setAllowedKeyPrefixes(CharSet characters) noexcept

Set the optional key prefix characters.

inline const CharSet &allowedKeyPrefixes() const noexcept

Get the optional key prefix characters.

Format &setAllowedValueChars(CharSet characters) noexcept

Set the allowed value characters. An empty set permits every safe character.

inline const CharSet &allowedValueChars() const noexcept

Get the allowed value characters.

Format &setValueWithoutKeySeparatorChars(CharSet characters) noexcept

Set characters that start a compact value immediately after a key.

inline const CharSet &valueWithoutKeySeparatorChars() const noexcept

Get characters that start a compact value immediately after a key.

void validate() const

Validate this format before parsing.

The format must have valid, unambiguous key names and separators.

struct Key

One normalized key alias and its semantic identifier.

Public Functions

void validate() const

Validate this key entry.

Public Members

String name

The key alias.

int index = {}

The semantic key identifier.

class Parser

A low-level parser for named-key and positional-value entry lists.

All syntax errors are reported as positioned err::ParseError exceptions.

Public Functions

Parser(StringCharReader &reader, const Format &format)

Create a parser at the first entry.

Parameters:

• format – The named-key format. Must be valid and unambiguous.

• reader – The input reader, positioned at the first entry.

inline const Format &format() const noexcept

Get the active format.

void setAllowedKeys(util::Set<int> keys)

Restrict recognized keys to the given semantic identifiers.

Entry readEntry()

Read one entry or the terminal entry.

Throws:

err::ParseError – for invalid syntax.

util::List<Entry> readAllEntries()

Read all remaining entries, excluding the terminal entry.

Throws:

err::ParseError – for invalid syntax.