LingAge Guides

Tutorial #2 — Building Incrementally, Context Switching, and Partial Graphs

Tutorial 1 focused on what CGDL looks like as a finished text. This page focuses on how CGDL is often authored in practice: line by line, while a graph grows in memory.

Install (npm)

cgdl-lib is published as an npm package. For a client-side app, installation is a normal npm dependency: 

npm install cgdl-lib

Source and documentation live in the GitHub repository: https://github.com/DirectedAttention/cgdl-lib

Line-by-line: the graph is built as lines arrive

Many applications build a graph while text is still being authored. CGDL is designed for line-by-line input: each new line can update the in-memory Directed Graph object immediately, without requiring a “final document.” The same text may later be serialized for storage or sharing, but the primary mode is incremental construction.

<`p> In practice, the same CGDL lines can travel through many channels: a UI, a chat, an API call, an email, a log stream, or a ViewModel passed into a Razor view. Saving to a file is just one possible serialization, not the defining feature. 

[[ event ]]
## Conference in Vienna
city: Vienna
country: Austria

[[ city ]]
## Vienna

Even before the country class is declared, the text already communicates meaning. A reader can understand “Vienna is a city” and “Austria is a country-like thing” from usage alone. A later version of the file may add the missing nodes as the author continues.

Context switching: [[ ... ]] changes the current class

CGDL is organized around a current class (context). A line [[ city ]] switches the current context to the class named city. After that, node headers (## ...) open nodes in that class until the class changes again. 

[[ city ]]
## Vienna
{} country = Austria

[[ country ]]
## Austria

[[ event ]]
## Conference in Vienna
city: Vienna
country: Austria

This “switch context, add nodes” style keeps the file readable and makes it easy to extend.

Partial graphs: readable early, refined later

CGDL is often written in stages. The early stage may contain only the event node and references to other entities. Later, those entities may gain properties and additional connections. 

[[ event ]]
## Alice visited Vienna
person: Alice
city: Vienna

[[ person ]]
## Alice

[[ city ]]
## Vienna
{} note = capital

This is a practical authoring pattern: the file stays understandable at every step, but the structure becomes richer as nodes are filled in.

Another small pattern: reuse the same catalog nodes across many events

One benefit of a graph is reuse. The same city node can be referenced by many different events, instead of repeating “Vienna” as unstructured text everywhere. 

[[ city ]]
## Vienna
## Paris

[[ person ]]
## Alice
## Bob

[[ event ]]
## Alice visited Vienna
person: Alice
city: Vienna

## Bob visited Paris
person: Bob
city: Paris

Summary