Structure

Conventions

The canonical form is written here as Program types. Its JSON conventions live with the encodings:

The two JSON encodings and how each shape (nodes, unions, optionals, identifiers) maps into them are documented under Object format and Array format.

Each node under The nodes is named for a language keyword — Module for MODULE, Field for FIELD, and so on. Two of them, HOLE and WITH, extend the base Code.Language.Program.Structure types with node types of their own; those are flagged where they appear. The structural glue that ties the keyword nodes together — the calls, arguments, bodies and references they are built from — is defined below under Common types, with the top-level shared types and the foundational library leaves after it.

The top level

A program has one root, the ROOT node, whose type is Code.Language.Program.Structure. It is a type, but it doubles as a pseudo-module: every other node type on this page (Module, Function, Type, …) is namespaced beneath it. As a value it holds the program's top level — one array per kind of declaration allowed there.

TYPE Structure
  FIELD Collection.Array(Code.Language.Program.Structure.Module) modules  # top-level modules (MODULE)
  FIELD Collection.Array(Code.Language.Program.Structure.PlatformImpl) natives  # top-level native setup blocks (NATIVE)
  FIELD Collection.Array(Code.Language.Program.Structure.BodyCommand) run  # the run body — the program's entry point

The three fields match the keywords allowed at the top level: MODULE for nested namespaces, NATIVE for per-target setup that runs as the program starts, and a run body of body commands — the entry point, where a bare CALL or a LET lives.

The nodes

Module

A MODULE is a named namespace. Because a module holds several kinds of declaration, each kind has its own named list: nested modules, types, functions, constants, native functions and native types.

TYPE Module
  FIELD Code.Language.Program.Identifier name  # the module's name
  FIELD Collection.Array(Code.Language.Program.Structure.Module) modules  # nested modules
  FIELD Collection.Array(Code.Language.Program.Structure.Type) types  # the module's types
  FIELD Collection.Array(Code.Language.Program.Structure.Function) functions  # derived functions
  FIELD Collection.Array(Code.Language.Program.Structure.Assignment) constants  # module-level constants (LET)
  FIELD Collection.Array(Code.Language.Program.Structure.Function) natives  # native functions
  FIELD Collection.Array(Code.Language.Program.Structure.NativeType) nativeTypes  # native type declarations

Function

A FUNCTION is a pseudo-module: it declares its inputs and holes, then holds either a derived body of body commands or a set of per-target native implementations — the FunctionBody union.

TYPE Function
  FIELD Code.Language.Program.Identifier name  # the function's name
  FIELD Collection.Array(Code.Language.Program.Structure.Reference) genericTypes  # generic type parameters
  FIELD Collection.Array(Code.Language.Program.Structure.Input) inputs  # the typed parameters
  FIELD Collection.Array(Code.Language.Program.Structure.Hole) holes  # callback parameters
  FIELD Code.Language.Program.Structure.FunctionBody body  # derived body, or native implementations
  FIELD Collection.Optional(Code.Language.Program.Structure.Return) optionalReturn  # the return, or none

Input

An INPUT is a typed parameter of a function or hole. Its direction is forward normally, or binding for a two-way BINDING input that is read and written back. An optional = constantExpression gives it a default: a trailing constant expression shown as a "default" key in object form and a final array element in array form — dropped from both when absent.

TYPE Input
  FIELD Code.Language.Program.Identifier name  # the parameter name
  FIELD Code.Language.Program.Structure.Reference type  # the parameter's type
  FIELD Code.Language.Program.Structure.Direction direction  # forward, binding or reverse
  FIELD Collection.Optional(Code.Language.Program.Structure.ConstantExpression) optionalDefault  # default constant expression, or none

Hole

A HOLE is a callback parameter: a gap the caller fills with a block. A hole has a name, an optional return type, and its own inputs — the values passed into the caller's block. The block that fills it is an inline function passed as a closure argument at the call site.

