Internals · Tree

Tree

The first thing a program becomes is a Code.Language.Program.Tree — a direct, line-for-line tree. Every source line parses into exactly one node, its payload, and the indentation beneath a line becomes that node's branches. Nothing is tightened or checked here: this is the raw shape, mirroring the keywords one-to-one, ready to lower into the canonical Structure form.

The top level

One type describes the tree at every level. A node carries a single payload which is a description of the one line it came from, and the trees for the lines indented under it.

MODULE Code
  MODULE Language
    MODULE Program
      TYPE Tree
        FIELD Code.Language.Program.Tree.Payload payload  # what this line is
        FIELD Collection.Array(Code.Language.Program.Tree) branches  # the lines indented beneath it

Code.Language.Program.Tree definition

The payload is a union that can represent any kind of line. Each option below has its own definition further down.

TYPE Payload
  OPTION Code.Language.Program.Tree.Module module  # MODULE
  OPTION Code.Language.Program.Tree.Function function  # FUNCTION
  OPTION Code.Language.Program.Tree.Input input  # INPUT
  OPTION Code.Language.Program.Tree.Hole hole  # HOLE
  OPTION Code.Language.Program.Tree.Native native  # NATIVE
  OPTION Code.Language.Program.Tree.Type type  # TYPE
  OPTION Code.Language.Program.Tree.Field field  # FIELD
  OPTION Code.Language.Program.Tree.Option option  # OPTION
  OPTION Code.Language.Program.Tree.Let let  # LET
  OPTION Code.Language.Program.Tree.State state  # STATE
  OPTION Code.Language.Program.Tree.Reverse reverse  # REVERSE
  OPTION Code.Language.Program.Tree.Set set  # SET
  OPTION Code.Language.Program.Tree.With with  # WITH
  OPTION Code.Language.Program.Tree.Call call  # CALL — a line with no keyword
  OPTION Code.Language.Program.Tree.Comment comment  # a comment line

Code.Language.Program.Tree.Payload definition

The nodes

One per keyword, plus Call and Comment, which are lines without a keyword. Each is a type nested in Code.Language.Program.Tree (the pseudo-module shown in full above), given here by its short name. A declared name is held as a shared Code.Language.Program.Identifier — a thin wrapper over the raw text; a type is still held as raw Text exactly as written, and the Structure form is where those become resolved references.

Module

A MODULE line: just its name. Its declarations are branches.

TYPE Module
  FIELD Code.Language.Program.Identifier name  # the module name

Code.Language.Program.Tree.Module definition

Function

A FUNCTION line: an optional return type and a name. Inputs, holes and body are branches.

TYPE Function
  FIELD Collection.Optional(Text) optionalType  # the return type, or none
  FIELD Code.Language.Program.Identifier name  # the function name

Code.Language.Program.Tree.Function definition

Input

An INPUT line: an optional BINDING marker, a type, a name, and an optional default.

TYPE Input
  FIELD Logic.Maybe binding  # true for a BINDING input
  FIELD Text type  # the parameter type
  FIELD Code.Language.Program.Identifier name  # the parameter name
  FIELD Collection.Optional(Code.Language.Program.Tree.ConstantExpression) optionalDefault  # the "= …" default, or none

Code.Language.Program.Tree.Input definition

Hole

A HOLE line: an optional return type and a name. Its inputs are branches.

TYPE Hole
  FIELD Collection.Optional(Text) optionalType  # the block's return type, or none
  FIELD Code.Language.Program.Identifier name  # the hole name

Code.Language.Program.Tree.Hole definition

Native

A NATIVE line: a target and a string of host code.

TYPE Native
  FIELD Text target  # the target name: js, dart, …
  FIELD Text code  # the host source string

Code.Language.Program.Tree.Native definition

Type

A TYPE line: just its name. Whether it is a record or a union is told only by whether its branches are fields or options.

TYPE Type
  FIELD Code.Language.Program.Identifier name  # the type name

Code.Language.Program.Tree.Type definition

Field

A FIELD line: a type, a name, and an optional default.

