Sections

In ELCL, a section can either define a new map of values or, in the case of a section list, a list of maps. The definition of a section, referred to as section_line in the following EBNF notation, opens the section for value assignments.

section_map_begin   ::= HYPHEN* SQ_BRACKET_OPEN
section_map_end     ::= SQ_BRACKET_CLOSE HYPHEN*
section_map         ::= section_map_begin spacing section_name spacing section_map_end

section_list_begin  ::= HYPHEN* ASTERISK SQ_BRACKET_OPEN
section_list_end    ::= SQ_BRACKET_CLOSE ASTERISK? HYPHEN*
section_list        ::= section_list_begin spacing section_name spacing section_list_end

section             ::= section_list | section_map
section_line        ::= section end_of_line

Rules for Regular Sections

Square Brackets: Section names must be enclosed in square brackets ([ and ]).

[example_section]
[ Example Section 2 ]
[Example Section . Sub. Sub]

Regular Sections: Regular sections create a new map of named values.
```
[section]
value 1: 123
value 2: 456
```
Hyphens as Visual Separator: Zero or more hyphen characters (-) may be placed before or after the square brackets as a visual separator.
```
--------[ section 1 ]--------
[section 2]------------------
------------------[section 3]
```
No Trailing Asterisk: A trailing asterisk (*) must not be present after the closing square bracket (]).
```
[regular section]*   # ERROR! There must be no trailing asterisk.
```
No Leading Spacing: There must be no spacing before the opening square bracket or hyphen character.
```
# Example Configuration
    [section]  # ERROR! There must be no spacing in front of a section.
```
Name Conflicts: Guidelines for handling name conflicts are explained in detail in Name Conflicts.

Rules for Section Lists

Square Brackets with Asterisk: Section names are enclosed in square brackets ([ and ]), with an asterisk (*) preceding the opening bracket.
```
*[section list]
*[ Section List ]
*[main . server . connection]
```

New Value Map: Section lists create a new list of value maps or add a new value map to an existing section list.

*[list]  # Creates a new section list "list" and adds its first entry.
*[list]  # Adds a second entry to the existing section list "list".

Optional Trailing Asterisk: An optional asterisk (*) may be placed after the closing square bracket (]) for visual symmetry.
```
*[section list]*
*[ Section List ]*
*[main . server . connection]*
```
Hyphens as Visual Separator: Zero or more hyphen characters (-) may precede or follow the asterisk or square brackets as a visual separator.
```
-------*[ list ]*-------
-------*[ list ]--------
*[list]-----------------
----------------*[list]*
```
No Leading Spacing: There must be no spacing before the opening square bracket, asterisk, or hyphen character.
```
# Example Configuration
    *[section]  # ERROR! There must be no spacing in front of a section.
```
Name Conflicts: Guidelines for handling name conflicts are explained in detail in Name Conflicts.

Implementation

A regular section defined in a configuration document, even if empty, creates a value of the type SectionWithNames.

[server]
[network]

● (root)                    <== Document ( size=2 ) 
├── [network]               <== SectionWithNames ( size=0 ) 
└── [server]                <== SectionWithNames ( size=0 ) 

A section list creates a value of the type SectionList, where each new entry is a SectionWithNames.

*[server]

● (root)                    <== Document ( size=1 ) 
└── *[server]               <== SectionList ( size=1 ) 
    └── [0]                     <== SectionWithNames ( size=0 ) 

If a section list with the given name already exists, a new SectionWithNames entry is added to that list.

*[server]
*[server]

● (root)                    <== Document ( size=1 ) 
└── *[server]               <== SectionList ( size=2 ) 
    ├── [0]                     <== SectionWithNames ( size=0 ) 
    └── [1]                     <== SectionWithNames ( size=0 ) 

For all missing intermediate elements in the name path, when defining a SectionWithNames or SectionList, a new value of the type IntermediateSection is created.

[one.two.three]

● (root)                    <== Document ( size=1 ) 
└── [one]                   <== IntermediateSection (  ) 
    └── [two]                   <== IntermediateSection (  ) 
        └── [three]                 <== SectionWithNames ( size=0 ) 

If a section is defined, that exists as IntermediateSection, it is converted into a SectionWithNames.

[one.two.three]
[one.two]

Path: one.two

● (root)                    <== Document ( size=1 ) 
┗━━ [one]                   <== IntermediateSection (  ) 
    ┗━━ [two]                   <== SectionWithNames ( size=1 ) 
        └── [three]                 <== SectionWithNames ( size=0 ) 

If a value or section with a text name is added to an empty SectionWithNames, it is converted into a SectionWithTexts.

Initial definition:

[server.text]

● (root)                    <== Document ( size=1 ) 
└── [server]                <== IntermediateSection (  ) 
    └── [text]                  <== SectionWithNames ( size=0 ) 

After adding a value with a text-name:

[server.text]
"text": 1

● (root)                    <== Document ( size=1 ) 
└── [server]                <== IntermediateSection (  ) 
    └── [text]                  <== SectionWithTexts ( size=1 ) 
        └── "text"                  <== Integer ( 1 ) 

If a sub section with a text name is added to an empty IntermediateSection, it is converted into a SectionWithTexts.

Initial definition:

[server.text]

● (root)                    <== Document ( size=1 ) 
└── [server]                <== IntermediateSection (  ) 
    └── [text]                  <== SectionWithNames ( size=0 ) 

After adding a sub section with a text-name:

[server.text]
[server.text."text"]

● (root)                    <== Document ( size=1 ) 
└── [server]                <== IntermediateSection (  ) 
    └── [text]                  <== SectionWithTexts ( size=1 ) 
        └── ["text"]                <== SectionWithNames ( size=0 ) 

Features

Feature	Coverage
core	Regular names, name paths, absolute and relative regular sections are part of the core language.
section-list	Section lists are a standard feature.
text-names	Text names and sections with text names are a standard feature.

Errors

Error Code	Causes
	All errors related to invalid names (see Names). All errors related to invalid text names (see Text Names). All errors related to name conflicts (see Name Conflicts).
Syntax	If a trailing asterisk follows a regular section.