Addressing Values with an Index

While indexes are not part of the ELCL syntax, they play an essential role in parser APIs, error messages, diagnostics, and tooling. Indexes allow you to unambiguously reference individual elements in a list — whether it’s a section list or a value list.

This chapter describes the syntax and meaning of indexes in name paths as part of the parser specification. Although these paths cannot be written in configuration files, understanding them is crucial for working with value trees and building parser implementations.

Important

Indexes are not part of the ELCL document syntax. You cannot manually specify an index in a configuration file. Indexes only exist within the parser environment.

Adding an Index to a Section or Value List

An index is added using the syntax [<number>] — a decimal integer enclosed in square brackets ([ and ]). The index must appear immediately after the list name, with no name separator (.) in between.

This allows a name path to refer to a specific item in a section list or value list.

Example

In the following configuration, each place defines its own list of tree sections:

---*[place]*---
name: "example01"

---*[place]*---
name: "example02"

*[place.tree]
fruit: "apple"

*[place.tree]
fruit: "pear"

---*[place]*---
name: "example03"

*[place.tree]
fruit: "cherry"

*[place.tree]
fruit: "apricot"

Here is the corresponding value tree with the path place[1].tree[0].fruit highlighted:

Path: place[1].tree[0].fruit

● (root)                    <== Document ( size=1 ) 
┗━━ *[place]                <== SectionList ( size=3 ) 
    ┠── [0]                     <== SectionWithNames ( size=1 ) 
    ┃   └── name                    <== Text ( "example01" ) 
    ┡━━ [1]                     <== SectionWithNames ( size=2 ) 
    │   ┡━━ *[tree]                 <== SectionList ( size=2 ) 
    │   │   ┡━━ [0]                     <== SectionWithNames ( size=1 ) 
    │   │   │   ┗━━ fruit                   <== Text ( "apple" ) 
    │   │   └── [1]                     <== SectionWithNames ( size=1 ) 
    │   │       └── fruit                   <== Text ( "pear" ) 
    │   └── name                    <== Text ( "example02" ) 
    └── [2]                     <== SectionWithNames ( size=2 ) 
        ├── *[tree]                 <== SectionList ( size=2 ) 
        │   ├── [0]                     <== SectionWithNames ( size=1 ) 
        │   │   └── fruit                   <== Text ( "cherry" ) 
        │   └── [1]                     <== SectionWithNames ( size=1 ) 
        │       └── fruit                   <== Text ( "apricot" ) 
        └── name                    <== Text ( "example03" ) 

This path refers to:

The second element in the place section list (place[1], zero-based index).
The first tree section within that place (tree[0]).
The value of fruit inside that section.

This points to the string "apple" in the value tree.

Tip

Indexes always start at zero.
Indexes are not separated from the list name — write place[1], not place.[1].

Parser-Specific Behavior

The index syntax described in this documentation is a recommended convention. Parser authors are encouraged to:

Use this format when generating name paths for error reporting or diagnostics.
Accept this format in API methods that resolve paths into specific values.

Note

Always refer to the documentation of the specific parser you are using. Not all implementations may support indexed name paths, or they may use alternative formats or APIs to address list elements.