Text Names

In the Erbsland Configuration Language (ELCL), 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.

text_name           ::= text

[filter."😀"]         # A section with a text name.
value: 123

[Translation.jp]      # A section with values that use text names.
"Good Morning!"       = "おはようございます！"
"Have a great day!"   = "良い一日をお過ごしください！"
"What is your name?"  = "お名前は何ですか？"

The syntax of text names follows the same rules as those used for values. However, there are additional restrictions when text names are applied in specific contexts, such as sections or as a name for values.

Important

A parser is not required to perform Unicode normalization on text names.

Text names can be processed internally as UTF-8 encoded byte-data. It is the responsibility of the application to manage Unicode normalization or apply any additional text checks, depending on its use case.

Text Name Rules

The following rules for text names apply not only to sections, but also to the names of values within a section.

Do Not Mix Text Names and Regular Names: Text names and regular names must not be mixed within the same section. If a section contains a regular name and the parser encounters a text name, it must raise a NameConflict error.
```
[text_names_for_values]
name: 123
"text": 123     # ERROR! Regular and text names must not be mixed.
```
```
[section.name]
name: 123
[section."text"]   # ERROR! Regular and text names must not be mixed.
name: 123
```
Unique Names: All names, whether regular or text names, must be unique within a section. Refer to Name Comparison for detailed information. If the parser encounters a duplicate name, it must raise a NameConflict error.
```
[unique_names]
name: 123
name: 123  # ERROR! Names must be unique.
```
```
[unique_text_names]
"text": 123
"text": 123  # ERROR! Text names must be unique.
```
No Subsections in Text-Named Sections: Sections that use text names must not contain subsections. If a subsection is encountered within a text-named section, the parser must raise an error.
```
[text."one"]
name: 123
[.subsection]  # ERROR! No subsections allowed in text-named sections.
[example."text".subsection]  # ERROR! No subsections allowed in text-named sections.
```
No Text Names for Section Lists: Section lists must not use text names. Attempting to use a text name in a section list will result in an error.
```
*[text."one"]  # ERROR! Section lists must not have text names.
*[text."one"]
```
Maximum Length: A text name must not exceed 4000 bytes in length, which corresponds to the maximum line length permitted in the configuration document (without the enclosing double quotes).

Note

Because escape sequences are always fully resolved before a text name is stored, it is not possible for a text name to exceed this limit during parsing. Parser implementors can therefore choose to enforce this limit only at the API level, depending on their specific application needs.

Text Name Normalization

Normalization of text names is performed according to these rules:

Resolve Escape Sequences: All escape sequences in text names must be fully resolved into their corresponding Unicode characters.
```
"\u{25b6}\u{fe0e}"  =>  "▶︎"
```
Preserve Double Quotes: Double quotes surrounding text names are considered an integral part of the name. This distinction ensures that a text name cannot be confused with a regular name, even if they share the same character sequence.
```
"He said \"hello!\""  =>  "he said "hello!""
```
Important

While double quotes are part of the text name for comparison purposes, a parser implementation does not necessarily have to store them. Instead, these quotes establish that a text name is always distinct from a regular name.

For example, the regular name example will never match the text name "example", because the double quotes are considered part of the text name. Parser implementations can choose to store an accompanying type identifier—regular name or text name—alongside the normalized text, ensuring correct comparisons.

Text Name Comparison

Code-Point Comparison for Text Names: Text names are compared by evaluating their Unicode code points directly, after all escape sequences have been resolved. For more details on normalization, refer to Text Name Normalization.
```
"\u{25b6}\u{fe0e}"  ==  "▶︎"
```
Important

Parsers are not required to perform Unicode normalization during text name comparison. Text names can be processed directly as UTF-8 encoded byte sequences. It is the responsibility of the application layer to handle any additional normalization or verification as needed for the specific use case.
Regular Names and Text Names Are Never Equal: Regular names and text names are inherently distinct. Even if their content is identical, they must never be considered equal because the double quotes are part of the text name.
```
"text" != text
```

Features

Feature	Coverage
text-names	Text names and sections with text names are a standard feature.

Errors

Error Code	Causes
Character	Raised if a “null” escape sequence is found in a text name.
Syntax	Raised if text names and regular names are mixed.
NameConflict	Raised if an already used text name is reused.
LimitExceeded	Raised if a text name exceeds the 4000-byte limit.