Name and Name-Path

Naming the individual elements in a configuration is done using name-paths. The API provides the classes NamePath and Name for this purpose.

The NamePath has a built-in mini-parser, that parsers a string in the name-path format defined by the Erbsland Configuration Language into a NamePath object. This parser also generates sytnax errors, like the configuraton parser does. It is a safe way to use name-paths in string format in your code.

Usage

import erbsland.conf as elcl

doc = elcl.load("configuration.elcl")

# Implicit parsed name-path
port = doc.get_int("main.server.port")

# Pre-parsed name-path
NP_PORT = elcl.NamePath.from_text("main.server.port")
for server in doc["main.server"]:
    port = server.get_int(NP_PORT)

path1 = elcl.NamePath.from_text("main.server")
path2 = elcl.NamePath.from_text("filter.keywords")

# Path operations
path3 = path1 / path2
path1.append(path2)

# Assemble a path from Name instances.
assembled_path = elcl.NamePath([
    elcl.Name.create_regular("translations"),
    elcl.Name.create_text("Welcome!"),
])

Interface

class Name(_type: NameType, _value: str | int)

Represent a single name.

A regular name is always converted into its normalized lower-case form.
A text name is kept as is.
An index name is neither normalized nor range checked.

classmethod create_regular(name: str) → Name

Create a regular name from name.

Parameters:: name – The raw name text.
Returns:: A Name instance of type REGULAR.
Raises:: ConfSyntaxError – If name violates the regular name rules.

classmethod create_text(text: str) → Name

Create a text name from text.

Parameters:: text – The text of the name.
Returns:: A Name instance of type TEXT.

classmethod create_index(index: int) → Name: Create an index name from index.

classmethod create_text_index(index: int) → Name: Create a text index name from index.

property type: NameType: Return the NameType of this name.

is_regular() → bool: Return True if this name is a regular name.

is_text() → bool: Return True if this name is a text name.

is_index() → bool: Return True if this name is an index name.

is_text_index() → bool: Return True if this name is a text index.

is_meta() → bool: Return True if this regular name starts with @.

as_text() → str

Return the underlying string value.

Returns:: The name text.
Raises:: TypeError – If the name does not store text.

as_index() → int

Return the underlying integer value.

Returns:: The index value.
Raises:: TypeError – If the name does not store an index.

to_path_text() → str: Return the name formatted for use in a name path.

classmethod normalize(text: str) → str: Normalize text for use as a regular name.

classmethod validate_text(text: str) → None: Validate the syntax of a text name.

classmethod validate_regular_name(name: str): Validate the syntax of a regular name.

classmethod from_document(raw_text: str) → Name

Parse a name captured from a document.

Parameters:: raw_text – The raw text captured from the document.
Returns:: The parsed name.
Raises:: ConfSyntaxError – If raw_text contains invalid syntax.

class NamePath(path: Name | list[Name] | None = None)

Represent a name path pointing to a value.

copy() → NamePath: Return a shallow copy of this path.

append(other: Name | NamePath | str) → None

Append other to this path.

Parameters:: other – A Name, another NamePath or a string to append.
Raises:: TypeError – If other has an unsupported type.

to_text() → str: Return the path formatted as text.

classmethod from_text(text: str) → NamePath

Parse a name path from text.

A path is a sequence of segments separated by dots. Segments may be regular names (foo), numeric indices ([0]), quoted text names ("foo") or text indices (""[0]). Spacing around segments is ignored. Quoted names use standard backslash escapes such as ", \n or \u.

Parameters:: text – The text to parse.
Returns:: The parsed path.
Raises:: ConfSyntaxError – If text contains invalid syntax.