architecture(3)

architecture(3) — the libecoli ✨architecture✨ page, bestie edition 💅

Okay so real talk, this is architecture out of the Libecoli manual, section 3, and it's genuinely one of my faves. Libecoli is written in C and gives you an API for building interactive command line interfaces. Like, it's the whole personality of your CLI. 🎀

🌸 NAME 🌸

architecture — the architecture of Libecoli. It's written in C, and it provides an API for building interactive command line interfaces. The library is made up of several components:

• Core — the main API for parsing and completing input strings.
• Nodes — the modular component of libecoli. Each node type implements its own specific parsing behavior (integers, strings, regular expressions, sequences, etc.).
• YAML parser — loads grammar trees from YAML configuration files.
• Editline — integration helpers for the editline library.
• Utilities — logging, string manipulation, string vectors, hash tables, and other support functions.

---

🦋 The Grammar Graph 🦋

Nodes are organized into a directed graph that defines the grammar. It's typically a tree, but lowkey loops are permitted in certain cases. The grammar graph describes how input is parsed and completed. Periodt.

There's a figure here in the original, labeled Simple grammar tree — yes, bestie, it's a whole diagram. 🙈

The same structure can be represented textually as:

sh_lex(
  seq(
    str(foo),
    option(
      str(bar)
    )
  )
)

This grammar matches:

• 'foo'
• 'foo bar'

It does not match:

• 'bar'
• 'foobar'
• '' (empty input)

---

🔥 Parsing 🔥

When libecoli parses input, it traverses the grammar graph using depth-first search and constructs a parse tree. The following example illustrates the process when ec_parse_strvec() is called:

1. The input is a string vector containing ['foo bar'].
2. The sh_lex node tokenizes the input using shell lexing rules, producing ['foo', 'bar'], and passes this to its child.
3. The seq node forwards the input to its first child.
4. The str node checks whether the first token equals foo. Since it does, the node returns 1 (the number of consumed tokens) to its parent.
5. The seq node passes the remaining tokens ['bar'] to its next child.
6. The option node forwards the input to its child, which matches and returns 1.
7. The seq node has processed all children and returns 2 (total consumed tokens).
8. The sh_lex node compares the return value against its token count and returns 1 (success) to the caller.

When a node fails to match, it returns EC_PARSE_NOMATCH to its parent. That value propagates up the tree until some node handles the failure — for example, the or node tries each child in sequence until one of them matches. No cap, that's the whole strategy. 💀

---

⭐ The Parse Tree ⭐

Consider another example grammar — the original has a figure here labeled Grammar with or node, and yep, it's a whole vibe. 🌈

Without a lexer node, the input must already be tokenized. This grammar matches:

• ['foo']
• ['bar', '1']
• ['bar', '100']

It does not match:

• ['bar 1'] (not tokenized)
• ['bar'] (missing required argument)
• [] (empty input)

During parsing, a parse tree is constructed. When parsing succeeds, the tree describes which grammar nodes matched and what input each node consumed.

Parsing ['bar', '1'] produces the following parse tree — yep, another figure in the original, this one labeled Parse tree structure. 🫶

Each parse tree node references the grammar node that matched and stores the corresponding input tokens. (Original figure: Parse tree with token references — iconic.)

Not all grammar nodes appear in the parse tree. In this example, str('foo') was not matched and therefore does not appear. Conversely, a single grammar node may appear multiple times in the parse tree. Consider this grammar that matches zero or more occurrences of foo (original figure: Grammar with many node):

Parsing [foo, foo, foo] produces — you guessed it, a figure, labeled Parse tree with repeated matches. Obsessed with the consistency tbh. 💖

---

💜 Node Identifiers 💜

Each grammar node may have an optional string identifier. This identifier enables locating specific nodes in the parse tree after parsing completes. For example, a node created with ec_node_int('COUNT', 0, 100, 10) can be found using ec_pnode_find(parse_tree, 'COUNT').

Identifiers do not need to be unique within the grammar graph. When multiple nodes share the same identifier, ec_pnode_find() returns the first match. Use ec_pnode_find_next() to iterate through additional matches. iykyk. 💅

---

🧚 Completion 🧚

The completion mechanism operates similarly to parsing, but it collects possible continuations instead of validating input. When the user requests completion, libecoli traverses the grammar graph and queries each node for tokens that could follow the current partial input.

Completions are grouped by the grammar node that produced them. Each completion item has one of three types:

• EC_COMP_FULL — a complete token (e.g., a command keyword).
• EC_COMP_PARTIAL — a partial token requiring further input (e.g., a directory path).
• EC_COMP_UNKNOWN — valid input that cannot be completed (e.g., an arbitrary string matching a regular expression).

---

🍓 Node Attributes 🍓

Grammar nodes support arbitrary key-value attributes. The interactive layer uses these attributes to store:

• Help text displayed during completion or on errors
• Callbacks invoked when parsing succeeds
• Short descriptions for contextual help

Use ec_node_attrs() to access the attribute dictionary and manipulate it with ec_dict_set() and ec_dict_get(). The Interactive command line API provides convenience functions such as ec_interact_set_help() and ec_interact_set_callback(). Slay.

---

👑 Node Configuration 👑

Nodes support a generic configuration system for setting parameters after creation. Each node type defines a schema describing its configuration options. The YAML parser uses this system to instantiate nodes from configuration files.

See Node configuration for details.

---

Fr fr, that's the whole page — every component, every node type, every match and non-match, all the EC_PARSE_NOMATCH and EC_COMP_* constants, and every figure, untouched. 💖

Okay and this page is literally brought to you by Version 0.11.3, dated Thu Apr 9 2026, and it's the architecture(3) page, so like — cite it correctly bestie, or don't cite it at all. 🎀✨🦋