There are two types of numbers: integers and real-valued numbers, referred to as reals, which are represented as floating-point numbers.

Integers consist of a sequence of digits in the range 0—9, optionally preceded by the integer’s sign. A preceding - indicates a negative number. A preceding + indicates a positive integer, which is the default if the sign is omitted.

Integer Syntax. 

<integer> = ['+'|'-']('0'..'9')+

There are numerous syntaxes for real-valued numbers. The most basic is the decimal syntax which comprises an integer followed by the decimal dot . character and a sequence of digits in the range 0—9.

Decimal Real Syntax. 

<real> = <decimal> | <magnitude-exponent>

<decimal> = <integer>'.'('0'..'9')+

	The decimal . must be preceded and followed by at-least one digit character. Thus .5 and 1. are not valid real literals, 0.5 and 1.0 have to be written instead.

The exponent syntax allows a real-number to be specified in scientific notation as a magnitude and exponent pair . The exponent syntax comprises a real in decimal syntax or an integer, followed by the character e, f, d, or l which indicates the precision of the real-number, followed by the exponent as an integer.

Exponent Syntax. 

<magnitude-exponent> = (<decimal>|<integer>)['e'|'f'|'d'|'l']<integer>

e and f indicate a single precision floating point number, d indicates double precision and l indicates long precision.

Literal strings consist of a sequence of characters enclosed in double quotes "...".

String Syntax. 

<string> = '"'<unicode char>*'"'

where <unicode char> can be any Unicode character.

A literal " character can appear inside a string if it is preceded by the backslash escape character \.

Example. 

"John said \"Hello\""

Certain escape sequence, consisting of a \ followed by a character, are shorthands for special characters, allowing the character to appear in the parsed string without having to write the actual character in the string literal.

The \u{<code>} escape sequence is replaced with the Unicode character with code (in hexadecimal) <code>. There must be an opening brace { following \u otherwise the escape sequence is treated as an ordinary literal character escape, in which \u is replaced with u. Currently the closing brace is optional }, as only the characters up to the first character that is not a hexadecimal digit are considered part of the character code. However, it is good practice to insert the closing brace as it clearly delimits which characters are to be interpreted as the character code and which characters are literal characters.

	The \n, \r and \t escape sequences can alternatively be written as \u{A}, \u{D} and \u{9} respectively.

	In a future release, omitting either the opening or closing brace, in a Unicode escape sequence, may result in a parse error.

A dependency of a node may also be an observer of the same node. This allows for a two-way binding in which data may flow from either direction. In this case only the observer nodes which are not also operands of the node’s current context are notified of a change in the node’s value.

Example. 

# A two-way binding is established between `a` and `b`
a -> b
b -> a

a -> c

d -> a

In the above example, both b and c, which are observers of a, will be notified of a change in the value of a triggered by a change in the value of d. This will trigger a change in the value of b however a will not be notified of this change as the change was triggered by a, itself.

In the case of a change in the value of a triggered by a change in the value of b, only the observer c of a will be notified of the change.

Cyclic bindings are bindings between a set of nodes, such that there is a path, via bindings, from a node to itself, consisting of at least three nodes. The resulting value of the node contains a cyclic reference to itself.

	A cycle comprising just a pair of nodes is interpreted as a two-way binding rather than a cyclic binding.

Example. 

cons(a, y) -> x
cons(b, x) -> y

The cycle in this example involves the nodes:

In this example the value function of x is effectively:

cons(a, cons(b, x))

where x, is substituted with a reference to the result of the evaluation of the expression, itself. This is well-formed since the arguments to the cons meta-node are evaluated lazily.

	In order for a cyclic binding to have a meaningful result, the cyclic reference must be evaluated lazily. The following will result in an infinite loop, as the cyclic reference to i, in i + 1, is strictly evaluated. Currently there is no compiler warning or error. i + 1 -> i

A binding in which the dependency is a literal value, is interpreted as setting the initial value of a node. A special init context is created, which has no operands and has the literal value as its function.

Initial values are set on the launch of the application, and are treated as an ordinary value change to the initial value. The initial active context of the node is the init context. If a node is not given an initial value, its initial value is a failure value of type No-Value, see Section 2.6, “Failures”.

Examples. 

0 -> counter
"hello" -> message
10.5 -> threshold

	The setting of the initial values of each node, is treated as having been triggered by a single common ancestor node. See Section 2.3, “Propagation of Changes” for the implications of this.

The context to which a binding is established can be set explicitly with the special /context operator.

Syntax. 

/context(node, context-id)

The effect of this expression, when it appears as the target of a binding, is that the binding to node will be established in the context with identifier context-id. The identifier can be a symbol or a functor.

Example. 

# Context `my-context` of b has a passthrough value function to the
# value of the dependency `a`.

a -> /context(b, my-context)

When a /context declaration appears in source position it is equivalent to an ordinary reference to the node.

Multiple bindings to the same explicit context can be established. The function of the context then selects the value of the first dependency, ordered by the declaration order in the source file, which does not fail to evaluate to a value, see Section 2.6, “Failures”.

Example. 

a -> /context(node, ctx)
b -> /context(node, ctx)
c -> /context(node, ctx)

node evaluates to:

If a, b and c all fail to evaluate to a value, node evaluates to the failure value of c.

	The @ macro from the core module, which is a shorthand for the /context operator, is the preferred way of establishing bindings to explicit contexts in source code.

A binding declaration a -> b can, itself, be treated as a node, to which an explicit binding can be established with the binding node as the target.

c -> (a -> b)

