[/=============================================================================

    Gaea text template language!

    Thanks to hkaiser, VeXocide and heller !!! on Spirit IRC
    Thanks to Daniel James for added comments and suggestions

==============================================================================]

Reserved tokens:
    [
    ]
    [u
    [def
    [decl
    [lambda
    ...]
    [/
    ["
    [""
    ""]
    \[
    \]

    (the last 2 is for escaping [ and ])

Comments:

    [/ nested comments. ]
    [/ nested [/ nested comments] comments. ]
    [/ balanced square braces [ and ] (i.e starts with [ and ends with ] and
       with equal number of [ and ]), are allowed inside comments. This is a
       good way to comment out code. ]

Lists:

  [a][b][c]       [/ 1st ]
  [[a][b][c]]     [/ 2nd ]
  [[a][[b][c]]]   [/ 3rd ]

Lists can form linear or hierarchical data structures. 1st is a
3-element list. 2nd is a 1-element list. The single child is a
list with 3 elements. 3rd is a 1-element list. The single child
is a 2-element list where the first element is a 1-element list
and the second has 2 elements.

Describing this in english makes me dizzy! Formatting makes it clear:

  1st:

    [a][b][c]

  2nd:

    [
      [a][b][c]
    ]

  3rd:

    [
      [a]
      [
        [b][c]
      ]
    ]

The first is an example of an "open-ended" list. The 2nd and 3rd are
not. Open-ended lists are used to pass in variable number of arguments
to a function (more below).

Strings:

  This is a string

  Jack and Jill went up the hill to fetch a pail of water.
  Jack fell down and broke his crown, and Jill came tumbling after.

  123 is a numeric string

Markups ([...]) are always significant, except inside escapes
(see ["" Escapes below). Like HTML/XML spaces are coalesced unless
they are inside the preformatted markup (see [" Preformatted below).

A string is just a special form of list with single character elements.

Unicode Code Points:

  [u2018]                     [/ Generates unicode code point (hexadecimal). ]

Escapes:

  \[                          [/ Escapes the open bracket]
  \]                          [/ Escapes the close bracket]
  [""[x]""]                   [/ Escapes all occurances of [ and ] in x. ]

Preformatted:

  [" some-text]               [/ Make spaces, tabs and newlines significant ]

Symbols:

  This-is-a-symbol
  ?
  *
  ==
  ?WTH

Symbols can be just about any string without spaces and the
reserved tokens.

Function:
Forward declarations:

  [decl foo]

  [decl dup a]

Definitions:

  [def foo][body]

  [def dup a][[a][a]]

  [def cat a b][[a][b]]

Function invocation:

  [foo]                       [/ nullary function ]

  [dup apple pie]             [/ unary function. argument is a string. ]

  [dup [apple pie]]           [/ unary function. argument is a 1-element list. ]

  [cat [apple][pie]]          [/ 2 arguments. argument is a 2-element list. ]

Example:

  [def f3 a b c]
  [
    [def d][de Guzman]
    [a] [d], [b] [d], [c] [d]
  ]

  [f3 [Joel][Mariel][Tenji]]  [/ returns Joel de Guzman, Mariel de Guzman, Tenji de Guzman ]

Variable args:

  [decl table title rows...]

The trailing elipsis signifies an open ended list. It is only
allowed after the final formal argument preceding the closing bracket.

Example invocation:

  [table title
      [[Heading 1] [Heading 2] [Heading 3]]
      [[R0-C0]     [R0-C1]     [R0-C2]]
  ]

Intrinsics:

  [def head x]                [/ Get first element from x. ]
  [def tail x]                [/ Return a list or string without the first element of x. ]
  [def empty x]               [/ Return 1 if x is empty else 0. ]
  [def at x n]                [/ Return the nth element of x. ]
  [def size x]                [/ Return size of x. ]
  [def append x e]            [/ Append e to x. ]
  [def insert x e n]          [/ Insert e to x at position n. ]
  [def reverse x]             [/ Reverse x. ]
  [def join x y]              [/ Join x and y as one longer list. ]

  [def fold x s f]            [/ For a list x, initial state s, and binary function f,
                                 fold returns the result of the repeated application of
                                 [f e s] for each element e of list x, to the result
                                 of the previous f invocation (s if it is the first call). ]

Many list operations can be implemented using fold. Yet, for the sake
of efficiency, we provide these common operations as intrinsics.

  [def transform x f]         [/ For a list x and function f, transform returns a new
                                 list with elements created by applying [f e] to each
                                 element e of x. ]

Since strings are just special forms of lists, all functions that accept
lists can also accept strings.


  [def + a b]                 [/ Add a and b. both a and b are numeric integer strings. ]
  [def - a b]                 [/ Subract a and b. both a and b are numeric integer strings. ]
  [def * a b]                 [/ Multiply a and b. both a and b are numeric integer strings. ]
  [def / a b]                 [/ Divide a and b. both a and b are numeric integer strings. ]
  [def % a b]                 [/ Remainder of a / b. both a and b are numeric integer strings. ]

  [def == a b]                [/ Returns 1 if a == b. ]
  [def < a b]                 [/ Returns 1 if a is less than b. ]
  [def && a b]                [/ Returns a and b (boolean logic). ]
  [def || a b]                [/ Returns a or b (boolean logic). ]
  [def if cond then else]     [/ Returns then if cond is 1, otherwise returns else. ]

Other comparisons and booleans can be synthesized from the basics above.
For example ! can be defined as [def ! x][[if [x][0][1]]], != can be defined
as [def != a b][[![==[a][b]]]], etc.

  [def >> file]               [/ Loads file. ]
  [def << file x]             [/ Saves x to file. ]

>> processes files (i.e. markups are significant). If you want to load
files verbatim, enclose it in the escape markup. Example:

  [""[>> text.gia]""]

Lambda Functions:

Functions are first class and can be passed and returned from other functions.
For example, the transform intrinsic requires a lambda function for its
last (f) argument.

Here's an example of a lambda function:

  [lambda x][[dup [x]]]

Its syntax resembles a function definition.

Here's a sample invocation of transform:

  [transform [list] [[lambda x][[dup [x]]]]]

This doubles all elements of the list.

Error conditions (todo):