Addressing a Section List

When a name path points to a section list, it refers to the list as a whole — not to a specific entry within the list.

This is an important distinction between how name paths behave in a configuration document versus how they are used within the parser API.

Consider the following example configuration:

[main]
user: "example"

[server]
threads: 4
startup delay: 20 s

*[server.connection]
port: 8080
interface: "web"

*[server.connection]
port: 9000
interface: "api"

[server.backend.filter]
reject: "bad"
accept: "good"

This results in the following value tree:

Path: server.connection

● (root)                    <== Document ( size=2 ) 
┠── [main]                  <== SectionWithNames ( size=1 ) 
┃   └── user                    <== Text ( "example" ) 
┗━━ [server]                <== SectionWithNames ( size=4 ) 
    ┠── [backend]               <== IntermediateSection (  ) 
    ┃   └── [filter]                <== SectionWithNames ( size=2 ) 
    ┃       ├── accept                  <== Text ( "good" ) 
    ┃       └── reject                  <== Text ( "bad" ) 
    ┡━━ *[connection]           <== SectionList ( size=2 ) 
    │   ├── [0]                     <== SectionWithNames ( size=2 ) 
    │   │   ├── interface               <== Text ( "web" ) 
    │   │   └── port                    <== Integer ( 8080 ) 
    │   └── [1]                     <== SectionWithNames ( size=2 ) 
    │       ├── interface               <== Text ( "api" ) 
    │       └── port                    <== Integer ( 9000 ) 
    ├── startup_delay           <== TimeDelta ( Not supported ) 
    └── threads                 <== Integer ( 4 ) 

As shown in the tree:

The name path server.connection refers to a section list under the server section.
The section list contains two entries: each with its own port and interface values.

Usage in Configuration Files

In the configuration file, you can repeat a section list declaration by using the same name path, prefixed with an asterisk (*). Each repeated section adds a new entry to the list.

*[server.connection]
port: 8080
interface: "web"

*[server.connection]
port: 9000
interface: "api"

This pattern appends to the list each time the same name path is used with the section list syntax.

Usage in Parser APIs

When interacting with a parsed configuration programmatically, the same name path — server.connection — will return the entire section list. You can then iterate over its entries as individual maps of values.

for conn in config["server.connection"]:
    print(conn["port"], conn["interface"])

This behavior allows you to treat the section list as a collection object, where each item corresponds to one declaration block from the configuration file.

Important

Even though the name path is the same in both cases, the semantics differ:

In the configuration language, repeating the path creates new list entries.
In the API, it addresses the whole list, enabling you to query, iterate, or inspect its entries programmatically.