TYPE Hole
  FIELD Code.Language.Program.Identifier name  # the hole's name
  FIELD Collection.Optional(Code.Language.Program.Structure.Reference) optionalType  # the block's return type, or none
  FIELD Collection.Array(Code.Language.Program.Structure.Input) inputs  # values passed into the block

Native

A NATIVE is a single per-target block of host code: a target name and a string of source in that target. Native blocks fill a function's implementations, or a native type's aliases. Both are lists of the one PlatformImpl node.

TYPE PlatformImpl
  FIELD Text platform  # target: js, dart, swift, go, rust, zig, ts, nodejs, glsl, php
  FIELD Text code  # host source for that target (function body, or type alias)

Type

A TYPE is a named type. Its body is split across three arrays: fields for a record, options for a union, and natives for a type backed by per-target host code. A given type populates whichever array applies and leaves the others empty.

TYPE Type
  FIELD Code.Language.Program.Identifier name  # the type's name
  FIELD Collection.Array(Code.Language.Program.Structure.Reference) genericTypes  # generic type parameters
  FIELD Collection.Array(Code.Language.Program.Structure.Field) fields  # the record's fields
  FIELD Collection.Array(Code.Language.Program.Structure.Field) options  # the union's options
  FIELD Collection.Array(Code.Language.Program.Structure.PlatformImpl) natives  # per-target native implementations

Both fields and options reuse the one Field node (a name and a type); each natives entry is a PlatformImpl, the same per-target block a NATIVE serialises to. Which array is populated is what makes a type a record, a union or a native type.

Field

A FIELD is a named, typed member of a type. Fields make up the fields array of a TYPE. An OPTION reuses this same node. A FIELD may carry a default via a trailing = constantExpression (its optionalDefault); an OPTION never does, and leaves it absent.

TYPE Field
  FIELD Code.Language.Program.Identifier name  # the field or option name
  FIELD Code.Language.Program.Structure.Reference type  # its type
  FIELD Collection.Optional(Code.Language.Program.Structure.ConstantExpression) optionalDefault  # default constant expression, or none

Option

An OPTION is one variant of a union. An option has the same shape as a field — a name and a type — and reuses the Field node (defined above); it is an option rather than a field by virtue of sitting in a type's options array rather than its fields. Unlike a field it never carries a default.

Let

A LET binds a name to a derived value that recomputes reactively. The value is an AssignmentValue union: either a bare reference to another name, a call, or a constant expression when the LET defines a constant.

TYPE Assignment
  FIELD Code.Language.Program.Identifier name  # the bound name
  FIELD Code.Language.Program.Structure.Reference type  # the value's type
  FIELD Code.Language.Program.Structure.AssignmentValue value  # a reference or a call

State

A STATE is a reactive cell — the only place a value really changes. The initial value is an assignment value — a reference, call or constant expression, the same as a LET binds — or null when a LOCKED cell starts empty; lockable marks it as possibly pending or carrying an error. See Internals · State for how these live at runtime.

TYPE State
  FIELD Code.Language.Program.Identifier name  # the cell's name
  FIELD Code.Language.Program.Structure.Reference type  # the cell's type
  FIELD Collection.Optional(Code.Language.Program.Structure.AssignmentValue) optionalInitialValue  # starting value, or none
  FIELD Logic.Maybe lockable  # true for a LOCKED cell

Reverse

A REVERSE is a write-back block: what happens when a value is written. It carries a body of body commands and one or more SET setters that push values into outer state.

TYPE Reverse
  FIELD Code.Language.Program.Identifier name  # the reverse's name
  FIELD Code.Language.Program.Structure.Reference type  # the type being written back
  FIELD Collection.Array(Code.Language.Program.Structure.SetterPair) setters  # write-backs into outer state
  FIELD Collection.Array(Code.Language.Program.Structure.BodyCommand) body  # work done before the write

Set

A SET pushes a value into outer state; a reverse ends in one or more of these. It is a pair: the outer settable to write, and the inner value to write into it.

TYPE SetterPair
  FIELD Text outerSettable  # outer state cell to write into
  FIELD Text innerValue  # name of the inner value to write

With

A WITH temporarily swaps a module's implementation for another over an indented block. It names the module to swap, the replacement to swap in, and the body the swap applies to. WITH is a body command; it appears as the with option of the BodyCommand union.

TYPE With
  FIELD Text module  # module whose implementation is swapped
  FIELD Text replacement  # module swapped in for the block
  FIELD Collection.Array(Code.Language.Program.Structure.BodyCommand) body  # commands the swap applies over

Common types

The structural nodes that hold the keyword nodes together: helper types defined inside the Code.Language.Program.Structure module and reused across many of the nodes above — the references, calls, arguments, bodies and constant expressions they are built from. With these and the shared types below, the schema is closed: every type named anywhere on this page is defined, and an entire program is one value of Code.Language.Program.Structure. In a body, each command appears in object form under its keyword ({ "LET": … }, { "STATE": … }, …); the union option names here are the type-system discriminators.

Reference

A reference to a type: a dotted name, plus the generic arguments applied to it. It is recursive — each generic argument is itself a Reference. A bare type like Text is a name of one identifier and no arguments; Collection.Array(Text) is a two-identifier name with one argument.

TYPE Reference
  FIELD Collection.Array(Code.Language.Program.Identifier) name  # the dotted type name, as identifiers
  FIELD Collection.Array(Code.Language.Program.Structure.Reference) generics  # the generic type arguments

NativeType

A native type: per-platform aliases grouped under a name. Each alias is a PlatformImpl whose code is the target's type alias.

TYPE NativeType
  FIELD Code.Language.Program.Identifier name  # the native type's name
  FIELD Collection.Array(Text) typeParamNames  # generic type parameter names
  FIELD Collection.Array(Code.Language.Program.Structure.PlatformImpl) implementations  # the per-target aliases

FunctionBody

The body of a function: derived, or native.

TYPE FunctionBody
  OPTION Collection.Array(Code.Language.Program.Structure.BodyCommand) body  # a derived body of commands
  OPTION Collection.Array(Code.Language.Program.Structure.PlatformImpl) implementations  # per-target NATIVE blocks

BodyCommand

One statement in a run body, function body or reverse body. The comment on each option names the keyword it appears as in object and array form.

TYPE BodyCommand
  OPTION Text comment  # COMMENT — a comment line
  OPTION Code.Language.Program.Structure.State state  # STATE — a reactive cell
  OPTION Code.Language.Program.Structure.Assignment assignment  # LET — a binding (reactive or constant)
  OPTION Code.Language.Program.Structure.FunctionCall call  # CALL — an effect call statement
  OPTION Code.Language.Program.Structure.Reverse reverse  # REVERSE — a write-back block
  OPTION Code.Language.Program.Structure.With with  # WITH — a swap

FunctionCall · a call / effect

A call to a function, whether a derived value or an effect statement. In object and array form its node tag is CALL — object { "CALL": { … } }, array ["CALL", "Ui.Content.Text", [], [ …args ]].

TYPE FunctionCall
  FIELD Code.Language.Program.Structure.Reference functionName  # dotted name of the function called
  FIELD Collection.Array(Code.Language.Program.Structure.Reference) typeArguments  # generic type arguments, if any
  FIELD Collection.Array(Code.Language.Program.Structure.Argument) arguments  # the call's arguments

AssignmentValue

The value bound by a LET: a bare reference, a call, or a constant expression — the last being a LET that defines a constant rather than a reactive value.

TYPE AssignmentValue
  OPTION Text reference  # a reference to a name in scope
  OPTION Code.Language.Program.Structure.FunctionCall call  # a call whose result is bound
  OPTION Code.Language.Program.Structure.ConstantExpression constant  # a constant expression the LET defines

Argument

One argument to a call: a reference, an inline closure (the block that fills a HOLE), or an inline constant.

