1 files changed, 78 insertions, 0 deletions
diff --git a/doc/chains.org b/doc/chains.org
new file mode 100644
index 0000000..0d20af5
--- /dev/null
+++ b/doc/chains.org
@@ -0,0 +1,78 @@
+#+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