Extension literals

Extension-defined literals

An installed package can add its own literal tag, so a model can write data in that package's format and get structured Grid values back. Import the tag explicitly with USE:

USE "pkg:grid/gedcom@1.0.0" EXPOSING (gedcom)
 
# GEDCOM levels start at the beginning of each line, so the payload is unindented.
family = gedcom"""0 HEAD
1 GEDC
2 VERS 7.0
0 @I1@ INDI
1 NAME Ada /Example/
0 TRLR
"""

Installing a package does not activate its tags; only USE does. Compiling never downloads a missing package, so install it first. The example package lives in examples/extensions/gedcom.

Three spellings

gedcom"...", gedcom"""...""" and <gedcom>...</gedcom> all select the same parser:

Ordinary quotes decode Grid escapes such as \n.
Triple quotes and angle blocks keep the payload exactly as written.
An angle block ends at the first matching closing tag, ignoring case.

Package literals never interpolate on their own. A package that supplies a template compiler adds the template attribute; see Reactive templates.

Naming and conflicts

EXPOSING (gedcom) makes the tag available by its own name. AS qualifies it instead:

USE "pkg:grid/gedcom@1.0.0" AS genealogy
 
family = genealogy.gedcom"""0 HEAD
0 TRLR
"""

Two imports that expose the same tag, or an import that would replace a built-in tag, are refused. Built-in literals keep their meaning.

When the package runs

Formatting and inspecting a model leave the literal's text untouched and do not run the package. Compiling runs the installed, verified parser once per distinct payload and replaces the literal with the constant value it returns. A parser error or a missing package fails the compile with a diagnostic that points inside the payload.

The compiled model then runs without the parser package. Editing the literal and recompiling needs the same package version again. The compiled model also records which package and payload produced each value, for review.

Using the value

The result is an ordinary Grid value: records, arrays and scalars. Read it with the usual accessors, for example family.people[1].name. A record value shaped as nodes and edges can be passed straight to GRAPH:

USE "pkg:grid/gedcom@1.0.0" EXPOSING (gedcom)
 
graph ancestry = GRAPH(gedcom"""0 HEAD
1 GEDC
2 VERS 7.0
0 @I1@ INDI
1 NAME Isolated /Example/
0 TRLR
""")
 
node_count = ancestry.NODE_COUNT()

Pass the literal directly to GRAPH; a named or computed record is not folded into a graph at compile time, because that would lose its live dependency.

Editors

A package can describe how editors should color its payloads. Without that, the payload appears as plain text. Coloring never changes parsing or results.

Package authors: the parser contract, manifest fields, result shape and limits are in the extension authoring guide for literals.