Glossary

Absolute Section

An absolute section is a section that starts with a name, rather than with a name separator (.). The name path of absolute sections always start at the document root.

[section]
[section.subsection.another]
[section.special."text"]

→ Read Section Names for details.

Boolean

A boolean value represents a logical truth value, typically expressed as Yes/No or True/False in ELCL.

→ Read Boolean Value for details.

Byte

A byte is a unit of digital information that typically consists of eight bits. In the context of ELCL, line lengths and some other specifications are measured in bytes, not characters.

→ Read Line Break for details.

Bytes

Byte-Data

A byte-data value allows raw byte-data to be represented directly within an ELCL configuration file.

→ Read Byte-Data Values for details.

Case-Insensitive

Case-insensitive means that uppercase and lowercase letters are treated as equivalent. For example, the strings example and EXAMPLE would be considered the same.

→ Read Names for details.

Case-Sensitive

Case-sensitive means that uppercase and lowercase letters are treated as distinct. For example, the strings example and EXAMPLE would be considered different.

→ Read Names for details.

Character

A character is any letter, digit, symbol, or control code that represents text in a computer system. In ELCL, characters are encoded according to the UTF-8 standard, therefore the number of bytes per character varies.

→ Read Characters for details.

Code

A code value in ELCL represents a code block, allowing formatted text or instructions to be embedded within configuration files.

→ Read Code Text Values for details.

Code-Point

Code Point

A code-point is a unique number assigned to each character in a character set, such as Unicode. It identifies a character within the standard, enabling consistent representation across different systems.

→ Read Characters for details.

Comment

In ELCL, comments are used to annotate the configuration without affecting the document’s structure or content.

# A comment in the first line.
[main]       # A comment after an element.
value:       # Unicode → but no control characters
    "text"   # Comment

→ Read Comments for details.

Control Characters

Most Unicode control characters are not allowed in ELCL documents. As control characters count all characters in the Unicode Category “Cc” (Control Codes). This are the ranges U+0000–U+001F and U+007F-U+009F. There are three exceptions: The newline \n and carriage-return character \r for the line breaks and the tab character \t that counts as spacing.

As ELCL documents must have a valid UTF-8 encoding, which adds more disallowed code points. The following list is a complete list of disallowed code points:

U+0000 – U+0008: Part of the control characters set.
U+000B – U+000C: Part of the control characters set.
U+000E – U+001F: Part of the control characters set.
U+007F – U+009F: Part of the control characters set.
U+D800 – U+DFFF: Low- and high surrogates aren’t allowed in UTF-8 encoding.
U+110000 – U+FFFFFFFF: The valid unicode range ends at U+10FFFF

→ Read Characters for details.

Core Language

The core language in Erbsland Configuration Language (ELCL) encompasses the essential syntax and features required for any compliant parser. It includes basic elements like sections, name-value pairs, and standard value types.

→ Read Core Language for details.

Date

A date value specifies a calendar date in a standard format within ELCL configurations.

→ Read Date, Time, and Date-Time Values for details.

Date-Time

A date-time value combines both date and time, used to specify an exact moment in ELCL.

→ Read Date, Time, and Date-Time Values for details.

Digit

In the context of ELCL, a digit refers to the characters 0 – 9.

All possible digits

0123456789

→ Read Characters for details.

Document

ELCL configuration documents must be encoded in UTF-8. A document can contain almost all valid Unicode characters, except control characters with a few exceptions.

A ELCL document is line based, and therefore a document is defined as a sequence of lines separated by line breaks.

→ Read Characters for details about the encoding of documents.

Document Root

In the context of ELCL, the document root is the lowest level where sections can be configured. Other than inside of sections, the document root cannot contain any name-value pairs. As starting from the first section line, all name-value pairs are part of one section, the only place for values in the document root is at the beginning of a document. All values defined in the document root must be meta values.

# Here is the document root
@version: "1.0"   # Only meta values are allowed on the document root

[section] # After this section, the document root is inaccessible.
Name: "Value"

→ Read Name Paths for details.

ELCL

ELCL stands for the Erbsland Configuration Language, a human-centric configuration format.

→ Read Introduction for details.

Error

In the context of ELCL, an error refers to a problem encountered during the parsing process, indicating that the document does not adhere to the expected syntax or rules. Common errors include issues like invalid line breaks, unsupported characters, or violations of length restrictions.

Errors detected during parsing are reported using a predefined set of error codes and accompanied by an error source. The parser also provides detailed information about the error’s location, including the exact line and column number where the issue occurred.

→ Read Error Categories and Codes for details.

Error Code

An error code is a standardized identifier used to report specific errors encountered during the document parsing process. While a parser may offer additional details about the nature of an error, each error is categorized using one of the predefined error codes. This standardization ensures consistent error handling across different parser implementations, making it easier for applications to manage errors in a uniform way, regardless of the parser being used.

→ Read Error Categories and Codes for details.

Error Source

The error source is a required component of every error report generated by a parser. It typically includes the path or identifier of the data source being parsed, along with the exact line and column where the error occurred. This information helps to pinpoint the origin of the issue within the document and aids in troubleshooting.

→ Read Error Categories and Codes for details.

Escape Sequence

An escape sequence in Erbsland Configuration Language (ELCL) allows special characters to be included in text values without disrupting the syntax. Escape sequences start with a backslash (\), followed by a specific character or code that represents the desired special character. They are used to add non-printable characters, symbols, or Unicode characters directly within text values.

ELCL supports the following escape sequences:

\\: Inserts a literal backslash.
\": Inserts a double quote.
\$: Inserts a dollar sign.
\n: Inserts a newline character.
\r: Inserts a carriage return character.
\t: Inserts a tab character.
\uXXXX: Inserts a Unicode character specified by exactly four hexadecimal digits (XXXX).
\u{Y}: Inserts a Unicode character specified by one to eight hexadecimal digits (Y).

→ Read Text for details.

Feature

A feature in the Erbsland Configuration Language (ELCL) represents an optional or advanced capability that a parser may support. ELCL includes both core features, which are required for basic functionality, and additional features, which enhance the language’s flexibility and allow for more complex configurations.

Features in ELCL are grouped into tiers, each tier providing a specific set of capabilities. Depending on the parser’s tier—such as Micro-Parser, Minimal Parser, Standard Parser, or Full-featured Parser—certain features may or may not be supported. This tiered approach allows implementations to range from lightweight parsers suitable for embedded systems to comprehensive parsers supporting the full ELCL specification.

→ Read Parser Tiers for details.

Floating-Point

Floating-Point Value

Floating-Point Number

In the context of ELCL, floating-point values are numbers as specified by the ISO/IEC 60559:2020 standard. The representation of these number shall follow the decimal format described in chapter 5.12 in this document. A parser should at least handle the floating-point values in the size and with the limitations as specified as binary64 in this standard, the parser can support a higher precision.

Note

Naturally, parsers are written for various programming languages and platforms, each with slightly different internal floating-point value representations. This can and will lead to minimal differences between implementations, which is an issue in the responsibility of the application to address.

For the representation of floating-point values in ELCL, the following rules and limitations apply:

A floating point number must have exact one decimal point . present.
A maximum of 32 digits before the decimal point are allowed.
A maximum of 32 digits after the decimal point are allowed.
A maximum of 6 digits for the exponent are allowed.

[section]
Floating Point 01: .0
Floating Point 02: NaN
Floating Point 03: INF
Floating Point 04: 2937.28301
Floating Point 05: 12e+10
Floating Point 06: -12.9
Floating Point 07: -8'283.9e-5

→ Read Floating-Point Value for details.

Full-featured Parser

A full-featured parser implements the complete set of features defined by the ELCL specification. This tier supports every aspect of the language, including advanced features, making it suitable for applications that require the highest level of configurability and flexibility.

→ For more details, refer to Parser Tiers.

Integer

Integer Value

In the context of ELCL, an integer is an integral data type that can be positive or negative. Integral data types may be of different sizes and may or may not be allowed to contain negative values. The supported range is that of a signed 64-bit value. Micro-parsers support signed 32-bit values.

Integer values can be written as decimal, hexadecimal and binary numbers. Full-featured parsers also support byte counts. The ' character is supported as separator in all formats.

[section]
Integer 01: 12'293
Integer 02: -9006
Integer 03: 0xab34
Integer 04: 0x1'0000'0000
Integer 05: 0b10010010
Integer 06: 100 kb

→ Read Integer Values for details .

Intermediate Section

An intermediate section is a special type of section that is implicitly created when a configuration uses name paths. Unlike regular sections, intermediate sections do not need to be explicitly defined in the configuration. Consider the following example:

[one.two.three.four]
value: 123

This configuration creates one regular section, four, and three intermediate sections along the path.

● (root)                    <== Document ( size=1 ) 
└── [one]                   <== IntermediateSection (  ) 
    └── [two]                   <== IntermediateSection (  ) 
        └── [three]                 <== IntermediateSection (  ) 
            └── [four]                  <== SectionWithNames ( size=1 ) 
                └── value                   <== Integer ( 123 ) 

The key distinction between a regular section and an intermediate section becomes important when you create new sections with the same name path. Each value or section must be defined only once in a configuration, but intermediate sections are an exception to this rule because they are created implicitly. In the example above, you can later define sections for one, one.two, and one.two.three without causing a name conflict.

[one.two.three.four]
value: 123

[one]  # This is allowed.
value: 456

[one.two.three]  # This is also allowed.
value: 789

[one.two.three.four]  # Error! This name path is already in use.
another value: "text"

As shown, redefining the section one.two.three.four causes an error because it was already explicitly defined earlier in the configuration. However, defining any of the intermediate sections created implicitly by the name path is perfectly valid and does not result in a conflict.

→ Read Section Names for details.

Language Version

The language version in Erbsland Configuration Language (ELCL) specifies the version of the ELCL syntax that a document conforms to. Defining a language version ensures compatibility between configuration documents and parsers by indicating the expected syntax rules and features supported in the document.

In an ELCL document, the language version is typically defined using a meta value at the beginning of the configuration file. This version identifier allows parsers to validate that they support the required language features before processing the document.

@version: "1.0"  # Specifies that the document uses ELCL version 1.0

Specifying a language version is essential for future-proofing configurations, as it allows new features or syntax changes to be introduced in future versions of ELCL without disrupting backward compatibility. If a parser encounters a document with an unsupported language version, it should raise an error or warning.

→ Read Meta Values and Commands for details.

Letter

In the context of ELCL, a letter refers to the characters a – z and A – Z. Since ELCL names are case-insensitive, the use of uppercase or lowercase letters does not affect comparison.

All possible letters

abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ

→ Read Characters for details.

Level

The level in the context of ELCL means how many names build the name path up to a section or value. The document root has level zero, while all root sections have level one. Each subsection adds one level to that. Other from counting names, the term has no functional meaning.

[section]       # This section is at level 1
Name: "Value"   # "Name" is at level 2: section.Name

[one.two]       # This section is at level 2
Three: "Value"  # "Three" is at level 3: one.two.Three

→ Read Name Paths for details.

Line

ELCL documents are organized in lines. Lines in a document are seperated by line breaks.

→ Read Line Break for details.

Line Break

Line Ending

A line break in ELCL can be one of the following:

A single newline (\n).
A Windows-style carriage-return followed by a newline (\r followed by \n).

→ Read Line Break for details.

Meta Command

A meta command is a name-value pairs, where the name is prefixed with an @ character, but compared to meta values, it can be specified multiple times in the document and also between section blocks. Version “1.0” of ELCL only supports the @include meta command.

[first_section]
Name: "Value"

@include: "configuration/extension.ecl"

[another_section]
Name: "Value"

Meta Value

Meta values are name-value pairs, where the name is prefixed with an @ character. They can have various uses, like define the used ELCL language version, required features, or parser specific values.

Meta values must be configured at the very beginning of the document, before the first section.

@version: "1.0"
@features: "regex, timedelta"

[section]
Name: "Value"

Version “1.0” of ELCL, supports the @version, @features, @signature and @parser_... meta values.

Micro-Parser

In ELCL, a micro-parser is the most minimal form of a parser, supporting only a basic subset of features. This variant is specifically designed to operate in environments with limited computational resources, such as embedded systems.

→ For more details, refer to Parser Tiers.

Minimal Parser

A minimal parser in ELCL is required to implement the core elements of the language, including the Core Language and support for floating-point values. It provides a foundational level of functionality suitable for lightweight applications, without delving into more complex or advanced features.

→ For more details, refer to Parser Tiers.

Multi-line Text

Multi-line Text Value

Multi-line text is a special form of text that can span multiple lines. It is enclosed in two sets of three " characters. The text itself must not start directly after the starting """, there must be an initial line break. The same is true for the end of the text, the ending """ must be placed on its own line.

Similar to regular text, no control characters, except line breaks and the tab character are allowed, but you can use escape sequences to add them.

[section]
Name 01: """      # A multi-line text.
    A multi_line text
    with a "second" line.
    """
Name 02: # Another multi-line text, starting after a line break.
    """
    A multi_line text
    starting after a line break.
    """

Spacing and line breaks up to the begin of the text on the second line are removed and do not count as part of the text. Also the character sequence you used to indent the first line of your text is removed from any subsequent lines. The line break and spacing at the end of your text, up to the closing """ are removed as well. If you require a line break at the end of your text, you must insert an empty line at the end.

→ Read Multi-line Text Values for details.

Name

A name can be part of a section or define a value inside a section. Names must always start with a letter, followed by a combination of letters, digits, underscores or spaces. Names are case-insensitive, meaning that Example, example, and EXAMPLE are considered identical.

→ Read Names for details.

Name Conflict

In the Erbsland Configuration Language (ELCL), a name conflict occurs when a section or value attempts to reuse a name or name path that has already been defined within the configuration. Since ELCL requires that each name or path be unique within its context, reusing a name results in an error.

Most common name conflicts are:

Duplicate Sections: Defining the same section more than once with an identical name path leads to a conflict, as shown below.
[settings] enabled: Yes [settings] # ERROR! The name "settings" is already in use. timeout: 30
Duplicate Values: Attempting to define a value more than once within the same section will result in a conflict.
[settings] enabled: Yes enabled: No # ERROR! The name "enabled" is already in use.
Mixed Sections and Values: Using the same name for both a section and a value in the same hierarchy causes a conflict.
[database] host: "localhost" [database.host] # ERROR! The name "database.host" is already used as a value.

→ Read Name Conflicts for details.

Name Path

In the context of ELCL, a name path is a sequence of one or more names, separated by a period (.). Name paths are used to define precise locations within sections of a configuration document or within the API of a parser to retrieve values from the document.

In configuration files, a name path specifies the hierarchy leading to a particular value. In the API, it allows for easy access to values by referencing their location in the configuration.

A name path in a configuration document section.

[one.two.three]
value: 123

A name path in application code to retrieve a value.

auto value = configuration->getInteger("one.two.three.value");

→ Read Name Paths for details.

Name Separator

The name separator is the period (.) character. It separates multiple names of a name path that is used for a section.

[ section . subsection ]  # Two names separated with the '.'
[one.two.three]           # Three names separated with the '.'
[.four]                   # A relative section, starting with '.'

→ Read Name Paths for details.

Name-Value Pair

A name-value pair consists of a name followed by a value, separated by a value separator. It represents a single structure within a section. A more commonly used term is “key/value pair”.

→ Read Named Values for details.

Number

In the context of ELCL, a number can be either an integer value or floating-point value. This term only plays a role for validating ELCL documents, where number adds more flexibility.

→ Read Integer Values and Floating-Point Value for details.

Optional Feature

An optional feature in the Erbsland Configuration Language (ELCL) is a non-mandatory capability that a parser may implement based on its designated tier. Optional features add flexibility and advanced functionality but are not required for basic ELCL compliance. Examples include support for complex data types like regular expressions and time deltas.

→ Read Parser Tiers for details.

Parser

A parser is a software library designed to read and interpret configuration files in the Erbsland Configuration Language (ELCL). Parsers can be developed for any programming language or platform, offering either a document model or an event-based approach to access the configuration values. Each parser can support a variety of features, allowing it to be classified into one of the defined Parser Tiers.

→ For more details, refer to Parser Tiers.

Parser Tier

ELCL defines four standardized parser tiers to simplify and organize the implementation of parsers. Each tier corresponds to a specific set of features, making it easier to describe and categorize a parser’s functionality.

Micro-Parser: The smallest parser tier, designed for embedded systems with limited resources.
Minimal Parser: Implements the Core Language and supports floating-point values.
Standard Parser: Implements most features of ELCL, with only a few advanced features omitted.
Full-featured Parser: Implements the entire ELCL specification, with all available features.

→ For detailed information, see Parser Tiers.

Regular Expression

A regular expression is a pattern used for matching text within ELCL, supporting complex search and validation operations.

→ Read Regular Expression Values for details.

Relative Section

A relative section is a section that starts with a name separator (.). It forms a subsection on the last absolute section in the document. Multiple relative subsections do not accumulate hierarchically but reset with each new relative section. Also, an ELCL document must not begin with a relative section.

[section]
[.sub]                    # Relative section => section.sub
[.subsection.another]     # Relative section => section.subsection.another
[block]
[."text section"]         # Relative section => block."text section"

→ Read Sections for details.

Root Section

A root section is a section that is at the document root, and is therefore defined with one single name.

[root_section]             # A root section.
[another_root_section]     # Another root section.

→ Read Name Paths for details.

Section

A section in ELCL starts with a name, or a sequence of nested names, enclosed in square-brackets. Sections organize name-value pairs in logical groups.

[section]                  # Regular section with one name.
Name: "Value"

[section.subsection]       # Section with one subsection.
Name: "Value"

[.another]                 # Relative section => section.subsection.another
Name: "Value"

[special."text"]           # Text section
Name: "Value"

Spacing is allowed inside the enclosing brackets, between the names and separators.

[  section  .  name  ]     # Use spacing around the names if you like.
Name: "Value"

If an asterix character * prefixes the starting square bracket [, a section list is created. Optionally you can repeat the asterix character after the closing bracket ].

*[section.list_sections]   # The first entry of a section list.
Name: "Value"

*[section.list_sections]   # The second entry of a section list.
Name: "Value"

*[section.list_sections]*  # You can repeat the `*` after the closing bracket.
Name: "Value"

Also, you can surround the enclosing brackets with the minus character - to visually enhance the separation of individual sections.

------------[ First Section ]-------------   # Use `-` for a visual separation
Name: "Value"

---*[      List Section      ]*---
Name: "Value"

→ Read Sections for details.

Section List

A section list in ELCL allows for repeated sections with the same name path, where each instance of the section represents an individual entry in the list. This structure is useful for configurations requiring multiple items under a single logical grouping, such as server connections, filters, or other repeatable elements.

Section lists are created by prefixing the section name with an asterisk (*), allowing multiple entries with the same name path without causing a name conflict.

*[servers]
name: "web-server-1"
address: "192.168.1.10"

*[servers]
name: "web-server-2"
address: "192.168.1.11"

*[servers]
name: "database-server"
address: "192.168.1.12"

In the example above, the servers section list contains three unique entries, each identified by its own properties while sharing the same logical grouping. The asterisk placement—either at the start, end, or both—does not affect the structure but helps visually distinguish list entries.

→ Read Sections for details.

Space

The space character (singular) refers specifically to the following space character .

→ Read Characters for details.

Spacing

In the context of ELCL, spacing (plural) can be any combination of the space character ( ) and the horizontal tab (\t). This does not include characters that form a line break (\r and \n).

→ Read Spacing for details.

Square-Brackets

Square-brackets are the characters [ and ].

→ Read Characters for details.

Standard Parser

A standard parser provides a more robust implementation of the ELCL, supporting most features except for a few advanced options. This tier is ideal for applications that need a comprehensive set of configuration language features without requiring the full extent of the specification.

→ For more details, refer to Parser Tiers.

Subsection

The differentiation of a subsection, compared to a root section is just its level in the section hierarchy. There is nothing special about subsections, except they are not at the document root. The distinction between subsections and root sections only matters for special features like text sections, which always must be subsections.

[root_section.sub]                 # A subsection.
[root_section.sub.sub]             # Another subsection.
[another_root_section.another]     # Another subsection.

→ Read Section Names for details.

Tab

The tab refers to the horizontal tab character \t.

→ Read Characters for details.

Text

Text Value

Text can be either a type of value, a special form of a subsection or also a special form to name values in a section. Text is enclosed in two " characters.

Text must not contain control characters, but can use escape sequences to add them to the text. Regular text must not contain line breaks, these are only allowed in multi-line text.

[section]
Name 01: "Simple" # A simple text "Simple"
Name 02: "→→→😄📝←←←" # Text with Unicode characters.
Name 03: "\r\n\"\u{20}\u2192\u{1F606}" # Text with escape sequences

→ Read Text for details.

Text Name

Text names are used for special cases where a single-line text is mapped to a section or a value. A text name is essentially a double-quoted string, as defined in the Text chapter.

→ Read Text Names for details.

Text Section

Text sections are a special form of subsections where its name is formed with a text value. This is an optional feature not all parsers must support.

[block."A text section"]           # A text section.
[block."Example"]                  # A text section.

→ Read Section Names for details.

Time

A time value indicates a time of day, formatted according to ELCL standards.

→ Read Date, Time, and Date-Time Values for details.

Time Delta

A time delta represents a duration or time interval, allowing relative time specifications in ELCL.

→ Read Time-Delta Values for details.

Underscore

In the context of ELCL, the underscore is character _.

→ Read Characters for details.

Unicode

A computing industry standard for consistent encoding, representation, and handling of text expressed in most of the world’s writing systems. Each character is assigned a unique number called a code-point, which identifies it in the Unicode standard.

→ Read Characters for details.

UTF-8

UTF-8 is a variable-width character encoding. It is capable of encoding all possible characters in Unicode and is the required encoding format for ELCL documents.

→ Read Characters for details.

Value

A value follows after a name in a section after the value separator. In can be text, a number or more specifically an integer or floating-point number, or one of many other value types and value formats.

Values must never start or being continued at the beginning of a line. There must always be a value separator or spacing in front of a value.

[section]
Name 01: 8'039                # An integer value
Name 02: 0x92ac               # An integer value, in hexadecimal format.
Name 03: 0b10010101           # An integer value, in binary format.
Name 04: No                   # A boolean value.
Name 05: 12.9e+7              # A floating point value
Name 06: "text"               # A text value
Name 07: 4, 5, 6              # Three values in a list
Name 08:
    "text"                   # A text value, starting in a new line.
Name 09: """                  # A multi-line text.
    Multi-line
    Text
    """
Name 10: 09:30:00Z            # Time value.
Name 11: 2024-08-31           # Date value.
Name 12: 2024-08-31 09:40:00  # Date/time value.
Name 13: <45 72 62 73 6c 61 6e 64>  # A byte-data value

→ Read Named Values for details.

Value Format

For the same value type, there are often several formats in which the same value can be configured. For example the integer value has several formats to use:

[section]
Integer 01: 12'293
Integer 02: 0xab34
Integer 03: 0b10010010
Integer 04: 100 kb

The same is true for the text type, that can be written as simple and multi-line text, and with Full-featured parsers also as code.

→ Read Named Values for details.

Value List

A value list in ELCL is an ordered sequence of values, which can be defined on a single line or across multiple lines, allowing multiple values to be grouped under a single name.

→ Read Single-Line Value Lists and Multi-line Value Lists for details.

Value Map

A value map is a collection of name-value pairs within an ELCL section, where each key uniquely identifies a value. It serves as a way to group related data.

→ Read Named Values for details.

Value Separator

The value separator distinguishes a name from its corresponding value. In ELCL, it can be either be the character : or alternatively =. Spacing is allowed before and after the separator, also a line break is allowed after the separator, before the configured value starts.

[section]
Name 01: "Value"
Name 02 = "Value"
Name 03        : "Value"
Name 04:
    "Value"

→ Read Named Values for details.

Value Tree

The value tree is the hierarchical structure representing ELCL configurations, where sections and values are organized in a nested, tree-like format based on their name paths.

→ Read Name Paths for details.

Value Type

There are several value type in ELCL. The core value types are: Integer, Text, and Boolean. Standard parsers also support Floating-Point, Date, Time and Date-Time. Full-featured parsers also support the following types: Byte-Data, Time Delta, and Regular Expression.

It is important to note, that the value type is not the same as the value format. While the value type is something a parser returns to the application, the same type can often be written in many different formats.

→ Read Named Values for details.