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

    Gaea text template language!

    Thanks to hkaiser, VeXocide and heller !!! on Spirit IRC

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

Reserved tokens:
    [
    ]
    [u
    [def
    [/
    ["
    [""
    [`
    \[
    \]

    (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 single element list with 3 elements. 3rd is a
2-element list where the first element is a single element list and the
second has 2 elements. Formatting makes it clear:

  1st:

    [a][b][c]

  2nd:

    [
      [a][b][c]
    ]

  3rd:

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

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 ]

Identifiers:

  This-is-an-identifier
  ?
  *
  ==
  ?WTH

Identifiers can be just about any string without spaces and the
reserved [ and ] characters.

Function:
Forward declarations:

  [def foo]
  [def dup a]

Definitions:

  [def foo][body]

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

  [def follow a b][[`a][`b]]

Function invocation:

  [`f0]                       [/ nullary function ]
  [`f1 apple pie]             [/ unary function. argument is a string. ]
  [`f1 [apple pie]]           [/ unary function. argument is a 1-element list. ]
  [`f2 [apple][pie]]          [/ 2 arguments. argument is a 2-element list. ]

  [/ Function invocations are explicit in Gaea to remove the
     ambiguity between invocations and lists and also to make
     functions first-class objects that can be passed as arguments
  ]

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]]
  ]

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 ]

Error conditions: