#+title: Chains
#+author: Thomas Albers Raviola

* Syntax
** Comments
Inline comments start with a % sign and go up to and /including/ the newline
character. Unwanted newline characters may thus be skipped by clever use of
comments.

* Evaluation
Chains works by reading input and building a syntax tree representing the
expresions inside the file. The difference with other programming languages is
that the structure of this tree may be modified by the code running. The final
resulting tree is then flattened into text and outputted.

** Chains; function calls
A chain is evaluated by first taking the first link. This must consist of an
object that evaluates to a function. Then the other links are evaluated by
evaluating each of their elements. Finally, the function gets called by passing
each of the following links as its arguments.

Every function returns a chain with a single link containing the return value.

A chain that is not a function call gets spliced in place.

The result chain of a function gets spliced, effectively appending its contents
to the surrounding link.

Whitespace gets ignored inside the first link if no other text is present.

Additionaly, as a bit of syntax sugar to make code more readable, if a symbol
preceeds a chain, the chain is implicitely a prepended link with the symbol
inside as its only element.

Therefore, the following expressions are equivalent for calling a function
~func~ taking two arguments:

1. ~{@func}{...}{...}~
2. ~{ @func }{}{}{}~
3. ~@func{...}{...}~

A behaviour unique to functions in chains is the possibility to consume its
siblings as arguments to the function being called, effectively changing the
structure of the abstract syntax tree. Because this effect may be confusing when
reading code, it is recomended to only use it for defining text elements.

** Other objects
Text and all other builtin types are evaluated to themselves. However, note that
no implicit convertion to text is made and that in the top-level only text
objects may be present; any other type of object will signal an error. Use the
~@text~ function to cast objects into text.

* Types
** Text
** Boolean
** Integers
** Floats
** Functions
** Empty line
** Symbols
** Chains

* Builtin functions and special forms
** @define
** @lambda
** @lambda\*
** @quote
** @+, @-, @*, @/
Usual arithmetic operations
** @use
Runs the code inside the provided file without inserting the generated text into
the module's output.
** @include
Runs the code inside the provided file inserting the resulting text in the
position of the function call.
** @text
** @int
** @float