TYPE Field
  FIELD Text type  # the field type
  FIELD Code.Language.Program.Identifier name  # the field name
  FIELD Collection.Optional(Code.Language.Program.Tree.ConstantExpression) optionalDefault  # the "= …" default, or none

Code.Language.Program.Tree.Field definition

Option

An OPTION line: a type and a name.

TYPE Option
  FIELD Text type  # the option payload type
  FIELD Code.Language.Program.Identifier name  # the option name

Code.Language.Program.Tree.Option definition

Let

A LET line: an optional type, a name, and the value expression.

TYPE Let
  FIELD Collection.Optional(Text) optionalType  # the bound type, or none
  FIELD Code.Language.Program.Identifier name  # the bound name
  FIELD Code.Language.Program.Tree.Expression value  # the "= …" value

Code.Language.Program.Tree.Let definition

State

A STATE line: an optional LOCKED marker, a type, a name, and the initial value expression.

TYPE State
  FIELD Logic.Maybe locked  # true for a LOCKED cell
  FIELD Text type  # the cell type
  FIELD Code.Language.Program.Identifier name  # the cell name
  FIELD Code.Language.Program.Tree.Expression value  # the "= …" initial value

Code.Language.Program.Tree.State definition

Reverse

A REVERSE line: a type and a name. Its body and setters are branches.

TYPE Reverse
  FIELD Text type  # the type being written back
  FIELD Code.Language.Program.Identifier name  # the reverse name

Code.Language.Program.Tree.Reverse definition

Set

A SET line: a name and the value expression written into it.

TYPE Set
  FIELD Text name  # the outer settable written into
  FIELD Code.Language.Program.Tree.Expression value  # the "= …" value written

Code.Language.Program.Tree.Set definition

With

A WITH line: the module swapped and its replacement. The body it applies over is branches.

TYPE With
  FIELD Text module  # the module whose implementation is swapped
  FIELD Text replacement  # the replacement swapped in

Code.Language.Program.Tree.With definition

Call

A CALL line — a bare function call, no keyword: a name and its arguments. A block filling a hole is written as branches.

TYPE Call
  FIELD Text function  # the function name, as written
  FIELD Collection.Array(Code.Language.Program.Tree.Argument) arguments  # its arguments, left to right

Code.Language.Program.Tree.Call definition

Comment

A comment line: its text. Not a keyword, but it is a line, so it is a node.

TYPE Comment
  FIELD Text text  # the comment text

Code.Language.Program.Tree.Comment definition

Common types

The = … on a LET, STATE or SET, and the arguments of a CALL, share a small set of shapes. A value is either a call (a name applied to arguments — a bare reference is a call with none) or a literal. A FIELD or INPUT default is a constant expression: a literal, or a constructor applied to arguments. The tree records its shape but does not check that it is really constant.

TYPE Expression
  OPTION Code.Language.Program.Tree.Call call  # a name applied to zero or more arguments
  OPTION Code.Language.Program.Constant constant  # a bare literal

TYPE Argument
  OPTION Text reference  # a name argument
  OPTION Code.Language.Program.Constant constant  # a literal argument

TYPE ConstantExpression
  OPTION Code.Language.Program.Constant literal  # a bare literal, e.g. 3.14 or "hi"
  OPTION Code.Language.Program.Tree.Call construction  # a constructor applied to arguments, e.g. Colour.RGB 255 0 0

Code.Language.Program.Tree.Expression, Argument and ConstantExpression definitions

Shared types

Two types are not part of the tree at all: they sit directly under Code.Language.Program, above both the Tree and Structure 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.

Identifier

A declared name — the text of a module, function, type, field or binding as written. A thin record wrapping a single name string; every node that declares a name holds one of these.

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

Code.Language.Program.Identifier definition

Constant

A literal value — text, a number, or nothing. There is no CONSTANT keyword: a literal never stands alone, it only appears inside something else — a call argument, a = … value on a LET or STATE, or a FIELD default.

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

Code.Language.Program.Constant definition

From here

This tree is deliberately loose — it can hold clashing names, a type with both fields and options, a default that is not really constant. Those are not fixed here. Parsing builds this tree; the Structure form is what it is lowered into, where such illegal shapes become unrepresentable and references are resolved.