TYPE Argument
  OPTION Text reference  # a reference to a name in scope
  OPTION Code.Language.Program.Structure.Function closure  # an inline function — the block filling a hole
  OPTION Code.Language.Program.Constant inlineConstant  # a literal written inline at the call

ConstantExpression

What may sit after = in a position that must be constant — an INPUT or FIELD default, or a LET that defines a constant rather than a reactive value. It mirrors the grammar's constantExpression: either a bare literal, or a constructor applied to constant arguments (e.g. Colour.RGB 255 0 0).

TYPE ConstantExpression
  OPTION Code.Language.Program.Constant literal  # a bare literal — 3.14, "hi", 42
  OPTION Code.Language.Program.Structure.ConstantConstruction construction  # a constructor applied to constants

TYPE ConstantConstruction
  FIELD Code.Language.Program.Structure.Reference constructor  # the constructor / function name, e.g. Colour.RGB
  FIELD Collection.Array(Code.Language.Program.Constant) arguments  # its constant arguments

Return

A function's return: a name, a type, and an optional direction for a reverse or binding return.

TYPE Return
  FIELD Code.Language.Program.Identifier name  # the return value's name
  FIELD Code.Language.Program.Structure.Reference type  # the return type
  FIELD Collection.Optional(Code.Language.Program.Structure.Direction) optionalDirection  # direction for reverse/binding returns, or none

Direction

The direction of an input or return. Each option carries no data, so it serialises as a bare string.

TYPE Direction
  OPTION Collection.Void forward  # a plain, read-only input
  OPTION Collection.Void reverse  # a reverse-flowing value
  OPTION Collection.Void binding  # a two-way BINDING input

Shared types

Two types are not part of the Structure module at all: they sit directly under Code.Language.Program, above both the Structure and Tree pseudo-modules, and are named unchanged at both stages — a declared name and a raw literal are each already in their final form, so neither is lowered. Their definitions are shown identically on both pages. After them are the foundational library leaves the whole schema bottoms out in.

Identifier

A declared name — a record wrapping a single name string; in the examples above it is written in the shorthand form of that bare string (see Conventions). Like Constant, this is a shared type sitting directly under Code.Language.Program rather than under the Structure or Tree pseudo-modules: a declared name is already in its final form, so both stages name the same type, and its definition is shown identically on both pages.

TYPE Identifier
  FIELD Text name  # the identifier text, as written

Constant

A single literal value — text, a number, or nothing. This is the shared type Code.Language.Program.Constant, sitting directly under Code.Language.Program rather than under the Structure or Tree pseudo-modules: a raw literal is already in its final form, so both stages name the same type, and its definition is shown identically on both pages. There is no CONSTANT keyword: a literal never stands alone, it only appears inside something else — an inline call argument, a STATE's initial value, or a constant expression.

TYPE Constant
  OPTION Text text  # a text literal, e.g. "hello"
  OPTION Maths.Integer integer  # an integer literal, e.g. 42
  OPTION Maths.Real real  # a real literal, e.g. 3.14
  OPTION Collection.Void none  # the empty value, carrying no data

Foundational types

The leaves of the schema: native library types on which everything above is built. They have no fields or options of their own — each is backed by host types in its own module — and are listed here so the schema references nothing undefined.

# native, provided by the standard library — no fields, no options
Text              # a string of text
Logic.Maybe              # a boolean (true / false)
Maths.Integer            # a whole number
Maths.Real            # a real number
Collection.Void          # the empty value, carrying no data
Collection.Optional(ValueType)   # a ValueType that may be absent
Collection.Array(ElementType)      # an ordered list of ElementType
Collection.Lookup(KeyType ValueType)   # a map from KeyType to ValueType
Collection.Dictionary(ValueType)       # a Lookup specialised to a Text key

See also

The compact array form is what the targets render from; the Targets · JSON pages show it in day-to-day use, and a full program in the canonical form. Internals · State follows a STATE cell from this form into a running program.