LingAge Guides

Tutorial #1 — Build a Directed Graph (CGDL)

CGDL (ContextGraph Description Language) is a line-based, plain-text format for describing a compact directed graph. cgdl-lib reads CGDL text and builds an in-memory directed graph.

A first graph: one event, several facts

This example declares a few small “catalog” nodes (person, city, year) and then creates a single event node that connects to them. 

[[ person ]]
## Alice

[[ city ]]
## Paris
## London
## New York

[[ year ]]
## 1989
## 1990

[[ event ]]
## Alice visited Paris in 1989
person: Alice
city: Paris
year: 1989

The file is readable as a small story, but it also forms a graph: the event node links to the person, the city, and the year.

Adding a second event

CGDL is often authored gradually. Adding a new event is just adding a new node and a few lines. 

[[ person ]]
## Alice

[[ city ]]
## Paris
## London

[[ year ]]
## 1989
## 1990

[[ event ]]
## Alice visited Paris in 1989
person: Alice
city: Paris
year: 1989

## Alice visited London in 1990
person: Alice
city: London
year: 1990

Once parsed, this becomes a compact structure that can later answer simple questions like: “Which events are linked to London?” or “Which events are linked to 1989?”.

Properties: small facts that belong on one node

Some facts are best expressed as properties on a specific node. Properties are explicit: they appear only on lines starting with {}. 

[[ city ]]
## Paris
{} country = France
{} note = capital city

[[ event ]]
## Alice visited Paris in 1989
city: Paris
year: 1989
{} source = diary

A property is a key/value pair, and it stays attached to the node where it appears.

Plain lines: keep what you want to remember

Not everything should be structured. A CGDL node can also contain plain lines, which remain readable and are preserved by the parser. 

[[ event ]]
## Alice visited Paris in 1989
person: Alice
city: Paris
year: 1989

Arrived late afternoon.
Walked near the river.
Weather: warm (this is just text here).

Summary