External values
Internal references (@) connect information declared in the model. External
references ($) request information supplied by the application using the model.
This lets one document describe relationships without embedding a machine's
paths or other changing application state.
Read an application-provided value
Catalog Shop {
Title: "Corner Stationery";
Heading: $Brand.Prefix + " " + @Title;
}
If the consuming application supplies Brand.Prefix = Welcome to, Heading is
Welcome to Corner Stationery. The language preserves the expression and its
internal references. In a Live model it requests the external value when
Heading is read.
The name Brand.Prefix identifies one external value, not a file, OS environment variable, or automatically discovered service. The application must provide a handler for it. Missing handling is an error; a handled empty string is a valid value. See the complete handler in Embedding.
Do not run this document through a materialized-only CLI emitter expecting it to invent a value. Ordinary JSON/SQLite emission of an unresolved compiled expression fails. A consumer using Live can supply the value before rendering.
Selected targets are already available
Every selected target value is also an external value. With Region selected as
US, $Region reads US without an application read handler. This applies to
custom names as well as build-tool names such as $TargetOS.
Selected targets take precedence over application handlers and are read-only.
An unselected name goes to the application's handler; merely spelling $Region
does not select a Region or filter definitions.
External identities are case-sensitive qualified paths. $Brand.Prefix and
$brand.prefix are distinct. Quoted "$Brand.Prefix" is literal text.
Current state and desired state
A consumer can also support external assignments:
Settings Distribution {
ToolDirectory: "/opt/nexus/bin";
$SearchPath: $SearchPath + ":" + @ToolDirectory;
}
The right side reads the consumer's current SearchPath and constructs a desired value. The left side identifies the external value to which that result pertains. It does not write a process environment variable or modify a file by itself.
Reading or evaluating the desired value does not feed it back into the current SearchPath. The consumer explicitly chooses whether to inspect the result or publish it to a result handler, and that handler decides what action to take. The separator here is chosen for the example's application; the language does not infer a host platform or path-list syntax.
Composition can override an inherited external assignment. Multiple surviving public assignments to the same external identity are rejected when Live is constructed. Assignments to selected target identities are rejected as well.
Evaluation and validation
A Live document retains a snapshot of the compiled structure and target selection. External reads are evaluated on access and can observe changed application values. They do not reload the source or rerun target selection.
Dialect checks that depend on external text are enforced when that text is read. For example, an external value required to be an integer cannot become valid merely because its text was unavailable during initial compilation.
This chapter describes the language capability. A specific consumer must actually provide the relevant external handlers and result policy. Check its documentation before using an application-specific external name.
Continue with Dialects.