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

<!-- ====================================================================== -->
<!-- = chapter-1.xml                                                      = -->
<!-- = afnix reference manual - 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="2" number="1">
  <title>Reserved keywords</title>

  <p>
  This chapter contains a summary of the <afnix/> reserved keywords
  with their syntax. 
  </p>

  <!-- =================================================================== -->
  <!-- = assert reserved keyword                                         = -->
  <!-- =================================================================== -->

  <keyword>
    <name>assert</name>
  
    <p>
    The <code>assert</code> reserved keyword check for equality
    between two operands. Both objects must be of the same type. If
    the equality test fails, the reserved keyword print a message and
    abort the execution. By default, the assertion checking is turned
    off. The interpreter option <option>-f assert</option> enables the
    assertion checking. When the interpreter is compiled in debug
    mode, the assertion checking is turned on by default.
    </p>

    <syntax>
    assert <em>"form 1" "form 2"</em>
    </syntax>
  
    <example>
    assert true (== 1 1)
    assert 3    (+  2 1)
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = block reserved keyword                                          = -->
  <!-- =================================================================== -->

  <keyword>
    <name>block</name>

    <p>
    The <code>block</code> reserved keyword defines a new nameset for
    sequential execution of regular form or implicit form. When the
    block form is evaluated, the block nameset is linked to its parent
    nameset. When all forms have been executed, the block nameset is
    destroyed and the result of the last evaluation in the block is
    considered to be the result of the block evaluation. 
    </p>

    <syntax>
    block <em>"regular form"</em><nl/>
    block <em>"block form"</em>
    </syntax>

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

  <!-- =================================================================== -->
  <!-- = class reserved keyword                                          = -->
  <!-- =================================================================== -->

  <keyword>
    <name>class</name>

    <p>
    The <code>class</code> reserved keyword creates a new class
    object. Without argument, an instance of that class is created without
    data members. With a list of arguments, the instance is created with
    a set of data member initialized to nil.
    </p>

    <syntax>
    class<nl/>
    class <em>"data member-list"</em>
    </syntax>

    <example>
    const Color (class)
    trans Color:initialize (red green blue) {
      const this:red   red
      const this:green green
      const this:blue  blue
    }
    const red   (Color 255   0   0)
    const green (Color   0 255   0)
    const blue  (Color   0   0 255)
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = const reserved keyword                                          = -->
  <!-- =================================================================== -->

  <keyword>
    <name>const</name>

    <p>
    The <code>const</code> reserved keyword binds a symbol with an
    object and marks it as a constant symbol. When used with three or
    four argument, a gamma expression is automatically
    created. <code>const</code> can also be used to bind class or
    instance members.
    </p>

    <syntax>
    const symbol <em>"object"</em><nl/>
    const symbol <em>"argument" "body"</em><nl/>
    const symbol <em>"argument" "closed variables" "body"</em>
    </syntax>

    <example>
    const number 123
    const max (x y) (if (> x y) x y)
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = daemon reserved keyword                                         = -->
  <!-- =================================================================== -->

  <keyword>
    <name>daemon</name>

    <p>
    The <code>daemon</code> reserved keyword creates a new thread by
    executing the form argument in a daemon thread. The created thread
    is executed by creating a clone of the interpreter and starting
    immediately the execution of the form with the cloned
    interpreter. The command returns the thread object in the calling
    thread. When the thread terminates, the thread object holds the
    result of the last executed form. The main thread does not wait for
    a daemon thread to terminate.
    </p>

    <syntax>
    daemon <em>"form"</em>
    </syntax>

    <example>
    daemon (println "hello world")
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = delay reserved keyword                                          = -->
  <!-- =================================================================== -->

  <keyword>
    <name>delay</name>

    <p>
    The <code>delay</code> reserved keyword delays the evaluation of the
    form argument by creating a <code>Promise</code> object. The promise
    evaluate to itself until a call to force the evaluation has been
    made. When the promise has been forced, the evaluation result is
    stored. Further call to force will produce the same result.
    </p>

    <syntax>
    delay <em>"form"</em>
    </syntax>

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

  <!-- =================================================================== -->
  <!-- = do reserved keyword                                             = -->
  <!-- =================================================================== -->

  <keyword>
    <name>do</name>

    <p>
    The <code>do</code> reserved keyword is used to build loop with
    forward condition. The loop construct accepts either 2 or 3
    arguments. With 2 argument, the first argument is the loop body and
    the second argument is the loop condition which must evaluates to a
    boolean object. With 3 arguments, the first argument is the initial
    condition that is executed only once.
    </p>

    <syntax>
    do <em>"body" "condition"</em><nl/>
    do <em>"initial" "body" "condition"</em>
    </syntax>

    <example>
    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>
  </keyword>

  <!-- =================================================================== -->
  <!-- = enum reserved keyword                                           = -->
  <!-- =================================================================== -->

  <keyword>
    <name>enum</name>

    <p>
    The <code>enum</code> reserved keyword creates an enumeration from a
    list of literal. The result object is an <code>Enum</code> object
    that holds the enumerated items. An item evaluation results with an
    <code>Item</code> object that is bound to the enumeration object.
    </p>
  
    <syntax>
    enum <em>"literal" ...</em>
    </syntax>

    <example>
    const e (enum E1 E2 E3)
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = errorln reserved keyword                                        = -->
  <!-- =================================================================== -->

  <keyword>
    <name>errorln</name>

    <p>
    The <code>errorln</code> reserved keyword prints on the interpreter
    error stream a set of arguments. Each arguments have to be a literal
    which are converted to a string. When all arguments have been
    printed a new line character is printed. The <code>error</code>
    reserved keyword behaves like <code>errorln</code> excepts that a
    new line character is not printed at the end of the arguments.
    </p>

    <syntax>
    errorln<nl/>
    errorln <em>"nil"</em><nl/>
    errorln <em>"literal list"</em>
    </syntax>

    <example>
    errorln
    errorln "hello millennium" ' ' 2000
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = errorln reserved keyword                                        = -->
  <!-- =================================================================== -->

  <keyword>
    <name>eval</name>

    <p>
    The <code>eval</code> reserved keyword simply evaluates the object
    argument. The form is useful when returning an argument from a
    lambda or gamma expression using an implicit form.
    </p>

    <syntax>
    eval <em>"object"</em>
    </syntax>

    <example>
    const ret (x) (eval x)
    eval (protect (+ 1 2))
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = for reserved keyword                                            = -->
  <!-- =================================================================== -->

  <keyword>
    <name>for</name>

    <p>
    The <code>for</code> reserved keyword provides a facility to iterate
    on <em>iterable objects</em>. The <code>Cons</code>,
    <code>List</code> and <code>Vector</code> objects are typical
    iterable objects. For each iterable objects, a symbol is set after
    each iteration. Each object symbol value can be used for further
    computation. The iteration stops when one of the objects iterator is
    at the end position.
    </p>

    <syntax>
    for <em>"symbol list" "iterable object list" "body"</em>
    </syntax>

    <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>
  </keyword>

  <!-- =================================================================== -->
  <!-- = force reserved keyword                                          = -->
  <!-- =================================================================== -->

  <keyword>
    <name>force</name>

    <p>
    The <code>force</code> reserved keyword forces the evaluation of its
    argument. If the argument evaluates to a <em>promise object</em>,
    the promise evaluation is forced. If the argument is not a promise,
    <code>force</code> keyword behaves like <code>eval</code>. When a
    promise has been forced, further call to force will not change the
    evaluation result.
    </p>

    <syntax>
    force <em>"object"</em>
    </syntax>

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

  <!-- =================================================================== -->
  <!-- = if reserved keyword                                             = -->
  <!-- =================================================================== -->

  <keyword>
    <name>if</name>

    <p>
    The <code>if</code> reserved keyword executes a form based on the
    evaluation of a boolean expression. In its first representation,
    <code>if</code> executes a form if the condition is evaluated to
    true. An alternate form can be specified and is executed if the
    boolean expression evaluates to false. It is an error to use a
    conditional form which does not evaluate to a boolean object.
    </p>

    <syntax>
    if <em>"condition" "true form"</em><nl/>
    if <em>"condition" "true form" "else form"</em>
    </syntax>

    <example>
    const max (x y) (if (> x y) x y)
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = lambda reserved keyword                                         = -->
  <!-- =================================================================== -->

  <keyword>
    <name>lambda</name>

    <p>
    The <code>lambda</code> reserved keyword creates a new <em>closure</em>
    object with eventually a set of arguments and a set of closed
    variables. In its first form, the closure is declared with a set of
    arguments or nil to indicate no argument. In its second form, the
    closure is declared with a set of arguments and a set of closed
    variables. The closed variables are evaluated at the construction of
    the closure and become part of the closure object. When the closure
    is called, a new nameset is created and linked with the parent
    nameset. The set of calling arguments are bounded in that nameset
    with  the formal argument list to become the actual arguments. The
    set of closed variables is linked at runtime to the closure
    nameset. A lambda or gamma expression can have its argument declared
    as <code>const</code> argument.
    </p>

    <syntax>
    lambda <em>"nil" "body"</em><nl/>
    lambda <em>"argument list" "body"</em><nl/>
    lambda <em>"argument list" "closed variables list" "body"</em>
    </syntax>

    <example>
    const no-args (lambda nil (+ 1 1))
    const add     (lambda ((const x) (const y)) (+ x y))
    const closed  (lambda (x) (y) (+ x y))
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = launch reserved keyword                                         = -->
  <!-- =================================================================== -->

  <keyword>
    <name>launch</name>

    <p>
    The <code>launch</code> reserved keyword creates a new thread
    by executing the form argument in a normal thread. The created
    thread is added in the normal thread list by creating a clone of the
    interpreter and starting immediately the execution of the form with
    the cloned interpreter. The command returns the thread object in the
    calling thread. When the thread terminates, the thread object holds
    the result of the last executed form. The main thread is suspended
    until all normal threads have completed their execution.
    </p>

    <syntax>
    launch <em>"form"</em>
    </syntax>

    <example>
    launch (println "hello world")
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = loop reserved keyword                                           = -->
  <!-- =================================================================== -->

  <keyword>
    <name>loop</name>

    <p>
    The <code>loop</code> reserved keyword executes a loop based on
    an initial condition, an exit condition and a step form. The initial
    condition is only executed one time. The exit condition is tested at
    each loop iteration. The <code>loop</code> reserved keyword creates
    its own nameset since the initial condition generally binds symbol
    locally for the loop.
    </p>

    <syntax>
    loop <em>"init form" "exit form" "step" "form"</em>
    </syntax>

    <example>
    loop (trans i 0) (&lt; i 10) (i:++) (println i)
    </example>
  </keyword>
    
  <!-- =================================================================== -->
  <!-- = nameset reserved keyword                                        = -->
  <!-- =================================================================== -->

  <keyword>
    <name>nameset</name>

    <p>
    The <code>nameset</code> reserved keyword creates a new
    nameset. With no argument, a new nameset is created and no parent is
    binded to this nameset. With one argument, the argument must evaluate
    to a nameset and that nameset is used as the parent one. If a nameset
    has to be created with the global nameset as the parent, the symbol
    <code>...</code> can be used to reference the top level nameset. The
    symbol <code>.</code> references the current nameset. The symbol
    <code>..</code> references the parent nameset of the current
    nameset.
    </p>

    <syntax>
    nameset<nl/>
    nameset <em>"parent nameset"</em>
    </syntax>

    <example>
    const local-nameset-not-bound (nameset)
    const local-nameset-bounded   (nameset ...)
    const ...:global-nameset      (nameset)
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = println reserved keyword                                        = -->
  <!-- =================================================================== -->

  <keyword>
    <name>println</name>

    <p>
    The <code>println</code> reserved keyword prints on the interpreter
    output stream a set of arguments. Each arguments have to be a
    literal which is converted to a string. When all arguments have been
    printed a new line character is printed. The <code>print</code>
    reserved keyword behaves like <code>println</code> excepts that a
    new line character is not printed at the end of the arguments.
    </p>

    <syntax>
    println<nl/>
    println <em>"nil"</em><nl/>
    println <em>"literal list"</em>
    </syntax>

    <example>
    println
    println "hello millennium" ' ' 2000
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = protect reserved keyword                                        = -->
  <!-- =================================================================== -->

  <keyword>
    <name>protect</name>

    <p>
    The <code>protect</code> reserved keyword take a single argument and
    returns it without evaluation. Protect is mainly use to get a symbol
    or form object.
    </p>

    <syntax>
    protect <em>"object"</em>
    </syntax>

    <example>
    const cons (protect (+ 1 2))
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = return reserved keyword                                         = -->
  <!-- =================================================================== -->

  <keyword>
    <name>return</name>

    <p>
    The <code>return</code> reserved keyword causes the current
    expression to stop its evaluation and returns the argument or
    nil. The <code>return</code> keyword is primarily used in lambda or
    gamma expressions. If used in a top level block, the block execution
    is stopped and the control is transferred to the top level.
    </p>

    <syntax>
    return <em>"object"</em>
    </syntax>

    <example>
    return (+ 1 2)
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = sync reserved keyword                                           = -->
  <!-- =================================================================== -->

  <keyword>
    <name>sync</name>

    <p>
    The <code>sync</code> reserved keyword is a form synchronizer. 
    Within a multi-threaded environment, the <afnix/> engine guarantees
    that only one thread will execute the form. The other threads are
    suspended until the form has been completed.
    </p>

    <syntax>
    sync <em>"form"</em>
    </syntax>

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

  <!-- =================================================================== -->
  <!-- = switch reserved keyword                                         = -->
  <!-- =================================================================== -->

  <keyword>
    <name>switch</name>

    <p>
    The <code>switch</code> reserved keyword is a form selector. The
    first argument is the object to switch. The second argument is a
    list of forms with an object matcher and an execution form. The
    <code>else</code> reserved keyword can be used as default matcher.
    </p>

    <syntax>
    switch <em>"selector" "list of conditions"</em>
    </syntax>

    <example>
    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>
  </keyword>

  <!-- =================================================================== -->
  <!-- = throw reserved keyword                                          = -->
  <!-- =================================================================== -->

  <keyword>
    <name>throw</name>

    <p>
    The <code>throw</code> reserved keyword throws an exception. Without
    argument, an exception of type <em>user-exception</em> is
    thrown. with one argument, the <em>exception id</em> is set. With
    two arguments, the <em>exception id</em> and <em>exception
    reason</em> are set. With three arguments, the <em>exception
    id</em>, <em>exception reason</em> and <em>exception object</em> are
    set.
    </p>

    <syntax>
    throw<nl/>
    throw <em>"exception id"</em><nl/>
    throw <em>"exception id" "exception reason"</em><nl/>
    throw <em>"exception id" "exception reason" "exception object"</em>
    </syntax>

    <example>
    throw              
    throw "type-error" 
    throw "type-error" "invalid argument"
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = trans reserved keyword                                          = -->
  <!-- =================================================================== -->

  <keyword>
    <name>trans</name>

    <p>
    The <code>trans</code> reserved keyword creates or sets a symbol
    with an object. <code>trans</code> searches in the current nameset
    only. If a symbol is found, it is set with the object. If the symbol
    is not found, it is created in the current nameset. The
    <code>trans</code> keyword can also be used with qualified
    names. With 3 or 4 arguments, <code>trans</code> creates
    automatically a lambda expression.
    </p>

    <syntax>
    trans symbol <em>"object"</em><nl/>
    trans symbol <em>"argument" "body"</em><nl/>
    trans symbol <em>"argument" "closed variables" "body"</em>
    </syntax>

    <example>
    trans a 1
    trans fact (n) (if (&lt; n 1) 1 (* n (fact (- n 1))))
    </example>
  </keyword>

  <!-- =================================================================== -->
  <!-- = try reserved keyword                                            = -->
  <!-- =================================================================== -->

  <!-- try reserved keyword -->
  <keyword>
    <name>try</name>

    <p>
    The <code>try</code> reserved keyword catch an exception in the
    current execution nameset. The first argument is a form to
    execute. The optional second argument is the <em>exception
    handler</em> to be called in case of exception. If there is no
    exception handler, all exceptions are caught. The result of
    execution is either the result of the form execution, or the
    exception object in case of exception, or nil if the exception is a
    native one. If there is an exception handler, the handler is
    executed with a new nameset and the special symbol <code>what</code>
    is   bound to the exception. If the exception is nil, the symbol
    <code>what</code> is undefined.
    </p>

    <syntax>
    try <em>"form"</em><nl/>
    try <em>"form" " exception handler"</em>
    </syntax>

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

  <!-- while reserved keyword -->
  <keyword>
    <name>while</name>

    <p>
    The <code>while</code> reserved keyword is used to build loop with
    backward condition. The loop construct accepts either 2 or 3
    arguments. With 2 argument, the first argument is the loop condition
    and the second argument is the loop body that must evaluate to a
    boolean. With 3 arguments, the first argument is the initial
    condition that is executed only once.
    </p>

    <syntax>
    while <em>"condition" "body"</em><nl/>
    while <em>"initial" "condition" "body"</em>
    </syntax>

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