<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = chapter-1.xml                                                      = -->
<!-- = afnix programmer's guide chapter 1                                 = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter volume="1" number="1">
  <title>Getting started</title>

  <p>
  This chapter is a quick introduction to the <afnix/> Programming
  Language, simply called <afnix/>. The chapter provides a general
  description of the language in the form of a guided tour. The
  remaining of the book contains chapter that are dedicated to
  specific language features.
  </p>

  <!-- first program -->
  <section>
    <title>First programs</title>
    
    <p>
    The fundamental <afnix/> syntactic object is a <em>form</em>. A form is
    parsed and immediately executed by the <afnix/> engine. A form is
    generally constructed with a function name and a set of
    arguments. The process of executing a form is called the
    <em>evaluation</em>. As a simple program, the traditional
    <command>"hello world"</command> program is shown below. 
    </p>

    <!-- hello world example -->
    <subsect>
      <title>Hello world</title>

      <p>
      The <command>"hello world"</command> program is <em>de
      rigueur</em> when introducing a new programming language. Here
      is the <afnix/> version of it.
      </p>

      <example>
      afnix&gt; println "hello world"
      </example>

      <p>
      <afnix/> is an interpreted language. It is possible to invoke the 
      interpreter and enter the above commands, or use a text editor
      and execute the file. By convention, an <afnix/> source 
      file has the extension <extn>.als</extn>. A simple session to
      run the above program -- assuming the source file is called
      <file>hello.als</file> -- is shown below. 
      </p>

      <example>
      zsh&gt; axi hello.als
      hello world
      </example>

      <p>
      It is also possible to invoke the interpreter as to enter the
      commands interactively. The result will be the same. Simply
      typing <command>ctrl-d</command> will exit the session. Another
      way to operate is to call the <afnix/> compiler called
      <product>axc</product>, and then invoke the interpreter with
      the compiled file, even let the interpreter to figure this
      out. Note that the interpreter assume the <extn>.axc</extn> for
      compiled file.
      </p>

      <example>
      zsh&gt; axc hello.als
      zsh&gt; axi hello.axc
      hello world
      zsh&gt; axi hello
      hello world
      </example>

      <p>
      The order of search is determined by a special system called the
      <em>file resolver</em>. Its behavior is described in a special
      chapter of this manual.
      </p>
    </subsect>

    <!-- inetrpreter commands -->
    <subsect>
      <title>Interpreter command</title>

      <p>
      The <afnix/> interpreter can be invoked with several options, a
      file to execute and some program arguments. The
      <option>-h</option> option prints the various interpreter options.
      </p>

      <example>
      zsh&gt; axi -h
      usage: axi [options] [file] [arguments]
             [-h]         print this help message
             [-v]         print version information
             [-i] path    add a path to the resolver
             [-f] assert  enable assertion checking
             [-f] nopath  do not set initial path
      </example>

      <p>
      The <option>-v</option> option prints the interpreter version
      and operating system. The <option>-f</option> option turn on or
      off some additional options like assertion checking. The program
      arguments are illustrated later in this chapter. The
      <option>-i</option> option add a path to the interpreter 
      file path resolver. Several <option>-i</option> options can be
      specified. The order of search is determined by the option
      order. The use of the resolver combined with the
      <em>librarian</em> is described in a specific chapter. If the
      initial file name to execute contains a directory path, such
      path is added automatically to the interpreter resolver path
      unless the <option>nopath</option> option is specified.
      </p>
    </subsect>

    <!-- interactive line editing -->
    <subsect>
      <title>Interactive line editing</title>

      <p>
      Line editing capabilities are supported when the interpreter is used
      interactively. Error messages are displayed in red if the terminal
      supports colors. The following table is a resume of the default key
      bindings.
      </p>

      <table>
       <title>Interactive line editing key bindings</title>

       <thead>
        <tr>
	  <td>Binding</td><td>Description</td>
        </tr>
       </thead>
       <tbody>
	<tr><td>backspace</td><td>Erase the previous character</td></tr>
	<tr><td>delete</td>   <td>Erase at the cursor position</td></tr>
	<tr><td>insert</td>   <td>Toggle insert with in-place</td></tr>
	<tr><td>left</td>     <td>Move the cursor to the left</td></tr>
	<tr><td>right</td>    <td>Move the cursor to the right</td></tr>
	<tr><td>up</td>       <td>Move up in the history list</td></tr>
	<tr><td>down</td>     <td>Move down in the history list</td></tr>
	<tr><td>ctrl-a</td>   <td>Move to the beginning of the line</td></tr>
	<tr><td>ctrl-e</td>   <td>Move to the end of the line</td></tr>
	<tr><td>ctrl-u</td>   <td>Clear the input line</td></tr>
	<tr><td>ctrl-k</td>   <td>Clear from the cursor position</td></tr>
	<tr><td>ctrl-l</td>   <td>Refresh the line editing</td></tr>
       </tbody>
      </table>
    </subsect>

    <!-- command line arguments -->
    <subsect>
      <title>Command line arguments</title>

      <p>
      The command line arguments to the interpreter are stored in a vector
      called <code>argv</code> which is part of the
      <code>interp</code> class. A complete discussion about class
      data member is covered in the <em>class object chapter</em>. The
      example below which illustrates the use of the vector argument.
      </p>
      
      <example>
      # argv.als
      # print the argument length and the first one
      println "argument length: " (interp:argv:length)
      println "first argument : " (interp:argv:get 0)
      
      zsh&gt; axi argv.als hello world
      2
      hello
      </example>
    </subsect>

    <!-- loading a source file -->
    <subsect>
      <title>Loading a source file</title>
    
      <p>
      The interpreter class provides also the <code>load</code>
      method to load a source file. The argument must be a valid file
      path or an exception is raised. The <code>load</code> method
      returns <code>nil</code>. When the file is loaded, the interpreter
      input, output and error streams are used. The load operation read
      one form after another and executes them sequentially.
      </p>

      <example>
      # load the source file fred.als
      afnix&gt; interp:load "fred.als"
      </example>

      <p>
      If the file has been compiled, the <extn>axc</extn> extension
      can be used instead. This force the interpreter to load the
      compiled version. If you are not sure, or do not care about
      which file is loaded, the extension can be omitted.
      </p>
      
      <example>
      # load the compiled file fred.axc
      afnix&gt; interp:load "fred.axc"
      # load whatever is found
      afnix&gt; interp:load "fred"
      </example>

      <p>
      Without extension, the compiled file is searched first. If it is not
      found the source file is searched and loaded.
      </p>
    </subsect>

    <!-- compiler -->
    <subsect>
      <title>The compiler</title>
      
      <p>
      The client <command>axc</command> is the <em>cross
      compiler</em>. It generates a binary file that can be run across
      platforms. The <option>-h</option> option prints the various
      compiler options. 
      </p>

      <example>
      usage: axc [options] [files]
                 [-h]      print this help message
                 [-v]      print version information
                 [-i] path add a path to the resolver
      </example>

      <p>
      One or several files can be specified on the command line. The source
      file can be searched by the resolver by using the
      <option>-i</option> option.
      </p>
    </subsect>

    <!-- builtin objects -->
    <subsect>
      <title>builtin objects</title>

      <p>
      <afnix/> provides several builtin objects, namely <code>Boolean</code>,
      <code>Integer</code>, <code>Real</code>, <code>Character</code>
      and <code>String</code>. A builtin object can be constructed
      literally for each of these types. The best way to build such
      object is to bind it to a <em>symbol</em>. The <code>const</code>
      and <code>trans</code> reserved keywords are used to declare a
      new symbol. A symbol is simply a binding between a name and an
      object. Almost any standard characters can be used to declare a
      symbol.
      </p>

      <example>
      const boolean   true
      const integer   1999
      const real      2000.0
      const string    "afnix"
      const char      'a'
      </example>

      <p>
      None of the symbols -- or names -- used in the program above are
      reserved keywords. In fact, the capitalize names are builtin
      objects such like Integer or String. The <code>const</code>
      reserved keyword creates a <em>constant symbol</em> and returns
      the last evaluated object. As a consequence, nested
      <code>const</code> constructs are possible like 
      <code>trans b (const a 1)</code>. The <code>trans</code>
      reserved keyword declare a new non-constant symbol. That is, the
      symbol can be changed. Note that it is the symbol which is
      marked constant, not the object.
      </p>

      <example>
      trans a-symbol "hello world"
      trans a-symbol 2000
      println a-symbol
      </example>
    </subsect>
      
    <!-- comments -->
    <subsect>
      <title>Comments</title>

      <p>
      Comments starts with the character <code>#</code>. All
      characters until the end of line are consumed. Comments can be
      placed anywhere in the source file. Comments entered during an
      interactive session are discarded.
      </p>
    </subsect>

    <!-- forms -->
    <subsect>
      <title>Forms</title>

      <p>
      The previous program was an illustration of the simplest form
      declaration, referred as <em>implicit form</em>. An implicit
      form is a single line command. When a command is becoming
      complex, the use of the standard form notation is more
      readable. The standard form uses the <code>(</code> and
      <code>)</code> characters to start and close a form. The
      previous programs could have been written with the standard form
      notation instead of the implicit one. The use of standard form
      notation versus the implicit is one is a matter of style and
      readability.
      </p>

      <p>
      A form causes an <em>evaluation</em>. When a form is evaluated,
      each symbol in the form are evaluated to their corresponding
      internal object. Then the interpreter treats the first object of
      the form as the object to execute and the rest is the argument
      list for the calling object. The use of form inside a form is
      the standard way to perform recursive evaluation for complex
      expression.
      </p>

      <example>
      const three (+ 1 2)
      </example>

      <p>
      The previous program defines a symbol which is initialized with
      the integer 3, that is the result of the computation <code>(+ 1
      2)</code>. The program shows also that Polish notation is used
      for arithmetic. If fact, <code>+</code> is a builtin operator
      which causes the arguments to be summed (if possible).

      Evaluation can be nested as well as definition and assignation. When a
      form is evaluated, the result of the evaluation is made available to
      the calling form. If the result is obtained at the top level, that
      result is discarded.
      </p>

      <example>
      const    b (trans a (+ 1 2))
      assert a 3
      assert b 3
      trans  a 4
      assert b 3
      </example>

      <p>
      This program illustrates the mechanic of the evaluation
      process. The evaluation is done recursively. The <code>(+ 1
      2)</code> form is evaluated as 3 and the result transmitted to
      the form <code>(trans a 3)</code>. This form not only creates
      the symbol <code>a</code> and binds to it the integer 3, but
      returns also 3 which is the result of the previous
      evaluation. Finally, the form <code>(const b 3)</code> is
      evaluated, that is, the symbol <code>b</code> is created and the
      result discarded. Internally, things are a little more complex,
      but the idea remains the same. This program illustrates also the
      usage of the <code>assert</code> keyword.
      </p>
    </subsect>
  </section>

  <!-- lambda expression -->
  <section>
    <title>Lambda expression</title>

    <p>
    A <em>lambda expression</em> is a function in the <afnix/>
    terminology. The term come historically from Lisp to express the
    fact that a lambda expression is analog to the concept of
    expression found in the lambda calculus. There are various ways to 
    create a lambda expression. A lambda expression is created with
    the <code>trans</code> reserved keywords. A lambda expression
    takes 0 or more arguments and return an object. A lambda
    expression is also an object by itself. When a lambda expression
    is called, the arguments are evaluated from left to right and
    placed on the interpreter <em>eval stack</em>. The function is
    then called and the object result is transmitted to the calling
    form. The use of <code>trans</code> vs <code>const</code> is
    explain later. As an example, we define the factorial of an
    integer in a recursive way.
    </p>
    
    <example>
    # declare the factorial function
    trans fact (n) (
      if (== n 1) 1 (* n (fact (- n 1))))
    
    # compute factorial 5
    println "factorial 5 = " (fact 5)
    </example>

    <p>
    This program calls for several comments. First the
    <code>trans</code> keyword defines a new function object with one
    argument called <code>n</code>. The body of the function is
    defined with the <code>if</code> reserved keyword and can be
    easily understood. The function is called in the next form when
    the <code>println</code> reserved keyword is executed. Note that
    here, the call to <code>fact</code> produces an integer object,
    which is converted automatically by the <code>println</code>
    keyword.
    </p>

    <!-- block form -->
    <subsect>
      <title>Block form</title>
      
      <p>
      The notation used in the <code>fact</code> program is the
      standard form notation originating from Lisp and the Scheme
      dialect. <afnix/> offers another notation called the <em>block
      form</em> notation with the use of the <code>{</code> and
      <code>}</code> characters. A block form is a syntactic notation
      where each form in the block form is executed sequentially. The
      form can be either an implicit or a regular form. The
      <code>fact</code> procedure can be rewritten with the block
      notation as illustrated below.
      </p>

      <example>
      # declare the factorial procedure
      trans fact (n) {
        if (== n 1) 1 (* n (fact (- n 1)))
      }
      
      # compute factorial 5
      println "factorial 5 = " (fact 5)
      </example>

      <p>
      Another way to create a lambda expression is via the reserved keyword
      <code>lambda</code>. Recall that a lambda expression is an
      object. So when such object is created, it can be bounded to a
      symbol. The factorial example could be rewritten with an
      explicit lambda call.
      </p>

      <example>
      # declare the factorial procedure
      const fact (lambda (n) (
        if (== n 1) 1 (* n (fact (- n 1))))
      
      # compute factorial 5
      println "factorial 5 = " (fact 5)
      </example>

      <p>
      Note that here, the symbol <code>fact</code> is a constant
      symbol. The use of <code>const</code> is rather reserved for
      <em>gamma expression</em>. 
      </p>
    </subsect>

    <!-- gamma expression -->
    <subsect>
      <title>Gamma expression</title>

      <p>
      A lambda expression can somehow becomes very slow during the
      execution, since the symbol evaluation is done within a set of
      nested call to resolve the symbols. In other words, each
      recursive call to a function creates a new symbol set which is
      linked with its parent. When the recursion is becoming deep, so
      is the path to traverse from the lower set to the top one. Afnix
      provides another mechanism called <em>gamma expression</em>
      which binds only the function symbol set to the top level
      one. The rest remains the same. Using a gamma expression can
      speedup significantly the execution.
      </p>

      <example>
      # declare the factorial procedure
      const fact (n) (
        if (== n 1) 1 (* n (fact (- n 1))))
      
      # compute factorial 5
      println "factorial 5 = " (fact 5)
      </example>

      <p>
      We will come back later to the concept of gamma expression. The
      use of the reserved keyword <code>const</code> to declare 
      a gamma expression makes now sense. Since most function
      definitions are constant with one level, it was a language choice to
      implement this syntactic sugar. Note that <code>gamma</code> is
      a reserved keyword and can be used to create a gamma expression
      object. On the other hand, note that the gamma expression
      mechanism does not work for instance method. We will illustrate
      this point later in this book.
      </p>
    </subsect>

    <!-- lambda generation -->
    <subsect>
      <title>Lambda generation</title>
      
      <p>
      A lambda expression can be used to generate another lambda
      expression. In other word, a function can generate a function,
      hence the term that <afnix/> is a <em>functional
      programming</em> language. Suppose one might want to write a
      function which take an argument and generate a function which
      add this argument to the generated function argument -- got
      that! --, then here is the implementation. 
      </p>

      <example>
      # a gamma which creates a lambda
      const gen (n)(
        lambda (x) (n) (+ x n))
      
      # create a function which add 2 to its argument
      const add-2 (gen 2)
      
      # call add-2 with an argument and check
      println "result = " (add-2 3)
      </example>

      <p>
      The interesting part in the previous program is the concept of
      closed variables. Looking at the lambda expression inside
      <code>gen</code>, notice that the argument to the gamma is
      <code>x</code> while <code>n</code> is marked in a form before
      the body of the gamma. This notation indicates that the gamma
      should retain the value of the argument <code>n</code> when the
      closure is created. In the literature, you might discover a
      similar mechanism referenced as a <em>closure</em>. A closure is
      simply a variable which is closed under a certain context. When
      a variable is reference in a context without any definition,
      such variable is called a <em>free variable</em>. We will 
      see later more programs with closures. Note that in the <afnix/>
      terminology, it is the object created by the gamma call which is
      called a closure. Note also that the same mechanism apply with
      lambda.

      In short, a lambda expression is a function with or without
      closed variables, which works with nested symbol sets also
      called <em>namesets</em>. A gamma expression is a function with
      or without closed variable which is bounded to the top level
      nameset. The reserved keyword <code>trans</code> binds a lambda
      expression. The reserved keyword <code>const</code> binds a
      gamma expression. A gamma expression cannot be used as an
      instance method.
      </p>
    </subsect>

    <!-- multiple argument binding -->
    <subsect>
      <title>Multiple arguments binding</title>

      <p>
      A lambda or gamma expression can be defined to work with extra
      arguments using the special <code>args</code> binding. During a
      lambda or gamma expression execution, the special symbol
      <code>args</code> is defined with the extra arguments passed at
      the call. For example, a gamma expression with 0 formal argument
      and 2 actual arguments has <code>args</code> defined as a <em>cons
      cell</em>.
      </p>
      
      <example>
      const proc-nilp (args) {
        trans result 0
	for (i) (args) (result:+= i)
	eval result
      }
      assert 3 (proc-nilp 1 2)
      assert 7 (proc-nilp 1 2 4)
      </example>

      <p>
      The symbol <code>args</code> can also be defined with formal
      arguments. In that case, <code>args</code> is defined as a cons
      cell with the remaining actual arguments.
      </p>

      <example>
      # check with arguments
      const proc-args (a b args) {
        trans result (+ a b)
	for (i) (args) (result:+= i)
        eval result
      }
      assert 3 (proc-args 1 2)
      assert 7 (proc-args 1 2 4)
      </example>
      
      <p>
      It is an error to specify formal arguments after
      <code>args</code>. Multiple <code>args</code> formal definition
      are not allowed. The symbol <code>args</code> can also be
      defined as a constant argument.
      </p>

      <example>
      # check with arguments
      const proc-args (a b (const args)) {
        trans result (+ a b)
	for (i) (args) (result:+= i)
	eval result
      }
      assert 7 (proc-args 1 2 4)
      </example>
    </subsect>
  </section>

  <!-- nameset and bindings -->
  <section>
    <title>Nameset and bindings</title>

    <p>
    A <em>nameset</em> is a container of bindings between a name and
    <em>symbolic variable</em>. We use the term <em>symbolic variable</em>
    to denote any binding between a name and an object. There are
    various ways to express such bindings. The common one in <afnix/>
    is called a symbol. Another type of binding is an
    argument. Despite the fact they are different, they share a set of
    common properties, like being settable. Another point to note is
    the nature of the nameset. As a matter of fact, <afnix/> has various
    type of namesets. The top level nameset is called a <em>global
    set</em> and is designed to handle a large number of symbols. In a
    lambda or gamma expression, the nameset is called a <em>local
    set</em> and is designed to be fast with a small number of
    symbols. The moral of this little story is to think always 
    in terms of namesets, no matter how it is implemented. All
    namesets support the concept of parent binding. When a nameset is
    created (typically during the execution of a lambda expression),
    this nameset is linked with its parent one. This means that a
    symbol lookup is done by traversing all nameset from the bottom to
    the top and stopping when one is found. In term of <afnix/>
    notation, the <em>current nameset</em> is referenced with the
    special symbol <code>.</code>. The <em> parent nameset</em> is
    referenced with the special symbol <code>..</code>. The <em>top
    level nameset</em> is referenced with the symbol <code>...</code>.
    </p>

    <!-- symbol -->
    <subsect>
      <title>Symbol</title>

      <p>
      A symbol is an object which defines a binding between a name and
      an object. When a symbol is evaluated, the evaluation process
      consists in returning the associated object. There are various
      ways to create or set a symbol, and the different reserved
      keywords account for the various nature of binding which has to
      be done depending on the current nameset state. One of the
      symbol property is to be <code>const</code> or not. When a
      symbol is marked as a constant, it cannot be modified. Note here
      that it is the symbol which is constant, not the object. A
      symbol can be created with the reserved keywords <code>const</code>
      or <code>trans</code>. 
      </p>
    </subsect>

    <!-- creating a nameset -->
    <subsect>
      <title>Creating a nameset</title>
      
      <p>
      A nameset is an object which can be constructed directly by using the
      object construction notation. Once the object is created, it can be
      bounded to a symbol. Here is a nameset called <code>example</code> in the
      top level nameset.
      </p>

      <example>
      # create a new nameset called example
      const example (nameset .)

      # bind a symbol in this nameset
      const example:hello "hello"
      println example:hello
      </example>
    </subsect>

    <!-- qualified name -->
    <subsect>
      <title>Qualified name</title>

      <p>
      In the previous example, a symbol is referenced in a given
      nameset by using a <em>qualified name</em> like
      <code>example:hello</code>. A qualified name define a path to
      access a symbol. The use of qualified name is a powerful
      notation to reference an object in reference to another
      object. For example, the qualified name <code>.:hello</code>
      refers to the symbol <code>hello</code> in the current nameset. The
      qualified name <code>...:hello</code> refers to the symbol 
      <code>hello</code> in the top level nameset. There are other use
      for qualified names, like method call with an instance.
      </p>
    </subsect>

    <!-- symbol binding -->
    <subsect>
      <title>Symbol binding</title>

      <p>
      The <code>trans</code> reserved keyword has been shown in all
      previous example. The reserved keyword <code>trans</code>
      creates or set a symbol in the current nameset. For example, the
      form <code>trans a 1</code> is evaluated as follow. First, a
      symbol named <code>a</code> is searched in the current
      nameset. At this stage, two situations can occur. If the symbol
      is found, it is set with the corresponding value. If the symbol
      is not found, it is created in the current nameset and set. The
      use of qualified name is also permitted -- and encouraged --
      with <code>trans</code>. The exact nature of the symbol binding
      with a qualified name depends on the partial evaluation of the
      qualified name. For example, <code>trans example:hello 1</code>
      will set or create a symbol binding in reference to the
      <code>example</code> object. If <code>example</code> refers to a
      nameset, the symbol is bound in this nameset. If
      <code>example</code> is a class, <code>hello</code> is bounded as a 
      static symbol for that class. In theory, there is no restriction
      to use <code>trans</code> on any object. If the object does not
      have a symbol binding capability, an exception is raised. For
      example, if <code>n</code> is an integer object, the form
      <code>trans n:i 1</code> will fail. 

      With 3 or 4 arguments, <code>trans</code> defines automatically
      a lambda expression. This notation is a syntactic sugar. The
      lambda expression is constructed from the argument list and
      bounded to the specified symbol. The rule used to set or define
      the symbol are the same as described above.
      </p>

      <example>
      # create automatically a lambda expression
      trans min (x y) (if (&lt; x y) x y)
      </example>
    </subsect>

    <!-- constant binding -->
    <subsect>
      <title>Constant binding</title>

      <p>
      The <code>const</code> reserved keyword is similar to
      <code>trans</code>, except that it creates a <em>constant
      symbol</em>. Once the symbol is created, it cannot be
      changed. This constant property is hold by the symbol
      itself. When trying to set a constant symbol, an exception is
      raised. The reserved keyword <code>const</code> works also with
      qualified  names. The rules described previously are the
      same. When a partial evaluation is done, the partial object is
      called to perform a constant binding. If such capability does
      not exist, an exception is raised.

      With 3 or 4 arguments, <code>const</code> defines automatically
      a gamma expression. Like <code>trans</code> the rule are the
      same except that the symbol is marked constant.
      </p>

      <example>
      # create automatically a gamma expression
      const max (x y) (if (> x y) x y)
      </example>
    </subsect>

    <!-- arguments -->
    <subsect>
      <title>Arguments</title>

      <p>
      An expression argument is similar to a symbol, except that it is
      used only with function argument. The concept of binding between
      a name and an object is still the same, but with an argument,
      the object is not stored as part of the argument, but rather at
      another location which is the execution stack. An argument can
      also be constant. On the other hand, a single argument can have
      multiple bindings. Such situation is found during the same
      function call in two different threads. An argument list is part
      of the lambda or gamma expression declaration. If the argument
      is defined as a constant argument a sub form notation is used to
      defined this matter. For example, the <code>max</code> gamma
      expression is given below.
      </p>

      <example>
      # create a gamma expression with const argument
      const max (gamma ((const x) (const y)) (if (> x y) x y))
      </example>

      <p>
      A special symbols named <code>args</code> is defined during a
      lambda or gamma expression evaluation with the remaining
      arguments passed at the time the call is made. The symbol can be
      either <code>nil</code> or bound to a list of objects.
      </p>

      <example>
      const proc-args (a b) {
        trans result (+ a b)
	for (i) (args) (result:+= i)
	eval result
      }
      assert 3 (proc-args 1 2)
      assert 7 (proc-args 1 2 4)
      </example>
    </subsect>
  </section>

  <!-- control flow -->
  <section>
    <title>Control flow</title>

    <p>
    <afnix/> provides various reserved keywords which can be seen as
    standard <em>imperative statements</em>. Such statements are
    useful to write readable programs but are not necessary the best
    in terms of efficiency. In most cases, a statement returns the
    last evaluated object. Most of the statements are control flow
    statements.
    </p>

    <!-- if statement -->
    <subsect>
      <title>If statement</title>

      <p>
      The <code>if</code> reserved keyword takes two or three
      arguments. The first argument is the boolean condition to
      check. If the condition evaluates to <code>true</code> the
      second argument is evaluated. The form return the result of such
      evaluation. If the condition evaluates to <code>false</code>,
      the third argument is evaluated or nil is returned if it does
      not exist. An interesting example which combines the
      <code>if</code> reserved keyword and a deep recursion is the
      computation of the Fibonacci sequence.
      </p>

      <example>
      const fibo (gamma (n) (
        if (&lt; n 2) n (+ (fibo (- n 1)) (fibo (- n 2))))
      </example>
    </subsect>

    <!-- while statement -->
    <subsect>
      <title>While statement</title>

      <p>
      The <code>while</code> reserved keyword takes 2 or 3
      arguments. With 2 arguments, the loop is constructed with a
      condition and a form. With 3 arguments, the first argument is an
      initial condition that is executed only once. When an argument
      acts as a loop condition, the condition evaluate to a
      boolean. The loop body is executed as long as the boolean
      condition is true. An interesting example related to 
      integer arithmetic with a <code>while</code> loop is the
      computation of the greatest common divisor or gcd.
      </p>

      <example>
      const gcd (u v) {
        while (!= v 0) {
          trans r (u:mod v)
          u:= v
          v:= r
        }
        eval u
      }
      </example>

      <p>
      Note in this previous example the use of the symbol
      <code>=</code>. The qualified name <code>u:=</code> is in fact a
      method call. Here, the integer <code>u</code> is assigned with a
      value. In this case, the symbol is not changed. It is the object
      which is muted.

      In the presence of 3 arguments, the first argument is an
      initialization condition that is executed only once. In this
      mode, it is important to note that the loop introduce its own
      nameset. The loop condition can be used to initialize a local
      condition variable.
      </p>

      <example>
      while (trans valid (is:valid-p)) (valid) {
        # do something
        # adjust condition
        valid:= (and (is:valid-p) (something-else))
      }
      </example>
    </subsect>

    <!-- do statement -->
    <subsect>
      <title>Do statement</title>

      <p>
      The <code>do</code> reserved keyword is similar to the
      <code>while</code> reserved keyword, except that the loop
      condition is evaluated after the body execution. The syntax call
      is opposite to the <code>while</code>. The loop can accept
      either 2 or 3 arguments. With 2 arguments, the first argument is
      the loop body and the second argument is the exit loop
      condition. With 3 arguments, the first argument is the initial
      condition that is executed only once.
      </p>

      <example>
      # count the number of digits in a string
      const number-of-digits (s) {
        const len (s:length)
        trans index 0
        trans count 0
        do {
          trans c (s:get index)
          if (c:digit-p) (count:++)
        } (&lt; (index:++) len)
        eval count
      }
      </example>
    </subsect>

    <!-- loop statement -->
    <subsect>
      <title>Loop statement</title>

      <p>
      The <code>loop</code> reserved keyword is another form of
      loop. It take four arguments. The first is the initialize
      form. The second is the exit condition. The third is the step
      form and the fourth is the form to execute at each loop
      step. Unlike the <code>while</code> and <code>do</code> loop,
      the <code>loop</code> statement creates its own nameset, since
      the initialize condition generally creates new symbol for the
      loop only.
      </p>

      <example>
      # a simple loop from 0 to 10
      loop (trans i 0) (&lt; i 10) (i:++) (println i)
      </example>
    </subsect>

    <!-- switch statement -->
    <subsect>
      <title>Switch statement</title>

      <p>
      The <code>switch</code> reserved keyword is a condition
      selector. The first argument is the switch selector. The second
      argument is a list of various value which can be matched by the
      switch value. A special symbol called <code>else</code> can be
      used to match any value.
      </p>

      <example>
      # return the primary color in a rgb
      const get-primary-color (color value) (
        switch color (
          ("red"   (return (value:substr 0 2))
          ("green" (return (value:substr 2 4))
          ("blue"  (return (value:substr 4 6))
        )
      )
      </example>
    </subsect>

    <!-- return statement -->
    <subsect>
      <title>Return statement</title>

      <p>
      The <code>return</code> reserved keyword indicates an
      exceptional condition in the flow of execution within a lambda
      or gamma expression. When a return is executed, the associated
      argument is returned and the execution terminates. If
      <code>return</code> is used at the top level, the result is
      simply discarded.
      </p>

      <example>
      # initialize a vector with a value
      const vector-init (length value) {
        # treat nil vector first
	if (&lt;= length 0) return (Vector)
	trans result (Vector)
	do (result:add value) (&gt; (length:--) 0)
      }
      </example>
    </subsect>

    <!-- eval and protect -->
    <subsect>
      <title>Eval and protect</title>

      <p>
      The <code>eval</code> reserved keyword forces the evaluation of
      the object argument. The reserved keyword <code>eval</code> is
      typically used in a function body to return a particular symbol
      value. It can also be used to force the evaluation of a
      <em>protected object</em>. In many cases, <code>eval</code> is
      more efficient than <code>return</code>. The
      <code>protect</code> reserved keyword constructs an object
      without evaluating it. Typically when used with a form,
      <code>protect</code> return the form itself. It can also be used
      to prevent a symbol evaluation. When used with a symbol, the
      symbol object itself is returned.
      </p>

      <example>
      const add (protect (+ 1 2))
      (eval add)
      </example>
      
      <p>
      Note that in the preceding example that the evaluation will
      return a lambda expression which is evaluated immediately and
      which return the integer 3.
      </p>
    </subsect>

    <!-- assert statement -->
    <subsect>
      <title>Assert statement</title>

      <p>
      The <code>assert</code> reserved keyword check for equality
      between the two arguments and abort the execution in case of
      failure. By default, the assertion checking is turn off, and can
      be activated with the command option <option>-f
      assert</option>. Needless to say that <code>assert</code> is
      used for debugging purpose.
      </p>

      <example>
      assert true   (> 2 0)
      assert 0      (- 2 2)
      assert "true" (String true)
      </example>
    </subsect>

    <!-- block statement -->
    <subsect>
      <title>Block statement</title>

      <p>
      The <code>block</code> reserved keyword executes a form in a new
      local set. The local set is destroyed at the completion of the
      execution. The <code>block</code> reserved keyword returns the
      value of the last evaluated form. Since a new local set is
      created, any new symbol created in this nameset is destroyed at
      the completion of the execution. In other word, the
      <code>block</code> reserved keyword allows the creation of a
      local scope.
      </p>

      <example>
      trans a 1
      block {
        assert    a 1
	trans     a (+ 1 1)
	assert    a 2
	assert ..:a 1
      }
      assert 1 a
      </example>
    </subsect>
  </section>

  <!-- builtin objects -->
  <section>
    <title>builtin objects</title>

    <p>
    <afnix/> provides several builtin objects and builtin operators for
    arithmetic and logical operations. The <code>Integer</code> and
    <code>Real</code> classes are primarily used to manipulate
    numbers. The <code>Boolean</code> class is used to for boolean
    operations. Other builtin objects include <code>Character</code>
    and <code>String</code>. The exact usage of these classes is
    described in the next chapter.
    </p>

    <!-- arithmetic operations -->
    <subsect>
      <title>Arithmetic operations</title>

      <p>
      <afnix/> provides various ways to perform arithmetic
      operations. Most of the operations are done with the
      <code>+</code>, <code>-</code>, <code>*</code> and <code>/</code>
      operators. Each of these operators works with both integer and
      real numbers.
      </p>

      <example>
      (+ 1 2)
      (- 1)
      (* 3 5.0)
      (/ 4.0 2)
      </example>
    </subsect>

    <!-- logical operations -->
    <subsect>
      <title>Logical operations</title>

      <p>
      The <code>Boolean</code> class is used to represent the boolean
      value <code>true</code> and <code>false</code>. These last two
      symbols are builtin in the interpreter as constant
      symbols. <afnix/> provides also some reserved keywords like
      <code>not</code>, <code>and</code> and <code>or</code>. Their 
      usage is self understandable.
      </p>

      <example>
      not true
      and true (== 1 0)
      or (&lt; -1 0) (&gt; 1 0)
      </example>
    </subsect>

    <!-- predicates -->
    <subsect>
      <title>Predicates</title>

      <p>
      A <em>predicate</em> is a function which returns a boolean
      object. <afnix/> provides several predicates to check for some
      builtin objects. By convention, a predicate terminates with the
      sequence <em>-p</em>. The <code>nil-p</code> predicate is a
      special predicate which returns true if the object is
      nil. <afnix/> provides a predicate for each builtin objects.
      </p>

      <table>
       <title>builtin predicates</title>

       <thead>
        <tr>
	  <td>Predicate</td><td>Description</td>
        </tr>
       </thead>
       <tbody>
        <tr><td>nil-p</td>       <td>check nil object</td></tr>
        <tr><td>eval-p</td>      <td>check evaluation</td></tr>
	<tr><td>real-p</td>      <td>check real object</td></tr>
	<tr><td>regex-p</td>     <td>check regex object</td></tr>
	<tr><td>string-p</td>    <td>check string object</td></tr>
	<tr><td>number-p</td>    <td>check number object</td></tr>
	<tr><td>boolean-p</td>   <td>check boolean object</td></tr>
	<tr><td>integer-p</td>   <td>check integer object</td></tr>
	<tr><td>character-p</td> <td>check character object</td></tr>
       </tbody>
      </table>

      <p>
      For example, one can write a function which returns
      <code>true</code> if the argument is a number, that is, an integer
      or a real number.
      </p>

      <example>
      # return true if the argument is a number
      const number-p (n) (
        or (integer-p n) (real-p n))
      </example>

      <p>
      Predicates for functional and symbolic programming are also
      builtin into the <afnix/> engine.
      </p>

      <table>
       <title>Special predicates</title>

       <thead>
        <tr>
	  <td>Predicate</td><td>Description</td>
        </tr>
       </thead>
       <tbody>
        <tr><td>class-p</td>     <td>check class object</td></tr>
	<tr><td>thread-p</td>    <td>check thread object</td></tr>
	<tr><td>promise-p</td>   <td>check promise object</td></tr>
	<tr><td>lexical-p</td>   <td>check lexical object</td></tr>
	<tr><td>literal-p</td>   <td>check literal object</td></tr>
	<tr><td>closure-p</td>   <td>check closure object</td></tr>
	<tr><td>nameset-p</td>   <td>check nameset object</td></tr>
	<tr><td>instance-p</td>  <td>check instance object</td></tr>
	<tr><td>qualified-p</td> <td>check qualified object</td></tr>
       </tbody>
      </table>
      
      <p>
      Finally, for each object, a predicate is also associated. For
      example, <code>cons-p</code> is the predicate for the
      <code>Cons</code> object.
      </p>

      <table>
       <title>Object predicates</title>

       <thead>
        <tr>
	  <td>Predicate</td><td>Description</td>
        </tr>
       </thead>
       <tbody>
        <tr><td>cons-p</td>   <td>check a cons object</td></tr>
	<tr><td>list-p</td>   <td>check for a list object</td></tr>
	<tr><td>queue-p</td>  <td>check a queue object</td></tr>
	<tr><td>bitset-p</td> <td>check a bitset object</td></tr>
	<tr><td>vector-p</td> <td>check a vector object</td></tr>
       </tbody>
      </table>

      <p>
      Another issue related to evaluation, is to decide whether or
      not an object can be evaluated. The
      predicate <code>eval-p</code> which is a special form is
      designed to answer this question. Furthermore, the
      <code>eval-p</code> predicate is useful to decide whether or not
      a symbol is defined or if a qualified name can be evaluated.
      </p>

      <example>
      assert true  (eval-p .)
      assert false (eval-p an-unknown-symbol)
      </example>
    </subsect>
  </section>

  <!-- classes and instances -->
  <section>
    <title>Class and Instance</title>

    <p>
    <afnix/> provides support for the object oriented programming
    paradigm. A <em>class</em> in the <afnix/> terminology is a nameset
    which can be bounded automatically when an <em>instance</em> of that
    class is created. Compared to other language, there is no need to
    declare the data member for a particular class. Data members are
    created during the instance construction. A class allows an instance
    to call function with the instance nameset visible for that
    function.
    </p>

    <!-- class and members -->
    <subsect>
      <title>Class and members</title>

      <p>
      A class is declared with the reserved keyword
      <code>class</code>. The class acts like a nameset. Functions can
      be bounded to this class.
      </p>

      <example>
      const Color (class)
      const Color:BLACK "#000000"
      const Color:WHITE "#FFFFFF"
      </example>

      <p>
      Any object can be bounded as a data member, including lambda
      expressions.
      </p>

      <example>
      const Color (class)
      const Color:get-primary-from-string (color value) {
        trans val "0x"
	val:+= (switch color (
          ("red"   (value:substr 1 3))
          ("green" (value:substr 3 5))
          ("blue"  (value:substr 5 7))
        )
	Integer val
      }
      </example>
    </subsect>

    <!-- instances -->
    <subsect>
      <title>Instances</title>

      <p>
      An instance of a class is created like any builtin object. If a
      method called <code>preset</code> is defined for that class,
      the method is used as an initializer  of that instance.
      </p>

      <example>
      const Color (class)
      trans Color:preset (red green blue) {
        const this:red   (Integer red)
	const this:green (Integer green)
	const this:blue  (Integer blue)
      }
      const red   (Color 255   0   0)
      const green (Color   0 255   0)
      const blue  (Color   0   0 255)
      </example>
    </subsect>

    <!-- instance method -->
    <subsect>
      <title>Instance method</title>

      <p>
      When a lambda expression is bound to the class or the instance,
      that lambda can be invoked as an instance method.  When an
      instance method is invoked, the instance nameset is set as the
      parent nameset for that lambda. This is the main reason why a
      gamma expression cannot be used as an instance method. The
      instance nameset defines the instance data members and the
      special symbol <code>this</code>. 
      </p>

      <example>
      const int-max (x y) 
        if (> x y) (Integer x) (Integer y))

      const Color:RED-FACTOR   0.75
      const Color:GREEN-FACTOR 0.75
      const Color:BLUE-FACTOR  0.75
      trans Color:get-darker nil {
        trans red   (int-max (this:red:*   Color:RED-FACTOR)   0)
        trans green (int-max (this:green:* Color:GREEN-FACTOR) 0)
	trans red   (int-max (this:blue:*  Color:BLUE-FACTOR)  0)
	Color red green blue
      }
      # get a darker color than red
      const dark-red (red:get-darker)
      </example>
    </subsect>
  </section>

  <!-- miscellaneous features -->
  <section>
    <title>Miscellaneous features</title>

    <p>
    <afnix/> provides several facilities for control flow and
    exceptional operations. Most of these features are available via
    the use of reserved keywords.
    </p>

    <!-- iteration -->
    <subsect>
      <title>Iteration</title>

      <p>
      An iteration facility is provided for some objects known as
      <em>iterable objects</em>. The <code>Cons</code>,
      <code>List</code> and <code>Vector</code> are typical iterable
      objects. There are two ways to iterate with these objects. The
      first method uses the <code>for</code> reserved keyword. The
      second method uses an explicit iterator which can be constructed
      by the object.
      </p>

      <example>
      # compute the scalar product of two vectors
      const scalar-product (u v) {
        trans result 0
	for (x y) (u v) (result:+= (* x y))
	eval result
      }
      </example>

      <p>
      The <code>for</code> reserved keyword iterate on both object
      <code>u</code> and <code>v</code>. For each iteration, the
      symbol <code>x</code> and <code>y</code> are set with their
      respective object value. In the example above, the result is
      obtained by summing all intermediate products.
      </p>

      <example>
      # test the scalar product function
      const v1 (Vector 1 2 3)
      const v2 (Vector 2 4 6)
      (scalar-product v1 v2)
      </example>

      <p>
      The iteration can be done explicitly by creating an iterator for each
      vectors and advancing steps by steps.
      </p>

      <example>
      # scalar product with explicit iterators
      const scalar-product (u v) {
        trans result 0
	trans u-it   (u:get-iterator)
	trans v-it   (v:get-iterator)
	while (u:valid-p) {
	  trans x (u:get-object)
          trans y (v:get-object)
          result:+= (* x y)
          u:next
          v:next
        }
        eval result
      }
      </example>

      <p>
      In the example above, two iterators are constructed for both vectors
      <code>u</code> and <code>v</code>. The iteration is done in a
      <code>while</code> loop by invoking the <code>valid-p</code>
      predicate. The <code>get-object</code> method returns the object
      value at the current iterator position.
      </p>
    </subsect>

    <!-- exception -->
    <subsect>
      <title>Exception</title>

      <p>
      An <em>exception</em> is an unexpected change in the execution
      flow. The <afnix/> model for exception is based on a mechanism which
      throws the exception to be caught by a handler. The mechanism is also
      designed to be compatible with the native "C++" implementation.

      An exception is thrown with the reserved keyword
      <code>throw</code>. When an exception is thrown, the normal flow
      of execution is interrupted and an object used to carry the
      exception information is created. Such exception object is
      propagated backward in the call stack until an exception handler
      catch it.

      The reserved keyword <code>try</code> executes a form and catch
      an exception if one has been thrown. With one argument, the form
      is executed and the result is the result of the form execution
      unless an exception is caught. If an exception is caught, the
      result is the exception object. If the exception is a native
      one, the result is nil.
      </p>

      <example>
      try (+ 1 2)
      try (throw)
      try (throw "hello")
      try (throw "hello" "world")
      try (throw "hello" "world" "folks")
      </example>

      <p>
      The exception mechanism is also designed to install an exception
      handler and eventually retrieve some information from the exception
      object. The reserved symbol <code>what</code> can be used to
      retrieve some exception information.
      </p>

      <example>
      # protected factorial
      const fact (n) {
        if (not (integer-p n)) (throw "number-error" "invalid argument")
	if (== n 0) 1 (* n (fact (- n 1)))
      }
      # exception handler
      const handler nil {
        errorln what:eid ',' what:reason
      }
      (try (fact 5)       handler)
      (try (fact "hello") handler)
      </example>
    </subsect>

    <!-- delayed evaluation -->
    <subsect>
      <title>Delayed evaluation</title>

      <p>
      The <afnix/> interpreter provides a special mechanism to delay
      an evaluation. The reserved keyword <code>delay</code> creates a
      special object called a <em>promise</em> which records the form
      to be later evaluated. The reserved keyword <code>force</code>
      causes a promise to be evaluated. Subsequent call with
      <code>force</code> will produce the same result.
      </p>

      <example>
      trans   y 3
      const   l ((lambda (x) (+ x y)) 1)
      assert  4 (force l)
      trans   y 0
      assert  4 (force l)
      </example>
    </subsect>

    <!-- regular expressions -->
    <subsect>
      <title>Regular Expressions</title>

      <p>
      The <afnix/> interpreter provides a builtin mechanism for
      regular expression. A <em>regex</em> is an object which is used to
      match certain text patterns. Regular expressions are built implicitly
      by the <afnix/> reader wit the use of the <code>[</code> and
      <code>]</code> characters.
      </p>

      <example>
      if (== (const re [($d$d):($d$d)]) "12:31") {
        trans hr (re:get 0)
	 trans mn (re:get 1)
      }
      </example>

      <p>
      In the previous example, a regular expression object is bound to
      the symbol <code>re</code>. The <code>regex</code> contains two
      groups. The call to the operator <code>==</code> returns
      <code>true</code> if the regex matches the argument string. The
      <code>get</code> method can be used to retrieve the group by index.
      </p>
    </subsect>
  </section>
  
  <!-- threads -->
  <section>  
    <title>Threads</title>

    <p>
    The <afnix/> interpreter provides a powerful mechanism which allows
    the concurrent execution of forms and the synchronization of shared
    objects. There are two types of threads, namely <em>normal
    thread</em> and <em>daemon thread</em>. They differ only by the
    interpreter exit condition. The interpreter will wait until all
    normal threads are completed. On the other hand, the interpreter
    will not wait for daemon threads. They are automatically stopped
    when all normal threads are finished. Normal threads are created
    with the reserved keyword <code>launch</code>, and daemon threads are
    created with the reserved keyword <code>daemon</code>. When threads
    are used, the interpreter manages automatically the shared objects
    and protect them against concurrent access.
    </p>

    <example>
    # shared variable access
    const var 0

    const decr nil (while true (var:= (- var 1)))
    const incr nil (while true (var:= (+ var 1)))
    const prtv nil (while true (println "value = " var))

    # start 3 threads 
    launch (prtv)
    launch (decr)
    launch (incr)
    </example>

    <!-- form synchronization -->
    <subsect>
      <title>Form synchronization</title>

      <p>
      Although, <afnix/> provides an automatic synchronization
      mechanism for reading or writing an object, it is sometimes
      necessary to control the execution flow. There are basically two
      techniques to do so. First, protect a form from being executed
      by several threads. Second, wait for one or several threads to
      complete their task before going to the next execution step. The
      reserved keyword <code>sync</code> can be used to synchronize a
      form. When a form, is synchronized, the <afnix/> engine
      guarantees that only one thread will execute this form.
      </p>

      <example>
      const print-message (code mesg) (
        sync {
          errorln "error  : " code
          errorln "message: " mesg
        }
      )
      </example>

      <p>
      The previous example create a gamma expression which make sure
      that both the error code and error message are printed in one
      group, when several threads call it.
      </p>
    </subsect>

    <!-- thread completion -->
    <subsect>
      <title>Thread completion</title>

      <p>
      The other piece of synchronization is the thread completion
      indicator. The thread descriptor contains a method called
      <code>wait</code> which suspend the calling thread until the
      thread attached to the descriptor has been completed. If the
      thread is already completed, the method returns immediately.
      </p>

      <example>
      # simple flag
      const flag false

      # simple shared tester
      const ftest (val) (flag) (assert val (flag:shared-p))

      # no thread mean not shared
      ftest false

      # in a thread it is shared
      const thr (launch (ftest true))
      thr:wait
      assert true (flag:shared-p)
      </example>

      <p>
      This example is taken from the test suites. It checks that a closed
      variable becomes shared when started in a thread. Note the use
      of the <code>wait</code> method to make sure the thread has
      completed before checking for the shared flag. It is also worth
      to note that <code>wait</code> is one of the method which
      guarantees that a thread result is valid.

      Another use of the <code>wait</code> method can be made with a
      vector of thread descriptors when one wants to wait until all of
      them have completed.
      </p>

      <example>
      # shared vector of threads descriptors
      const thr-group (Vector)

      # wait until all threads in the group are finished
      const wait-all nil (for (thr) (thr-group) (thr:wait))
      </example>
    </subsect>

    <!-- condition variable -->
    <subsect>
      <title>Condition variable</title>

      <p>
      A <em>condition variable</em> is another mechanism to
      synchronize several threads. A condition variable is modeled
      with the <code>Condvar</code> object. At construction, the
      condition variable is initialized to <code>false</code>. A
      thread calling the <code>wait</code> method will block until the
      condition becomes <code>true</code>. The <code>mark</code>
      method can be used by a thread to change the state of a
      condition variable and eventually awake some threads which are
      blocked on it. The use of condition variable is particularly
      recommended when one need to make sure a particular thread has
      been doing a particular task.
      </p>
    </subsect>
  </section>
</chapter>
