<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:trans="http://docbook.org/ns/transclusion"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <title>Syntax</title>

  <para><informaltable>
      <tgroup cols="3">
        <tbody>
          <row>
            <entry>Literals, Expressions, Basic Statements</entry>

            <entry>Annotations</entry>

            <entry>Intrinsics: query</entry>
          </row>

          <row>
            <entry>Identifiers, Code Blocks</entry>

            <entry>Branch Statements</entry>

            <entry>Interfaces: Extern-C</entry>
          </row>

          <row>
            <entry>Functions</entry>

            <entry>Loops</entry>

            <entry>Other: Transcend, Versions</entry>
          </row>

          <row>
            <entry>Types</entry>

            <entry>Variants</entry>

            <entry/>
          </row>
        </tbody>
      </tgroup>
    </informaltable></para>

  <para>There are number of principles Xreate syntax based on:</para>

  <itemizedlist>
    <listitem>
      <para>Follows SSA form: each identifier is defined only once and no
      redefinitions allowed</para>
    </listitem>

    <listitem>
      <para>Order in which identifiers are defined does not influence
      computation order. Identifiers are computed in order based on
      dependencies between expressions. Order in which identifiers are defines
      reflects preferences and what is convenient for a developer.</para>
    </listitem>
  </itemizedlist>

  <section>
    <title>Literals and expressions</title>

    <para>In Xreate expressions have a form:</para>

    <synopsis>SYNTAX:
//expression// [:: //type//; //annotations-list// ]</synopsis>

    <para>where <emphasis>annotation-list</emphasis> is a list of annotations
    delimited by semicolon.</para>

    <para>Expressions consist of literals and various operations as
    follows:</para>

    <informaltable>
      <tgroup cols="2">
        <colspec colwidth="115*"/>

        <colspec colwidth="885*"/>

        <tbody>
          <row>
            <entry>Literals</entry>

            <entry>numbers, strings: <code>5, "Nimefurahi
            kukujua"</code></entry>
          </row>

          <row>
            <entry>Lists, records</entry>

            <entry>Record is a collection of elements of different types -
            <code>{year = 1934, month = "april"}</code>. List is a collection
            of elements of the same type without keys - <code>{16, 8,
            3}</code></entry>
          </row>

          <row>
            <entry>Arithmetic operations</entry>

            <entry>Basic arithmetic operations: <code>+, -, *,
            /</code></entry>
          </row>

          <row>
            <entry>Relations</entry>

            <entry><code>==, !=, &lt;&gt;, &lt;, &lt;=, &gt;, &gt;=</code>.
            Both <code>!=, &lt;&gt;</code> mean <emphasis>not equal</emphasis>
            relation. Examples: <code>8&gt;=3, "Blue" &lt;&gt;
            "Green"</code></entry>
          </row>

          <row>
            <entry>List and struct operations</entry>

            <entry><emphasis>index</emphasis> operation to access individual
            elements of a list or a record. Example: <code>colors = {"Green",
            "Blue"}::[string]. color = colors[0]:: string.</code> Record's
            element access: <code>date = {year = 1934, month = "april"}. year
            = date["year"]</code></entry>
          </row>

          <row>
            <entry>Identifiers</entry>

            <entry>Example: <code>a - b</code></entry>
          </row>

          <row>
            <entry>Functions</entry>

            <entry>Example: <code>result = isOdd(6).</code></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section>
    <title>Code Blocks</title>

    <para>Block is a list of expressions delimited by period. It has a
    <emphasis>body</emphasis> - main expression and optionally some identifier
    definitions.</para>

    <synopsis>SYNTAX:
{
  [//ident// = //expression// . | //body-expression// . ]..
}</synopsis>

    <para>Code block consists of expression called <emphasis>body
    expression</emphasis> and optional set of assignments to define
    identifiers used by body expression. Block computation is defined as
    result of associated body expression computation. If any expression
    encountered during computation includes some identifiers they are computed
    first.</para>

    <programlisting xml:id="CodeBlocks1">test = function:: int 
{
  a = 10::  int. 
  b = 2::   int.

  a + b::   int
}</programlisting>

    <para>Above is an example of code block which have <code>a+b</code> as a
    body expression. In this case body depends on identifiers <code>a</code>,
    <code>b</code> so compiler computes both of them beforehand.</para>

    <para>Computation order depends only on dependencies between expressions.
    This approach has properties as follows:</para>

    <itemizedlist>
      <listitem>
        <para>Mutually independent identifiers can be evaluated in any
        order</para>
      </listitem>

      <listitem>
        <para>Identifier gets computed only if it's required by block body
        expression or other required identifier</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Functions</title>

    <synopsis>SYNTAX:
//function-name// = **function** ([//argument//:: //type//[; //annotation-list//]]...):: //return-type// [; //annotations//]... 
//function-block//</synopsis>

    <itemizedlist>
      <listitem>
        <para><emphasis>function-name</emphasis> name of function</para>
      </listitem>

      <listitem>
        <para><emphasis>argument</emphasis> formal parameter. Arguments
        delimited by comma.</para>
      </listitem>

      <listitem>
        <para><emphasis>type</emphasis>, <emphasis>return-type</emphasis>
        formal parameter and returning value types</para>
      </listitem>

      <listitem>
        <para><emphasis>function-block</emphasis> code block that holds
        function definition</para>
      </listitem>

      <listitem>
        <para><emphasis>annotations</emphasis> list of annotations delimited
        by semicolon</para>
      </listitem>
    </itemizedlist>

    <para>Below is an example of a function <code>sum</code>. It takes two
    arguments and returns their sum. Also it has few annotations. First
    annotation <code>entry</code> has a special meaning - it depicts entry
    point or main function in a program. Second annotation
    <code>status(needs_review)</code> is an example that developers can
    annotate function using custom annotations to express different
    properties.</para>

    <programlisting xml:id="Functions1">sum = function(x:: int, y:: int):: int; entry; status(needs_review)
{
  x+y
}</programlisting>
  </section>

  <section>
    <title>Function Specializations</title>

    <synopsis>SYNTAX:
**guard**:: //annotation//
{
  //functions-list//
}</synopsis>

    <itemizedlist>
      <listitem>
        <para><emphasis>annotation</emphasis> Guard expressed by
        annotation</para>
      </listitem>

      <listitem>
        <para><emphasis>functions-list</emphasis> one or more function that
        share the same guard</para>
      </listitem>
    </itemizedlist>

    <para>Xreate allows several functions called
    <emphasis>specializations</emphasis> to share the same name. This is
    syntactic foundation for <emphasis>function level polymorphism</emphasis>
    i.e. ability for compiler to decide which exactly function is called out
    of several options. Resolution can happen during compilation or at
    run-time.</para>

    <para>Functions with the same name i.e. different specializations should
    have unique identifiers called <emphasis>guards</emphasis>. When function
    is actually called it's expected that resolution is already done at some
    point before and supplies correct guard to uniquely specify which exactly
    specialization to call.</para>

    <para>Example:</para>

    <programlisting xml:id="FunctionSpecialization1">guard::                              safe_enviroment 
{
  sum = function (a::int, b::int) :: int 
  {
      a + b
  }
}</programlisting>

    <note>
      <para>See <link
      xlink:href="/w/transcend/ast-api#function-s-specializatio">API</link> to
      get more information on how guards are processed</para>
    </note>
  </section>

  <section>
    <title>Branch Statements</title>

    <section>
      <title>IF Statement</title>

      <synopsis>SYNTAX:
**if** (//condition//):: //type// [; //annotations// ]..
  //block-true//
    **else**
  //block-false//</synopsis>

      <para>IF statement executes <emphasis>block-true</emphasis> or
      <emphasis>block-false</emphasis> depending on
      <emphasis>condition</emphasis> evaluation result.</para>

      <para>Example:</para>

      <programlisting xml:id="IfStatement1">answer = if (question == "Favorite color?"):: string
  {"Yellow"} else {"Don't know"}.</programlisting>
    </section>

    <section>
      <title>SWITCH Statement</title>

      <synopsis>SYNTAX:
**switch** ( //condition// ) :: //type// [; //annotations//]..
[**case** ( //guard// ) code-block]..
**case default** //default-code-block//
</synopsis>

      <itemizedlist>
        <listitem>
          <para><emphasis>condition</emphasis>'s result is used to decide
          which branch to execute next</para>
        </listitem>

        <listitem>
          <para><emphasis>guard</emphasis> value to match against
          <emphasis>condition</emphasis></para>
        </listitem>

        <listitem>
          <para><emphasis>default-code-block</emphasis> executed if no
          appropriate case found</para>
        </listitem>
      </itemizedlist>

      <para>SWITCH statement evaluation's result is that of branch whose
      <emphasis>guard</emphasis> matches
      <emphasis>condition</emphasis>.</para>

      <para>Example:</para>

      <programlisting xml:id="SwitchStatement1">monthName = switch(monthNum) :: string
    case (1) {"Jan"}
    case (2) {"Feb"}
    case default {"Strange.. Don't know this month"}.</programlisting>
    </section>
  </section>

  <section>
    <title>Loop Statements</title>

    <section>
      <title>LOOP Statement</title>

      <synopsis>SYNTAX:

**loop** ( //init-value// -&gt; //accumulator// ):: //type// [; //annotations//] //loop-body//</synopsis>

      <itemizedlist>
        <listitem>
          <para><emphasis>init-value</emphasis> initial value loop starts
          from</para>
        </listitem>

        <listitem>
          <para><emphasis>accumulator</emphasis> identifier which holds loop's
          result after each iteration</para>
        </listitem>
      </itemizedlist>

      <para>For each iteration <emphasis>accumulator</emphasis> assumes result
      of previous iteration or <emphasis>init-value</emphasis> during first
      iteration. Result of the <emphasis>loop-body</emphasis> evaluation is
      used as <emphasis>accumulator</emphasis>'s next iteration value and as
      overall loop statement result after the last iteration.</para>

      <para>This notation does not have termination condition. Compiler relies
      on loop body fixed point in order to decide when to interrupt loop.
      Let's consider example:</para>

      <programlisting xml:id="LoopStatement1">COUNTEREXAMPLE
//infinite loop
answer = loop (2-&gt;x) :: int
{
  if(IsPerfect(x)):: int {x} else {x+1}
}.</programlisting>

      <para>The example tests numbers for being perfect(sum of all proper
      divisors equals to the number itself). While iterating accumulator
      <code>x</code> assumes values as follows: 2, 3, 4, 5, 6, 6 ... After it
      founds first perfect number any further iteration do not change result
      anymore since there is no increment and it continues to test the same
      number again and again. Obviously, <code>x=6</code> is a fixed point in
      this example. There is no point to continue going through further
      iterations once fixed point is evaluated and hence loop can be safely
      interrupted.</para>

      <para>Compiler relies on manually provided annotations to recognize when
      fixed point is reached. There is special annotation <code>final</code>
      to specify fixed point for loops. Once expression marked as
      <code>final</code> gets evaluated it's assumed to be fixed point or in
      other words compiler knows it's the very last iteration after which loop
      ends. Correct code for the example above is:</para>

      <programlisting xml:id="LoopStatement2">//loop exits after first perfect number is found
answer2 = loop (2-&gt;x) :: int
{
  if(IsPerfect(x))::int {x:: int; final} else {x+1}
}.</programlisting>

      <para>In this case compiler able to recognize when fixed point is
      reached to exit loop. After loops is done <code>answer</code> is
      <code>6</code>.</para>
    </section>

    <section>
      <title>LOOP FOLD Statement</title>

      <synopsis>SYNTAX:

**loop fold** (//list// **-&gt;** //element//:: //type// [; //annotations//], //init-value// **-&gt;** //accumulator//):: //type// [; //annotations//]
  //loop-body//</synopsis>

      <itemizedlist>
        <listitem>
          <para><emphasis>list</emphasis> to iterate through</para>
        </listitem>

        <listitem>
          <para><emphasis>element</emphasis> identifier that assumes value of
          currently processed list element</para>
        </listitem>

        <listitem>
          <para><emphasis>type</emphasis>, <emphasis>annotations</emphasis>
          expression types and optional annotations delimited by
          semicolon</para>
        </listitem>

        <listitem>
          <para><emphasis>init-value</emphasis> accumulator's initial value
          loop starts with</para>
        </listitem>

        <listitem>
          <para><emphasis>accumulator</emphasis> identifier assumes loop-body
          evaluation result after each iteration</para>
        </listitem>
      </itemizedlist>

      <para>Iterates over <emphasis>list</emphasis> in order to accumulate
      result by applying <emphasis>loop-body</emphasis> transformation to each
      <emphasis>element</emphasis> and intermediate
      <emphasis>accumulator</emphasis>. Overall loop value is a accumulator's
      value after the last iteration. If fixed point is found an execution
      terminates earlier.</para>

      <para>Example shows code excerpt that looks for a minimal element in the
      given list(and less then initial value <code>10</code>).</para>

      <programlisting xml:id="FoldStatement1">numbers = {4, 8, 7, 1, 5}::                  [int].
min = loop fold(numbers-&gt;x:: int, 10-&gt;acc):: int
{
  if (acc &gt; x):: int {x} else {acc}
}.</programlisting>
    </section>

    <section>
      <title>LOOP MAP Statement</title>

      <synopsis>SYNTAX:

**loop map** ( //list// **-&gt;** //element// :: //type// [; //annotations// ] ) :: //type// [;  //annotations// ]
  //loop-body//</synopsis>

      <itemizedlist>
        <listitem>
          <para><emphasis>list</emphasis> to iterate through</para>
        </listitem>

        <listitem>
          <para><emphasis>element</emphasis> identifier that assumes value of
          currently processed list element</para>
        </listitem>

        <listitem>
          <para><emphasis>type</emphasis>, <emphasis>annotations</emphasis>
          type and optional annotations delimited by semicolon.</para>
        </listitem>

        <listitem>
          <para><emphasis>loop-body</emphasis></para>
        </listitem>
      </itemizedlist>

      <para>Iterates over input <emphasis>list</emphasis> and applies
      <emphasis>loop-body</emphasis> transformation to each element. Result is
      a list that consists of all transformed elements.</para>

      <programlisting xml:id="MapStatement1">odd_numbers = {1, 3, 5}:: [int].
even_numbers = loop map(odd_numbers-&gt;number::int) :: [int]
    { 2 * number }.</programlisting>

      <para>Example demonstrates creating <code>even_number</code> list by
      multiplying by 2 every element of <code>odd_numbers</code>.</para>
    </section>
  </section>

  <section>
    <title>Types</title>

    <para>Primitive Types</para>

    <informaltable>
      <tgroup cols="2">
        <colspec colwidth="173*"/>

        <colspec colwidth="827*"/>

        <tbody>
          <row>
            <entry><code>num</code></entry>

            <entry><code>i32</code> alias. Reserved for auto detected most
            appropriate either integral of floating-point number type</entry>
          </row>

          <row>
            <entry><code>int</code></entry>

            <entry><code>i32</code> alias. Reserved for auto detected most
            appropriate integral number type</entry>
          </row>

          <row>
            <entry><code>float</code></entry>

            <entry>Double precision floating-point number</entry>
          </row>

          <row>
            <entry><code>bool</code></entry>

            <entry>Boolean type</entry>
          </row>

          <row>
            <entry><code>i8, i32, i64</code></entry>

            <entry>Signed integers. 8, 32, 64 bit wide respectively</entry>
          </row>

          <row>
            <entry><code>string</code></entry>

            <entry>Pointer to a null terminated ANSI char string. Reserved for
            auto detected most appropriate string type.</entry>
          </row>

          <row>
            <entry><code>*</code></entry>

            <entry>Unspecified type. Example <code>x = {amount=200,
            currency="USD"}::*.</code></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>Compound types:</para>

    <informaltable>
      <tgroup cols="2">
        <colspec colwidth="312*"/>

        <colspec colwidth="688*"/>

        <tbody>
          <row>
            <entry><code>[ <emphasis>element-type</emphasis> ]</code></entry>

            <entry>List of elements of the same type
            <emphasis>element-type</emphasis>. Example: <code>[int]</code> -
            list of <code>int</code>'s</entry>
          </row>

          <row>
            <entry><code>{<emphasis>key</emphasis>::
            <emphasis>type</emphasis>, ...}</code></entry>

            <entry>List of elements of different type possibly with named
            keys. Examples: <code>{int, string}</code>, <code>{name::string,
            age::int}</code></entry>
          </row>

          <row>
            <entry><code>variant {<emphasis>option</emphasis> ::
            (<emphasis>type</emphasis>, ...}, ...}</code></entry>

            <entry>Holds a single element of type of one out of number of
            options. Examples: <code>variant {FullAddress:: {string, string,
            string}, ShortAddress:: {string}}</code></entry>
          </row>

          <row>
            <entry><code>slave <emphasis>identifier</emphasis></code></entry>

            <entry>Type determined by Transcend. Example: <code>slave
            unit_test</code></entry>
          </row>

          <row>
            <entry><code><emphasis>compound-type</emphasis> [
            <emphasis>key</emphasis> ]</code></entry>

            <entry>Accessing elements of compound type. Example: <code>Bio =
            type {birth_year:: int, name:: string}. Year = type
            Bio[birth_year].</code></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>New types defined as:</para>

    <synopsis>SYNTAX:

//type-name// = **type** (//parameters//...) //type-definition// .</synopsis>

    <para>Example:</para>

    <programlisting xml:id="Types1">Tuple = type {string, int}.
Int = type Tuple[1]. //accessing by index</programlisting>
  </section>

  <section>
    <title>Variants and SWITCH VARIANT Instruction</title>

    <synopsis>SYNTAX:

**switch variant** ( //condition//  [-&gt; //alias// ] [:: //type// [; //annotations//... ] ] ) :: type [; annotations... ]
[ **case** ( //guard// ) //case-branch// ]...</synopsis>

    <itemizedlist>
      <listitem>
        <para><emphasis>condition</emphasis> expression of variant type</para>
      </listitem>

      <listitem>
        <para><emphasis>alias</emphasis> identifier to denote unwrapped
        content of condition withing case branches.</para>
      </listitem>

      <listitem>
        <para><emphasis>guard</emphasis> name of variant to match against
        actual condition's variant</para>
      </listitem>

      <listitem>
        <para><emphasis>case-branch</emphasis> block of code to execute in
        case of matched variant. Content is accessible by using alias Within
        the branch .</para>
      </listitem>
    </itemizedlist>

    <para>Sometimes it is useful for a variable to have value of different
    types depending on some conditions, in other words it has
    <emphasis>variant type</emphasis>.</para>

    <para>Let's consider example with variable <emphasis>month</emphasis> of
    variant type <emphasis>Month</emphasis>:</para>

    <programlisting xml:id="Variants1">Month = type variant {
  MonName  :: {string}, 
  MonNumber:: {int}
}.

test = function:: Month
{
  month = MonName("April"):: Month.
  month
}</programlisting>

    <para>Variable <code>month</code> holds value of either
    <code>string</code> or <code>int</code> type. Value is not accessible
    directly. It should be <emphasis>unwrapped</emphasis> before using. Xreate
    supports <code>switch variant</code> instruction for this
    operation.</para>

    <para>As an example below is <code>nextMonth</code> function
    definition:</para>

    <programlisting>nextMonth = funcrtion(month:: Month):: Month 
{
  switch variant(month):: Month 
  case (MonName) 
    {
      //
    }
  case (MonNumber)
  
}</programlisting>
  </section>
</chapter>