The result of this declaration is that the binding a -> b is only active if the condition node c evaluates to true, the value of the builtin True node,. If c evaluates to false, the value of the builtin False node, b is not set to the value of a but is set to a failure value of type No-Value.

A binding declaration, with a binding node as the target, changes the function of the context of the binding to return a failure value if the value of the condition node is false. The binding node a -> b (->(a, b) in prefix notation), is added as a dependency of b and as an operand of the context corresponding to the binding a -> b. The binding node is itself an observer of c with a simple passthrough function. This allows you to reference the status of the binding by referencing the binding node, a -> b.

Example: Simple Validation. 

# Validate that `i` has a value > 0
# Propagate value of `i` to `j`

i > 0 -> (i -> j)

# Perform some computation with `j` which is guaranteed to either be a
# numeric value greater than zero or a failure.
...

	The bind -> operator has right associativity, thus the parenthesis in c -> (a -> b) can be omitted: c -> a -> b.

Conditional bindings to an explicit context can also be established, see Explicit Contexts. If a condition node evaluates to false, it is treated as though the corresponding dependency node has failed to evaluate to a value. The context’s function then evaluates to the next dependency which does not fail to evaluate to a value. If all condition nodes evaluate to false, the node fails to evaluate to a value.

Example: Conditional Bindings and Explicit Contexts. 

cond1 -> (a -> /context(node, ctx))
cond2 -> (b -> /context(node, ctx))
c -> /context(node, ctx)

The net result is that node evaluates to:

Failure values can also be created explicitly with the fail meta-node, from the core module. This meta-node takes one optional argument: a value indicating the failure type. If the failure type is not provided, the failure returned does not have a type.

Example: Explicit Failure with Type. 

# Bind `b` to `a` if `c` is true
c -> (a -> /context(b, ctx))

# If `c` is false set `b` to an explicit failure
fail("my-type") -> /context(b, ctx)

The failure type of a failure value can be retrieved with the fail-type meta-node. This meta-node takes a single argument, which if it evaluates to a failure, returns the failure type associated with the failure. If the argument does not fail to evaluate to a value, or the failure has no type associated with it, fail-type returns a failure.

Example: Querying Failure Type. 

# Compare failure type of `b`, to "my-type" from example above

fail-type(c) = "my-type" -> c-fails?

The failure type is useful to identify the cause of a failure, since failures are used to represent many classes of errors, such as type errors, out of range errors, no value errors, as well as representing special classes of values.

The special /context operator takes an optional third argument which is a test function that is evaluated prior to activating the binding after the previous binding fails. The test function is applied on a single argument, the failure type of the previous binding. If the function returns true the binding is activated otherwise this binding fails with the same failure type as the preceding binding.

	The @ macro, from the core module, contains a shorthand syntax for establishing a binding to an explicit context with a test function that compares the failure type to a given value.

A node in the argument list, of a meta-node definition, may also be of the form name : value. This designates that the argument, which is bound to local node name, is optional. If it is omitted, in an instance of the meta-node, the local argument node is set to value instead.

	value is processed in the global scope as the meta-node definition is processed. Thus value cannot (as of yet), refer to the preceding argument nodes of the meta-node.

The value may be omitted, written in prefix form :(name), in which case if the argument is omitted, the local argument node is set to a failure, see Section 2.6, “Failures”, of type No-Value.

Example. 

# Increment `x` by 1 or given delta

inc(x, d : 1) : x + d

# Increment `a` by default delta 1
inc(a)

# Increment `b` by explicit delta 2
inc(b, 2)

	Optional arguments may only be followed by optional arguments or a rest argument. An optional argument may not be followed by a required argument.

The last node in the argument list, of a meta-node definition, may also be of the form ..(name). This designates that the local node name is bound to the list containing the remaining arguments, on which the meta-node is applied, after the last optional or required argument. This allows for a variable number of arguments.

Example. 

# Add `n` to each remaining argument

add-n(n, ..(xs)) : {
    inc(x) : x + n
    map(inc, xs)
}

See Section 5.11, “Lists” for the documentation of lists and the list processing functions.

Nodes local to the meta-node’s definition may only be referenced from within the definition itself even if they have the same identifiers as global nodes. Local nodes are created for each of the argument nodes.

A node reference, within the definition of a meta-node, primarily refers to the local node. If there is no local node with that identifier, it refers to the node in the enclosing scope. If the enclosing scope does not contain a node with that identifier, the scope’s enclosing scope is searched until the global scope is reached. If the node is not found in any enclosing scope a compilation error is triggered.

Local nodes are created if they appear as the target of a binding, whether implicit or explicit. This is the means by which local nodes, storing intermediate results are created. Local nodes are also created for each top-level atom node declaration, See Section 1.1, “Atom Nodes”.

	The node creation rules inside meta-node definitions differ from the node creation rules at the global scope.

	A global node, with the same identifier as a local node, can be referenced using the outer .. operator.

Example: Local Nodes. 

a + b -> x
x + y -> n

addx(n) : {
    # `n` refers to the local argument node `n`, not the global `n`
    # `x` refers to the global node `x`
    n + x
}

Example: Meta-Nodes. 

1-(n) : n - 1

factorial(n) :
    case (
        # The `1-` refers to the global `1-` meta-node
        n > 1 : n * factorial(1-(n)),
        1
    )

Example: Local nodes storing intermediate results. 

x + 1 -> next

factorial(n) :

    # A local node `next` is created since it appears as the target of
    # a binding. `next` does not refer to the global node of the same
    # name.

    n - 1 -> next

    case (
        n > 1 : n * factorial(next),
        1
    )

Example: Local Node Declarations. 

