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

    Gaea text template language!

    Thanks to hkaiser, VeXocide and heller !!! on Spirit IRC
    Thanks to Daniel James and Dave Abrahams for added comments
    and suggestions (Boost Docs List).

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

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

    (the last 2 is for escaping [ and ])

Comments:

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

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

Formatting makes it clear:

  1st:

    [
      [a][b][c]
    ]

  2nd:

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

Function:
Forward declarations:

  [decl [foo]]

  [decl [dup a]]

Forward declarations are good for recursion and is always perfect
for documenting functions.

Definitions:

  [def [foo] body]            [/ nullary function def ]

  [def foo body]              [/ short for nullary function def ]

  [def [dup a] [a][a]]        [/ arguments always need to be evaluated, e.g. [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. ]

Function identifier:

Function identifiers can either consist of:

  An initial alphabetic character or the underscore,
  followed by zero or more alphanumeric characters or
  the underscore. This is similar to your typical C/C++ identifier.
  One to four character operator (a non-alphanumeric printable character)

Formal Arguments

  Formal arguments are identifiers consisting of an initial
  alphabetic character or the underscore, followed by zero
  or more alphanumeric characters or the underscore. This is
  similar to your typical C/C++ identifier.

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 dot '.' before the last formal argument signifies variable
number of arguments. It is only allowed before the final formal
argument. The actual arguments passed are collected in one list.

Example invocation:

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

Intrinsics:

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

  [decl [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.

  [decl [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.


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

  [decl [== a b]]              [/ Returns 1 if a == b. ]
  [decl [< a b]]               [/ Returns 1 if a is less than b. ]
  [decl [&& a b]]              [/ Returns a and b (boolean logic). ]
  [decl [|| a b]]              [/ Returns a or b (boolean logic). ]
  [decl [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.

  [decl [>> file]]             [/ Loads file. ]
  [decl [<< 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 to 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.