cycle(a, b) : {
    x; y;  # Declare local nodes `x` and `y` 

    cons(a, y) -> x
    cons(b, x) -> y

    x
}

The special self node is a local node which represents the meta-node’s value. This node can be used to set the value, returned by the meta-node, using explicit bindings.

When an explicit binding to self is established, the meta-node no longer returns the value of the last node in its definition.

	A meta-node may not have more than a single context, see Section 2.5, “Contexts”, as it is ambiguous which context’s value function to use as the meta-node function.

	In the absence of an explicit binding to self, the last node in the meta-node’s definition is implicitly bound to self.

Example. 

factorial(n) : {
    n * factorial(n - 1) -> next
    case (n > 1 : next, 1) -> self 
}

In the example, above, the value returned by the factorial meta-node is set by an explicit binding to the self node. The meta-node no longer evaluates to the value of the last node in the declaration list.

The self node is particularly useful for creating a dictionary of values to which the meta-node evaluates to, see Section 2.9, “Subnodes”:

Example: Creating Dictionaries. 

Person(first, last): {
    first -> self.first-name
    last -> self.last-name
}

The body of a meta-node can contain other meta-node definitions nested inside it. These meta-nodes are local to the body, and can only be used inside it, even if the same meta-node identifier appears in an expression outside the body. If a meta-node with the same identifier is already defined at global scope, the nested meta-node shadows it in the scope of the body. This means that references to the meta-node within the body refer to the nested meta-node and not the global node.

Example: Factorial with Nested Tail-Recursive Helper Meta-Node. 

factorial(n) : {
    # `iter` is local to `factorial`
    iter(n, acc) : {
        case (
            n > 1 : iter(n - 1, n * acc),
            acc
        )
    }

    iter(n, 1)
}

The special /quote operator returns its argument, treated as a literal symbol rather than a node expression.

	The ' macro from the core module is the preferred shorthand for the /quote operator.

Example. 

# This is interpreted as the literal symbol `x` rather than the node
# with identifier `x`.

/quote(x)

# The following is a shorthand for the above
'(x)

These can be used inside macro nodes to insert literal node or operator names.

Example: Definition of ' macro. 

'(thing) :
    list(/quote(/quote), thing)

/attribute(', macro, True)

Generally a macro-node expands to a declaration involving some other meta-node. The meta-node might not be located in the same module, see Section 4, “Modules”, as the module in which the macro-node instance occurs. Using the quote operator to generate a declaration involving the meta-node may result in a compilation error, if the meta-node is not present in the module in which the macro-node instance occurs, or may result in a node declaration involving an entirely different meta-node, if the module contains a node with the same identifier.

Node objects can be referenced directly with the node reference operator, &. When the declaration returned by a macro-node contains a raw node object, no node lookup is done and the raw node object is used as though it has been returned by node lookup. This is useful in macros as the node is looked up once in the module containing the macro-node’s definition.

Example: Definition of <- Macro. 

<-(target, src) :
    list(&(->), src, target)

/attribute(<-, macro, True)

The <- macro function, in the example above, returns a functor expression where the operator is the node object ->. When the functor expression is processed, the operator is taken to be the -> node, rather than the node with identifier -> in the module in which the instance is processed.

Any node can be referenced including ordinary nodes and macro-nodes. Special operators, however, cannot be referenced and have to be returned as quoted symbols instead. There is no issue with directly quoting the special operator’s identifier, in expressions returned by macros, as there is for meta-nodes since the meaning of a special operator cannot be overridden and does not change with the module. Most of the special operators mentioned till this point, which are not an identifier prefixed with /, such as ->, :, &, ., .. are actually builtin macro nodes which expand to an internal special declaration, thus can be referenced with the & operator. Special operators beginning with /, such as /attribute, /operator, /module are actual special operators and cannot be referenced with &.

When a raw node referenced occurs in code which is intended to be evaluated at runtime, rather than during macro expansion, the runtime node object, of the node, is referenced. The nature of this object is dependent on the backend.

The special /use operator creates pseudo-nodes for the modules passed as arguments. The pseudo-nodes are created with the same identifiers as the modules.

	Module pseudo-nodes are referred to as such, since syntactically they are the same as any other node, however the value of a module pseudo-node cannot be referenced nor can bindings involving it be established.

Syntax. 

/use(mod1, mod2, ...)

	Creating a pseudo node in a module, which contains a node with same identifier as the pseudo-node, results in a compilation error.

Nodes from the used modules can then be referenced as subnodes of the module pseudo nodes.

Example. 

/module(mod1)

a -> b

/module(mod2)
/use(mod1)

# Reference node `b` from module `mod1`
mod1.b -> b
x -> mod1.b

Meta-nodes from a different module can be also referenced as subnodes of the module pseudo-node.

Example. 

/module(mod1)

add(x, y) : x + y

/module(mod2)
/use(mod1)

# Use the `add` meta-node from module `mod1`
mod1.add(a, b) -> c

	Nodes referenced from other modules, can appear both as dependencies or observers of bindings.

	Referencing a subnode of a module pseudo-node does not result in the automatic creation of a node in that module. Referencing a node that does not exist in the module results in a compilation error.

A pseudo-node with a different identifier, from the identifier of the module, can be created using the special /use-as operator. This is useful for when the module identifier is too long to type out repeatedly, or there is already a node, in the current module, with the same identifier.

the /use-as operator takes two arguments, the identifier of the module and the name of the pseudo-node to create in the current module:

/use-as(module-name, pseudo-node-name)

The above examples can be rewritten using /use-as declarations:

Example. 

/module(mod1)

a -> b

/module(mod2)
/use-as(mod1, m1)

# Reference node `b` from module `mod1`
m1.b -> b
x -> m1.b

Example. 

/module(mod1)

add(x, y) : x + y

/module(mod2)
/use-as(mod1, m1)

# Use the `add` meta-node from module `mod1`
m1.add(a, b) -> c

The second approach to referencing a node, residing in another module, is to add it directly to the current module. With this approach there is no need to reference the node as a subnode of a module pseudo-node. This is referred to as importing the node and is achieved using the /import operator.

The /import operator adds the identifiers of nodes, residing in another module, to the current module. The result is that the node can be referenced directly by its identifier, as though it were declared in the current module.

The /import operator has two forms:

Syntax. 

# Short form: Import all nodes exported from `module`
/import(module)

# Long form: Import only the nodes listed in the arguments after the
# module identifier.
/import(module, node1, node2, ...)

Example: Long form. 

/module(mod1)

a -> b

/module(mod2)

# Import node `b` from `mod1`
/import(mod1, b)

# Node `b` is the same `b` as in `mod1`
b -> a
x -> b

The short form only imports those nodes which are explicitly exported from the module. Nodes are explicitly exported from the current module with the /export operator which simply takes the identifiers of the nodes to export as arguments.

Syntax. 

/export(node1, node2, ...)

Each /export declaration adds (does not replace) nodes, that are in the arguments, to the exported nodes of the current module.

Example: /export and short form /import. 

/module(mod1)

a -> b

# Export node `b`
/export(b)

/module(mod2)
# Import all nodes exported from `mod1`
/import(mod1)

# Node `b` is the same `b` as in `mod1`
b -> a
x -> b

Meta-node Example: /export and short form /import. 

/module(mod1)

add(x, y) : x + y

/export(add)

/module(mod2)
/import(mod1)

# Use the `add` meta-node from module `mod1`
add(a, b) -> c

A side effect of /import is that if the identifier of an imported node, whether imported by the long or short form of /import, is registered as an infix operator in the module, from which it is being imported, it’s entry in the module’s operator table is copied over to the current module. This allows the operator to be placed in infix position, in the current module.

	All nodes in the builtin module, which contains the special operators mentioned so far (->, :, .., &, .), are automatically imported into the init module.

It may be necessary to reference a node in another module without creating a pseudo-node, for its module, and without importing it in the current module. The special /in operator directly references a node in another module by the module and node identifiers.

Syntax. 

/in(module-id, node-id)

The first argument is the identifier of the module containing the node, and the second argument is the identifier of the node.

	module-id is the identifier of the module itself, and not the identifier of a module pseudo-node.

Example: /in Operator. 

/module(mod1)

a -> b

/module(mod2)

# Reference node `b` in `mod1` directly
/in(mod1, b) -> a
x -> /in(mod1, b)

Example: /in Operator. 

/module(mod1)

add(x, y) : x + y

/module(mod2)

# Use the `add` meta-node from module `mod1`
(/in(mod1, add))(a, b) -> c

New infix operators can be registered using the special /operator declaration. This declaration modifies the operator table of the current module.

Syntax. 

/operator(identifier, precedence [, (left | right)])

The first argument is the node identifier to register as an infix operator. The second argument is the precedence as an integer value. The third argument specifies the associativity. This is either the identifier left or right for left or right associativity. If the third argument is omitted, left associativity is assumed.

	The identifier does not have to name a node or meta-node that exists at the time the /operator declaration is processed. The table only stores the identifier for syntactic transformations, no information about the actual node is stored.

An /operator declaration adds an entry to the current module’s operator table if it does not already contain an entry for the identifier. If the table already contains an entry for the identifier, the precedence and associativity values of the existing entry are replaced with those given in the arguments to the /operator declaration.

	The precedence and associativity of all operators can be changed, with the exception of function application.

When a node is imported into the current module and there is an entry, for the node’s identifier, in the operator table of the module, from which the node is being imported, the entry is copied over into the current module’s operator table, replacing any existing entries for the identifier.

Example: + infix operator from core module. 

# Register `+` as infix operator
/operator(+, 100, left)

# Now `+` can appear in infix position
a + b

# It can also still appear in prefix position
+(a, b)

Interprets x as a literal symbol rather than a node declaration. See Literal Symbols.

The same symbol object is always returned for a given symbol name.

Pattern Matching

Matches the literal symbol x. See Pattern Matching.

Returns x interpreted as a literal character.

Pattern Matching

Matches the character literal produced by the given argument. See Pattern Matching.

Returns the raw node object corresponding to the node with identifier node. See Node References.

Establishes a binding between node source and node target.

	Registered as an infix operator with precedence 10 and right associativity.

Establishes a binding between node source and node target.

Same as -> however the argument order is reversed with the first argument being the target node and the second argument being the source node.

	Registered as an infix operator with precedence 10 and left associativity.

Indicates an explicit context to which bindings, involving node as the target, should be established.

When the @ expression appears as the target of a binding, the binding to node is established in the context with identifier context, see Section 2.5, “Contexts”. The context identifier may be omitted in which case the identifier default is assumed.

context may also be a functor of the form when(context-id, type), where context-id is the context identifier and type is a node, of which the value is interpreted as a failure type. In this case the binding will only be activated if the failure type, of the previous binding in the context, is equal to type by =. See Conditionally Active Bindings based on Failure Type. If context-id is omitted, that is context is of the form when(type), the identifier default is assumed.

	Registered as an infix operator with precedence 800 and left associativity. The when symbol is also registered as an infix operator with precedence 850 and left associativity.

When appearing as the target of a binding, a binding is established to node which is only active when node is in the state with identifier state.

state may also be a functor of the form from => state, in which case the binding is only active when the state of node changes from the state with identifier from to the state with identifier to.

See Section 2.10, “Node States” for more information.

	Registered as an infix operator with precedence 700 and left associativity. The => symbol is also registered as an infix operator with precedence 750 and left associativity.

Defines a meta-node with identifier id, argument list args and definition body. See Section 3, “Meta-Nodes”.

	Registered as an infix operator with precedence 5 and right associativity.

Explicitly references a node defined in the enclosing scope of the meta-node. See Section 3.3, “Outer Node References”.

Returns a failure with a given failure type.

Returns the failure type of x.

Returns a failure if x does not evaluate to a failure or evaluates to a failure with no type.

Returns true if x fails to evaluate to a value.

Pattern Matching

Matches if the source node evaluates to a failure. If the argument x is provided matches only failures of type x otherwise matches any failure. See Pattern Matching.

Returns true if x evaluates to a value, false if x fails to evaluate to a value.

Tests for failure with a given type.

Returns true if x fails with failure type equal to type, by =. Returns false if the failure type of x is not equal to type or x does not fail.

Evaluates to true if x evaluates to a value. If x evaluates to a failure, evaluates to the failure value.

Returns value if test does not fail. If test fails, the failure is returned.

Tests that each argument of a functor expression does not fail, before evaluating the expression.

If at least one argument fails, then the entire functor node fails.

Returns the value of try if it does not evaluate to a failure. If try evaluates to a failure returns the value of catch.

Failure type representing the absense of a value.

Optional meta-nodes arguments, for which no value is provided, are bound to a failure of this type.

Node No-Value! is bound to a failure of this type.

A failure of this type is returned when an argument to a meta-node is not of the expected type.

Node Type-Error! is bound to a failure of this type.

A failure of this type is returned when attempting to access an element at an index that is outside the bounds of the list or string.

Node Index-Out-Bounds! is bound to a failure of this type.

A failure of this type is returned by int when a string, from which an integer cannot be parsed, is provided as an argument.

Node Invalid-Integer! is bound to a failure of this type.

A failure of this type is returned by real when a string, from which a real number cannot be parsed, is provided as an argument.

Node Invalid-Real! is bound to a failure of this type.

A failure of this type is returned when a meta-node is invoked indirectly, by a meta-node reference see Section 3.5, “Higher-Order Meta-Nodes”, with an incorrect number of arguments.

Node Arity-Error! is bound to a failure of this type.

Computes the sum of x and y.

	Registered as an infix operator with precedence 100 and left associativity.

Computes the difference of x and y.

If y is not provided, returns the negation of x, i.e. x multiplied by -1.

	Registered as an infix operator with precedence 100 and left associativity.

Computes the product of x and y.

	Registered as an infix operator with precedence 200 and left associativity.

Computes the quotient of x and y.

	Registered as an infix operator with precedence 200 and left associativity.

Computes the remainder of the division of x by y.

	Registered as an infix operator with precedence 200 and left associativity.

Returns true if x is less than y.

	Registered as an infix operator with precedence 50 and left associativity.

Returns true if x is less than or equal to y.

	Registered as an infix operator with precedence 50 and left associativity.

Returns true if x is greater than y.

	Registered as an infix operator with precedence 50 and left associativity.

Returns true if x is greater than or equal to y.

	Registered as an infix operator with precedence 50 and left associativity.

Returns true if a is equal to b.

	Registered as an infix operator with precedence 50 and left associativity.

Returns true if a is not equal to b.

See = for the rules of equality.

	Registered as an infix operator with precedence 50 and left associativity.

Logical AND.

Returns True if x and y evaluate to True. Returns False otherwise.

	Registered as an infix operator with precedence 25 and left associativity.

Pattern Matching

Matches if both the nested patterns in x and y match the source node. See Pattern Matching.

Logical OR.

Returns True if either x or y evaluate to True. Returns False if both x and y evaluate to False.

	Registered as an infix operator with precedence 20 and left associativity.

Pattern Matching

Matches if at least one of the nested patterns in x and y match the source node. Both the bindings generated by the patterns x and y are established if the corresponding pattern condition matches. See Pattern Matching.

	This pattern matches even if not all its nested patterns have matched.

Logical NOT.

Returns True if x evaluates to False.

Pattern Matching

Matches if the nested pattern x does not match. The bindings generated by x are not established by this pattern. See Pattern Matching.

	Since this binding does not establish any bindings, it is treated as a constant pattern and may only appear nested inside other patterns.

Returns true-value if condition is True otherwise returns false-value.

If false-value is not provided, a failure is returned if condition evaluates to False.

<clause> = <condition> : <value>

Expands to nested if expressions.

Each argument is a clause is of the form condition : value. The case expression evaluates to the value corresponding to the first clause of which the condition node evaluates to True. The final clause may also be of the form value, in which case it becomes the default value, to which the case expression evaluates if the conditions of all the other clauses evaluate to False.

Example. 

case(
    a < b : a,
    b >= a : b
)

# Is equivalent to:

if(a < b, a, if(b >= a, b))

Example with default value. 

case(
    a < b : -1,
    b > a : 1,
    0
)

# Is equivalent to:

if(a < b, -1, if(b > a, 1, 0))

The value of this node represents Boolean True.

The value of this node represents Boolean False.

Converts x to an integer value.

If x is neither of the above returns a failure of type Type-Error.

Pattern Matching

Matches if the source node is an integer, in which case x is matched to the integer value. See Pattern Matching.

Converts x to a real number value.

If x is neither of the above returns a failure of type Type-Error.

Pattern Matching

Matches if the source node is a real, in which case x is matched to the real value. See Pattern Matching.

Converts x to a string.

Pattern Matching

Matches if the source node is a string, in which case x is matched to the string value. See Pattern Matching.

Converts x to an integer value.

Same as int however with the target-node attribute set to int. As such, in the following:

a -> to-int(b)

Node b is set to the value of a converted to an integer.

Converts x to an real number value.

Same as real however with the target-node attribute set to real. As such, in the following:

a -> to-real(b)

Node b is set to the value of a converted to a real number.

Converts x to an integer value.

Same as string however with the target-node attribute set to string. As such, in the following:

a -> to-string(b)

Node b is set to the value of a converted to a string.

Returns true if x is an integer.

Returns true if x is a real valued number.

Returns true if x is a string.

Returns true if x is a symbol.

Returns true if x is a character.

Returns true if x is either positive or negative infinity.

Returns true if x is a NaN (Not a Number) value.

Creates a list with the head as the first element and tail as the list of remaining elements.

Pattern Matching

Matches if the source node is a non-empty list, in which case head is matched to the head of the list and tail is matched to the tail of the list. See Pattern Matching.

Returns the head (first element) of a list.

If list is the empty list, returns a failure of type Empty.

If list is not a list returns a failure value of type Type-Error.

Returns the tail, the list containing the elements after the first element, of a list.

If list is the empty list, returns a failure of type Empty.

If list is not a list returns a failure value of type Type-Error.

Returns true if thing is a list of at least one element, false otherwise.

	Does not return true if thing is the empty list.

The value of this node represents the empty list.

The value of this node is a failure of type Empty. This failure is returned when attempting to access the head or tail of an empty list.

Creates a list with elements xs.

Pattern Matching

Matches if the source node is a list of the same size as xs, in which case each argument in xs is matched to the corresponding list element. See Pattern Matching.

Creates a list containing, as elements, all the arguments in xs excluding the last. The last argument in xs is treated as a list containing the remaining elements.

Pattern Matching

Matches if the source node is a list of at least one less elements that the number of elements in xs. The arguments, excluding the last, are matched to the corresponding elements in the list with the last argument being matched to the remaining list elements. See Pattern Matching.

Creates a list containing, as elements, all the arguments in xs.

Unlike list, if at least one of xs fails to evaluate to a value, the failure is returned.

Retrieves the element of a list at a particular index.

Returns a failure of type Index-Out-Bounds if n is greater than the number of elements in list.

Returns a list containing the elements of list2 appended to list1.

Folds a list to a single value, starting from the first element.

The function f is first applied on x and the head of list. Subsequently, f is applied on the result of the previous application and the next element of list, until the end of list is reached.

Folds a list to a single value, starting from the first element.

Same as foldl' except the head of list is used as the initial first argument to the fold function f.

Folds a list to a single value, starting from the last element.

f is first applied on the last element of list and the value of x. If the x argument is not provided or x evaluates to a failure of type No-Value, f is first applied on the last two elements of list. Subsequently f is applied on the previous element of list and the result of the previous application, until the head of list list is reached.

If list only has a single element and x is not provided, the element is returned as is. If l is empty and x is provided, x is returned as is.

Applies a function on each element of a list.

Returns a list containing the result of applying f on each element of list in turn.

Filters elements from a list.

Returns a list containing only the elements of list for which the function f returns true.

Returns true if f returns true for every element of list.

Returns true if f returns true for at least one element of list.

Returns true if f returns false for every element of list.

Returns true if f returns false for at least one element of list.

Returns the character at a given index in the string.

If the index is greater than the number of characters in this string, returns a failure of type Index-Out-Bounds.

Concatenates str2 to the end of str1.

Returns a list containing the characters in a string.

Returns a string containing the concatenation of the elements in a list.

Each element of list is converted to a string and concatenated to the result string.

Creates a formatted string, in which placeholders are replaced by the arguments in args.

The sequence %s designates a placeholder which is to be replaced by an argument. The first placeholder is replaced by the first argument, the second with the second argument and so on. Each argument is converted to a string prior to being substituted into the result string.

The sequence %% designates a literal % character and is thus replaced with a %.

Retrieves the value of an entry in a dictionary.

If dict does not have an entry for key a failure, of type No-Value is returned.

Applies a function on an argument list.

The argument list, on which f is applied consist of each argument of xs, excluding the last, followed by each element of the last argument of xs.

	If f is not a function or the last argument of xs is not a list, a failure of type Type-Error, is returned.

Returns true if thing is a node object.

Looks-up a node in a module.

Returns the node object or a failure if no node is found.

	Currently there is no way to retrieve a module object, thus the module argument is not used. This functionality will be added in a future release.

Retrieves the value of an attribute of a node.

Returns a failure if the attribute is not set.

Patterns may be nested, that is an argument to a meta-node instance is itself a meta-node instance of which the operator meta-node supports pattern matching. When the arguments contain one or more nested patterns, the bindings to the argument nodes should only succeed if all nested patterns match.

Example. 

x -> list(int(y), z)

The example, above, is similar to the previous example except with the additional condition that the first element of x should also be an integer. That is y is bound to the first element of x and z to the second element of x if x is a list of two elements of which the first element is an integer.

When _ appears nested inside a pattern it matches anything and does not establish any bindings. This is used to indicate that the value for a particular argument is unimportant.

Example. 

x -> list(_, y)

In the example, above, y is bound to the second element of x if it is a list of two elements. The value of the first element of x is ignored completely.

Constant patterns comprise a constant value as opposed to a node. These patterns match when the source node is equal, by =, to the constant value. Constant patterns do not result in any bindings being established however they do affect the condition of the pattern in which they are nested.

	Constant patterns may only be used when nested inside a non-constant pattern.

Constant values include any literal constants, such as numbers, strings as well as character literals, produced by the c macro, and literal symbols, produced by the ' macro.

Example. 

x -> list(1, y, z)

In the example, above, y is bound to the second element of x and z to the third element of x if x is a list of three elements of which the first element is equal to 1.

The following are examples of invalid uses of constant patterns:

Examples: Invalid use of Constant Patterns. 

# Invalid as the pattern is not nested
x -> 1

# Invalid as at least one argument should not be a constant.
x -> list(1, 2)

	Functor nodes, of which the arguments are all constants, such as 1 + 1, are only treated as constant patterns if the meta-node supports pattern matching. In this case the + meta-node does not support pattern matching, thus 1 + 1 is currently not treated as a constant pattern.

The matcher node attribute stores a meta-node which is called to construct the pattern for a given list of arguments. The matcher meta-node is called with two arguments: the place to be matched, which should become the source node of any bindings established by the pattern, and the pattern functor expression itself (including the operator). The meta-node should return a Pattern object, which is a dictionary containing the following entries:

	Pattern objects may be created with the Pattern meta-node.

All bindings, established by a pattern, should be established in an explicit context with identifier match, which is activated only on failures with type Match-Fail. This allows multiple patterns to be specified on a single node, with the node being set to the value corresponding to the binding of the first pattern that matches.

Example: Multiple Patterns. 

x -> int(y)
x -> list(int(y))
x -> list("x", int(y))

The example above contains multiple patterns involving a single node y.

y is bound to:

The following meta-nodes in the core module all have a matcher and may thus appear within patterns.

Creates a Pattern object. See Matchers

Returns the matcher function, stored in the matcher attribute of a node.

Returns a failure if the node’s matcher attribute is not set.

Creates the Pattern object for a pattern expression.

	Can be used for any pattern, including constant patterns.

	If pattern is a functor expression of which the operator is not a meta-node with a matcher, a Pattern with a single binding place -> pattern, and no condition is returned.

Returns an expression which is the conjunction of two expressions, by and.

If c1 evaluates to a failure, returns c2. If c2 evaluates to a failure, returns c1.

	This is useful for creating a condition which combines the conditions of multiple argument nodes.

Returns a list where each binding in bindings is conditioned on condition. See Conditional Bindings.

If condition evaluates to a failure, a condition of True is assumed, thus the bindings are not conditioned.

Failure type indicating that a pattern failed to match.

Node Match-Fail! is bound to a failure of this type.

If condition evaluates to false or to a failure, returns a failure of type Match-Fail, otherwise returns true.

Generates a binding src -> target, with target in the match context which is activated on failures of type Match-Fail.

Creates the node declarations implementing a pattern.

Returns a single node declaration.

	The declaration returned by this meta-node is a suitable return value for a target-transform function. See Section 3.7, “Instances as Targets”.

A Tridash application is compiled to a single runtime module object. When targeting the JavaScript or WebAssembly backends, this is a JavaScript object with at least the following property:

The module object also provides the following member function:

The runtime node object provides three methods:

	In order to be able to set the value of a node, it must be marked as an input node, by setting its input attribute to true. See Section 2.7, “Input Nodes”.

Unless a node is an input node or an output node, that is a node with no observers, there is no guarantee that a runtime node object is created for it, even if it is given a public identifier, due to node coalescing. To ensure that a runtime node object is created for a node, for which a public identifier is assigned, its coalescable and removable attributes should be set to false. See Section 6.1, “Coalescing” for more information.

Most Tridash primitive value types correspond directly to JavaScript primitives:

The remaining value types are represented by instances of classes in the runtime library, which is contained in the Tridash module object.

Failure values are represented by an instance of the Tridash.Fail class, which has one property

Instances of this class are thrown as JavaScript exceptions rather than being returned directly. Generally failure values are represented by thunks, see the next section on lazy evaluation, which, when evaluated, throw a Tridash.Fail exception.

	Use the Tridash.fail function, which takes one argument, the failure type (defaulting to null), to create failure values, which are wrapped in thunks.

The following functions return a JavaScript object, which serves to identify a builtin failure type.

Tridash expressions may be evaluated lazily, that is they are only evaluated at the point where they are first used. Lazily evaluated expressions are wrapped in thunk objects, which are instances of the Tridash.Thunk class.

Thunks are created using the Tridash.Thunk constructor which takes one argument, the thunk computation function. The thunk computation function should be a function of no arguments which computes, and returns, the thunk’s result value.

The Tridash.resolve function, of one argument, computes the value of a Tridash.Thunk, passed as the argument, if it has not been computed already, and returns the resulting value. If the argument is not a Tridash.Thunk object it is returned directly.

	Tridash.resolve repeatedly computes the value of a thunk, which is the result of computing the value of another thunk until the result is not a thunk. This means Tridash.resolve always returns an immediate value, not a thunk object.

Example: Resolving node value and handling failures. 

try {
    value = Tridash.resolve(value);

    // Use resolved value
    ...
}
catch (e) {
    if (e instanceof Tridash.Fail) {
        // Handle failure
        ...
    }
}

In the JavaScript backend, the name of the JavaScript function, which provides the implementation of an external meta-node is given by the value of the node’s js-name attribute. This attribute must be a string which names a function that is globally accessible to the generated JavaScript code, at the time it is run.

Example: Linking external meta-node to JavaScript function. 

## Meta-Node of two arguments
/external(fn, a, b)

## Link to JavaScript 'my_func' function
/attribute(fn, js-name, "my_func")

The function is called passing in the values of the argument nodes as arguments. If the value for an optional argument is not provided to the meta-node, in the Tridash source, the default value is passed to the function. If the optional argument and the arguments following it do not have default values, they are omitted in the generated function call.

Example: External meta-node with optional arguments with default value. 

## Meta-Node with 1 required and 1 optional argument
/external(fn, a, b : 1)

## Link to JavaScript 'my_func' function
/attribute(fn, js-name, "my_func")

## Instance with optional argument omitted
fn(x)

This example compiles to the following call to my_func:

my_func(x, 1)

Example: External meta-node with optional arguments without default value. 

## Meta-Node with 1 required and 1 optional argument
/external(fn, a, :(b))

## Link to JavaScript 'my_func' function
/attribute(fn, js-name, "my_func")

## Instance with optional argument omitted
fn(x)

This example compiles to the following call to my_func:

my_func(x)

Notice that no value is provided for the b argument since it was omitted, in the meta-node instance fn(x) and it does not have a default value.

Rest arguments are accumulated into a single JavaScript array which is passed as the last argument to the function. If the rest argument list is empty, the argument is omitted entirely in the generated function call.

Example: External meta-node with rest arguments. 

## Meta-Node with 1 required and 1 rest argument
/external(fn, x, ..(xs))

## Link to JavaScript 'my_func' function
/attribute(fn, js-name, "my_func")

## Instance 1: 3 rest arguments
fn(a, b, c, d)

## Instance 2: no rest arguments

Instance 1 is compiled to the following call to my_func:

my_func(a, [b, c, d])

Instance 2 is compiled to the following call to my_func:

my_func(a)

Notice no value is passed for the second argument which corresponds to the rest argument.

Each argument, passed to an external function, may either be an immediate value or a Tridash.Thunk object, in the case of an argument which is lazily evaluated. The Tridash.resolve function should be called on each argument, of which the value is actually used, to ensure that the immediate value is obtained.

The function should always return a value, which becomes the return value of the meta-node. This can either be an immediate Tridash value, of one of the types specified in Value Types, or a Tridash.Thunk object.

Any failure value exception, thrown inside the function either by the function itself or while evaluating a thunk, should be caught and wrapped in a Tridash.Thunk object which is returned from the function.

Example: Handling failures in external meta-node functions. 

function my_func(a) {
    try {
        // Resolve value of the `a` argument
        // The result may be a failure value
        a = Tridash.resolve(a);

        // Do something with `a`
        ...
    }
    catch (e) {
        // Handle failure value exception
        if (e instanceof Tridash.Fail) {
            // Wrap failure in thunk object and return
            return new Tridash.Thunk(() => { throw e });
        }

        // Rethrow other exceptions
        throw e;
    }
}

By default, when targeting the JavaScript backend, a standalone JavaScript file is produced, which assigns the nodes and set_values properties of the runtime module object to the exports object. This file can be loaded by a JavaScript runtime which supports the require function, such as Node.js. The properties of the module object can then be accessed as properties of the object returned by require.

Example: JavaScript Module Object Usage. 

# Load the compiled JavaScript module. Substitute `module.js` with the
# path to the generated JavaScript file.

const module = require('module.js');
const node_x = module.nodes.node_x;

// Retrieve value of node_x
const value = node_x.get_value();

...

// Set value of node_x to integer 10
node_x.set_value(10);

The get_value method of the runtime node object takes a single optional argument, which if true (the default), the value of the node is fully evaluated if it is a thunk object, representing a lazily evaluated value. If the argument is false, thunk objects are not evaluated but are returned directly.

Tridash value types are represented by objects stored in the heap of the compiled WebAssembly module’s memory object. The heap is managed by a tracing garbage collector, which is run whenever a memory allocation requests more space than is available.

In order for a Tridash value to be passed to a JavaScript function, and vice versa, it is has to be converted (marshalled) to an equivalent representation using JavaScript types. This functionality is provided by the Tridash.Marshaller class in the JavaScript component of the runtime library, which is encapsulated in the module object Tridash.

Tridash value types, when converted to JavaScript value types, are represented by the following:

The following properties of the Marshaller.FailTypes represent builtin failure types as JavaScript Values:

The Tridash.Marshaller class is responsible for converting Tridash values stored in the WebAssembly heap to equivalent JavaScript values and vice versa. An instance of this class is automatically created when loading the WebAssembly module.

Methods

A pointer may point to a thunk object, which represents a Tridash value which has not been computed yet. When converting a Tridash value to a JavaScript value, all thunk objects are computed. As a result of this each conversion from Tridash to JavaScript may trigger a garbage collection cycle. Likewise, converting a JavaScript value to a Tridash value may also trigger a garbage collection since a new object is created on the heap.

	Converting an infinite list or a cyclic object will result in an infinite loop, due to all lazily evaluated values being computed on conversion.

When converting multiple values, of which the conversion of the first value, a, results in a garbage collection cycle being run, the memory held by the second value, b, may be reclaimed if it is not referenced by an object in the root set. Furthermore, the pointer to b is no longer valid due to the objects being copied to the new heap.

To overcome this problem, before converting a Tridash value to JavaScript, all pointers to other Tridash values should be pushed onto the root set stack, using the stack_push method of Tridash.Marshaller. After the conversion the updated pointer values should be popped off the root set stack using the stack_pop method of Tridash.Marshaller.

	Every call to stack_push must be balanced by a call to stack_pop.