predefined.anubis 243 KB

Edit Raw Blame History



                                      The Anubis Project

                                  Predefined types and data.

                           Copyright (c) Alain Prouté 2000-today.
                             Contributions by: Cédric Ricard
                                               Julien Verneuil


   Last revision: Aug 2015.


   $begin

   $section(The primitive types and tools ($fname(predefined.anubis)))


   The  file $fname(predefined.anubis) $em(cannot) be read (using the  keyword $att(read)).
   It was precompiled,
   translated into  the language C, and is  already part of the  compiler.  Compiling this
   file requires  a special  version of the  compiler.  Modifying  this file will  have no
   effect (unless you recompile the Anubis compiler itself, but you do this under your own
   responsability).

   $end

   ---------------------------------- Table of Contents ----------------------------------

   *** (1) Even more primitive stuff.
      *** (1.1) The type 'Empty'.
      *** (1.2) The type 'Bool', 'false' and 'true'.
      *** (1.3) The declaration scheme for boolean equality.

   *** (2) General purpose types.
      *** (2.1) The type 'One', 'unique' and 'forget'.
      *** (2.2) The type scheme 'Maybe($T)', 'failure' and 'success'.
      *** (2.3) The type scheme 'Result($E,$T)', 'error' and 'ok'.
      *** (2.4) The type schemes 'List($T)', '[ ]' and '[ . ]'.
      *** (2.5) The type 'Bit'.
      *** (2.6) The types 'Word4', 'Word8', 'Word16', 'Word32', 'Word64', 'Word128'.
      *** (2.7) The types 'RGB' and 'RGBA'.

   *** (3) Useful parameters and informations
      *** (3.1) Determination of the host system.
      *** (3.2) Version numbers of your Anubis system.
      *** (3.3) Anubis directories (where the system is installed).
      *** (3.4) Getting and setting environment variables.
      *** (3.6) Informations on virtual machines.
      *** (3.7) Informations on the memory allocator.
      *** (3.8) Automatic restarting of 'anbexec'.

   *** (4) Operations on strings, byte arrays, integers and floating point numbers.
      *** (4.1) Strings (type 'String').
      *** (4.2) Byte arrays (type 'ByteArray').
      *** (4.3) True integers (type 'Int').
      *** (4.4) Floating point numbers (type 'Float'). (obsolete in a near future)
      *** (4.5) Floating point numbers (types 'Float32' and 'Float64'). (still under construction)

   *** (5) Files.
      *** (5.1) Opening files.
      *** (5.2) Unix file system interface.
      *** (5.3) Standard files.
      *** (5.4) Getting the size of a file.
      *** (5.5) Weakening file modes.
      *** (5.6) Managing directories.
      *** (5.7) Creating symbolic links.
      *** (5.8) Reading and writing files (and also TCP/IP connections).
      *** (5.9) Removing and renaming files.

   *** (6) Network interface.
      *** (6.1) Connecting to a TCP/IP server. ('connect').
      *** (6.2) Querying IP addresses.
      *** (6.3) Querying a name server ('dns').
      *** (6.4) Creating a TCP/IP network server ('start_server').
      *** (6.5) Creating an UDP client socket ('create_udp_client_socket').
      *** (6.6) Sending and receiving UDP packets.
      *** (6.7) Starting an UDP server ('start_udp_server').
      *** (6.8) Low level sockets.

   *** (7) Miscellaneous tools.
      *** (7.1) Executing an operating system command ('execute').
      *** (7.1) Capturing the output of 'execute'.
      *** (7.2) Random numbers ('random').
      *** (7.3) Dynamic Variables ('Var(T)', 'MVar(T)', 'var', 'mvar' and monitoring).
         *** (7.3.1) Creating, reading and writing.
         *** (7.3.2) Multiple dynamic variables.
         *** (7.3.3) Monitoring.
      *** (7.4) Date and time ('Date_and_Time', 'now', 'convert_time').
      *** (7.5) Other tools (boolean '&', 'append', 'reverse', 'member').
      *** (7.6) Mapping a function to all elements of a list ('map').
      *** (7.7) Reading a password from standard input ('get_password').
      *** (7.8) Loading a .adm module during execution.

   *** (8) Serialization, saving and transmitting data.
      *** (8.1) Serializing and unserializing.
      *** (8.2) Saving and retrieving data ('save' and 'retrieve').
      *** (8.3) Transmitting data.

   *** (9) Built-in cryptography.
      *** (9.1) Secure hash functions ('md5' and 'sha1').
      *** (9.2) Symmetric cryptography ('blowfish_encrypt', 'blowfish_decrypt').
      *** (9.3) SSL ('Secure Sockets Layer').
         *** (9.3.1) SSL connections.
         *** (9.3.2) X.509 Certificates.
         *** (9.3.3) Opening an SSL connection.
         *** (9.3.4) Reading and writing with SSL connections.
         *** (9.3.5) Creating an SSL server.
      *** (9.4) Simple (non cryptographic) hashing.

   *** (10) Images.
      *** (10.1) Types of images.
      *** (10.2) Creating images.
      *** (10.3) Drawing into images.
         *** (10.3.1) Drawing pixels.
         *** (10.3.2) Getting pixels.
         *** (10.3.3) Drawing rectangles.
         *** (10.3.4) Cropping and encrusting, rotating and flipping.
         *** (10.3.5) Drawing system characters.
         *** (10.3.6) System characters and fonts informations.
      *** (10.4) Handling JPEG/JFIF image files.
         *** (10.4.1) Converting to 'HostImage'.
         *** (10.4.2) Converting to 'RGBAImage'.
         *** (10.4.3) Writing (creating) a JPEG file.
         *** (10.4.4) Reading a JPEG file.

   *** (11) Managing the graphic screen.
      *** (11.1) Types for screen, mouse and keyboard handling.
      *** (11.2) Tools.
      *** (11.4) Opening a host window.
      *** (11.5) Queuing an event to a host window.
      *** (11.6) Basic paint functions.

   *** (12) SQLite3 interface.
      *** (12.1) Errors.
      *** (12.2) Opening a data base.
      *** (12.3) Data types.
      *** (12.4) Querying a database.

   *** (13) Fast lexical analysis.
      *** (13.1) Describing a lexer.
      *** (13.2) Compiling a description.

   *** (14) Dynamically linking an external library.
      *** (14.1) Overview.
      *** (14.2) Restrictions.
      *** (14.3) How data are transmitted.
      *** (14.4) Loading the external library.
      *** (14.5) How to call a library function.
      *** (14.6) How to write an extension function.
      *** (14.7) Description of data format.
      *** (14.8) External concrete data housekeeping.

   *** (15) Generic Database interface (dbapi).
      *** (15.1) DB Clients.
      *** (15.1) Errors.
      *** (15.2) Connecting to a data base.
      *** (15.3) Data types.
      *** (15.4) Querying a database.
      *** (15.5) Low level DBAPI Interface (August 2008).

   *** (16) Confining.

   *** (17) Manipulating types and terms as data.
      *** (17.1) Types for describing Anubis types.
      *** (17.2) Types for describing Anubis terms.
      *** (17.3) Quoting and evaluating.
      *** (17.4) Getting the definition of a type or of a term.

   *** (18) Find and replace.
      *** (18.1) Compiled dictionaries.
      *** (18.2) Certifying a dictionary.
      *** (18.3) Changing the array of values.
      *** (18.4) Replacing within a string or a byte array.
      *** (18.5) Replacing by chunks.

   ---------------------------------------------------------------------------------------


   $begin


   $subsection(General purpose types and related tools)

   We define some  types and data of very general use.  They are defined here (and  hence cannot be
   redefined) because the virtual machine itself is dependant on their precise definition.


   $subsubsection(The type $att(Empty))

   The type $att(Empty) is defined as follows:

   $acode(public type Empty:.
   )

      (i.e.  with zero alternative). This type contains no data.


   $subsubsection(The type $att(Bool), $att(false) and $att(true))

   The type $att(Bool) is defined as follows:

   $acode(public type Bool:
   false,
   true.
   )

   The following is a variant of $att(Bool) which is used in particular in B-trees. See below
   comparison functions using this type.

   $acode(
public type Compare:
   before,
   same,
   after.
   )


   $subsubsection(The declaration scheme for boolean equality)


   The scheme for equality is declared as follows:
   $acode(public define Bool $T x = $T y.
   )

   $acode(
public define macro Bool $T x /= $T y = if x = y then false else true.
   )


   $subsubsection(The type $att(One), $att(unique) and $att(forget))

   We need  a type with only  one element. This type  is not $em(empty),  because it contains
   $att(unique).  Nevertheless, $att(unique) does not  carry any information. The $em(bit width) (the
   number of bits on which data are implemented) of this type is 0 (i.e. data of this type
   are represented using 0 bits).
   $acode(
public type One:
  unique.
   )
   In the library,  you will find  many uses of  $att(One) and $att(unique).   The most
   representative example is:
   $acode(
public define inline One forget($T  x).
   )
   Typically, $att(forget) is used for making some side effect and forgeting the returned value. For
   example, you may write:$p

      $center($att(forget(a); b))

   where  $att(a) produces some  side effect,  and returns  a value  that you  don't  want to
   use. Since $att(forget) returns  a datum of type $att(One), the semicolon  is legal.  The whole
   expression returns  the value  of $att(b).   Of course, if  $att(a) is  already of  type $att(One),
   $att(forget) is not useful, and in that case, you can write:$p

         $center($att(a; b))


   $subsubsection(The type scheme $att(Maybe($T)), $att(failure) and $att(success))

   The type scheme $att(Maybe) is widely used by the system. See examples below. $att(Maybe(T)) is
   used instead of $att(T) as a return type whenever the result of an operation is uncertain.
   $acode(
public type Maybe($T):
   failure,
   success($T).
   )


   $subsubsection(The type scheme $att(Result($E,$T)), $att(error) and $att(ok))

   $att(Result) is  similar to $att(Maybe), but  provides a way to describe the problem  that may
   have occured.
   $acode(
public type Result($E,$T):
   error($E),
   ok($T).
   )


    $subsubsection(The type schemes $att(List($T)), $att([ ]) and $att([ . ]))

   $att(List) is a great classic. Remark that the following definition defines also $att([ ]) and
   $att([ . ]) (the empty list and pairs).
   $acode(
public type List($T):
   [ ],                        // the empty list (for type $T)
   [$T . List($T)].            // non empty lists
   )
   Recall that the  Anubis compiler reads (say) $att([a,b,c]) as  $att([a . [b . [c  . []]]]), so that
   you may write lists without too many characters.$p

   For Lisp lovers, it would have been possible to define this type as follows:
   $ecode(
           public type List($T):
              nil,
              cons($T car, List($T) cdr).
   )
   You can still do it, but you will have to choose another name than $att(List) for this type
   scheme (for  example, choose $att(Lisp)). Also  remark that the Lisp  predicates $att(atom) and
   $att(consp)  are useless,  due  to the  syntax  of conditionals.   Unlike  Lisp (and  other
   languages like CAML or Prolog), Anubis can never fail on $att(car) or $att(cdr) (which are also
   useless, since  they do not generate implicit  destructors).  This type is  a very good
   illustration  of  the  advantages  of  the  Anubis concept  of  conditionals  based  on
   alternatives of  types. This concept comes  directly from an analysis  of the universal
   problem defining $em(coproducts) (also called $em(sums)) in Category Theory.$p

   Another convenient variant used by several languages allows to write the list $att([a,b,c,d])
   as:$p

      $center($att(a :: b :: c :: d :: []))

   $acode(
public define macro List($T)    $T h :: List($T) t     = [h . t].
   )


   $subsubsection(The type $att(Bit))

   The type $att(Bit) describes bits, in the same way as $att(Bool) describes booleans.
   $acode(
public type Bit:
   zero,
   one.
   )
   Of course, it is implemented on just one bit by the compiler.


   $subsubsection(The types $att(Word4), $att(Word8), $att(Word16), $att(Word32), $att(Word64), $att(Word128))

   A $em(word) is just an array of bits. Anubis provides several currently used sizes:
   $acode(
public type Word4:      word4     (Bit low, Bit, Bit, Bit high).
public type Word8:      word8     (Word4  low, Word4  high).
public type Word16:     word16    (Word8  low, Word8  high).
public type Word32:     word32    (Word16 low, Word16 high).
public type Word64:     word64    (Word32 low, Word32 high).
public type Word128:    word128   (Word32 low, Word32, Word32, Word32 high).
   )
   Hexadecimal notations  like: $tt(0x567ad5) (including  those prefixed by $att(-),  i.e. negative
   values) written  directly into your source  file, have interpretations as  words of all
   sizes.  Decimal notations  (including negative  numbers) also  have  interpertations as
   words of all sizes.  Of course all values  are reduced modulo the right power of 2: 2$sup(4)
   for $att(Word4), 2$sup(8) for $att(Word8), etc...$p

   Notice that the low order parts are comming first in the components of the above types.
   Nevertheless, the expression $att(word8(0x1,0x2)) has  the same value as $att(0x21). Similarly,
   $att(word16(0x12,0x34))  has  the same  value  as  $att(0x3412).   Indeed, numbers  are  always
   represented internally with the most significant digits first (at the left end).$p

   You  can get  an hexadecimal  representation  of a  word.  This  representation is  not
   prefixed by $att(0x), and the number of  hexadecimal digits depends only on the size of the
   word, not on its value, 1 digit for $att(Word4), 2 digits for $att(Word8), etc... Furthermore, what
   you get is the $em(unsigned) representation.
   $acode(
public define String    to_hexa(Word4 x).      1  digit
public define String    to_hexa(Word8 x).      2  digits
public define String    to_hexa(Word16 x).     4  digits
public define String    to_hexa(Word32 x).     8  digits
public define String    to_hexa(Word64 x).     16 digits
public define String    to_hexa(Word128 x).    32 digits
   )
   For example, $att(to_hexa((Word16)33)) is $att("0021") and $att(to_hexa((Word8)15)) is $att("0f").$p

   Conversion  to  decimal  notation  is  similar,  except  that  it  does  not  pad  with
   zeros. Again, what you get is the $em(unsigned) representation.
   $acode(
public define String    to_decimal(Word4 x).
public define String    to_decimal(Word8 x).
public define String    to_decimal(Word16 x).
public define String    to_decimal(Word32 x).
public define String    to_decimal(Word64 x).
public define String    to_decimal(Word128 x).
   )
   For example $att(to_decimal((Word64)0x1234567890)) is $att("78187493520").$p

   Typical operations on words are left and  right shifts. As in C, bits which are shifted
   out are lost, and bits which are shifted  in are 0. Furthermore, when you use the shift
   operations you must think of your words as being written as ordinary numbers, i.e. with
   the most significant bits  at the left end.  For example $att(x << 1) means $em($att(x) multiplied
   by 2), not $em($att(x) divided by 2).
   $acode(
public define Word4     Word4 x   << Int nb.
public define Word8     Word8 x   << Int nb.
public define Word16    Word16 x  << Int nb.
public define Word32    Word32 x  << Int nb.
public define Word64    Word64 x  << Int nb.
public define Word128   Word128 x << Int nb.
   )
   $acode(
public define Word4     Word4 x   >> Int nb.
public define Word8     Word8 x   >> Int nb.
public define Word16    Word16 x  >> Int nb.
public define Word32    Word32 x  >> Int nb.
public define Word64    Word64 x  >> Int nb.
public define Word128   Word128 x >> Int nb.
   )
   This also works with $att(nb) negative. For example $att(x << -2) is equivalent to $att(x >> 2).$p


   $att(|), $att(:), $att(&)  and $att($~) represent the  bitwise OR, the bitwise XOR,  the bitwise AND
   and the bitwise complement to 1.
   $acode(
public define Word4     Word4 x    | Word4 y.         OR
public define Word8     Word8 x    | Word8 y.
public define Word16    Word16 x   | Word16 y.
public define Word32    Word32 x   | Word32 y.
public define Word64    Word64 x   | Word64 y.
public define Word128   Word128 x  | Word128 y.

public define Word4     Word4 x    : Word4 y.         XOR
public define Word8     Word8 x    : Word8 y.
public define Word16    Word16 x   : Word16 y.
public define Word32    Word32 x   : Word32 y.
public define Word64    Word64 x   : Word64 y.
public define Word128   Word128 x  : Word128 y.

public define Word4     Word4 x    & Word4 y.         AND
public define Word8     Word8 x    & Word8 y.
public define Word16    Word16 x   & Word16 y.
public define Word32    Word32 x   & Word32 y.
public define Word64    Word64 x   & Word64 y.
public define Word128   Word128 x  & Word128 y.
   )
   Note: the $att($~) seems to be missing below, but this is just due to a $em(feature) of MAML.
   $acode(
public define Word4                ~ Word4 y.         bitwise complement to 1
public define Word8                ~ Word8 y.
public define Word16               ~ Word16 y.
public define Word32               ~ Word32 y.
public define Word64               ~ Word64 y.
public define Word128              ~ Word128 y.
   )
   We also consider comparisons. Words are compared  by $att(+=<) and $att(+<) as unsigned numbers and
   by $att(-<) and $att(-=<) as signed numbers.
   $acode(
public define Bool     Word4 x    +=< Word4 y.     Comparison as unsigned.
public define Bool     Word8 x    +=< Word8 y.
public define Bool     Word16 x   +=< Word16 y.
public define Bool     Word32 x   +=< Word32 y.
public define Bool     Word64 x   +=< Word64 y.
public define Bool     Word128 x  +=< Word128 y.

public define Bool     Word4 x     +< Word4 y.
public define Bool     Word8 x     +< Word8 y.
public define Bool     Word16 x    +< Word16 y.
public define Bool     Word32 x    +< Word32 y.
public define Bool     Word64 x    +< Word64 y.
public define Bool     Word128 x   +< Word128 y.

public define Bool     Word4 x    -=< Word4 y.    Comparison as signed.
public define Bool     Word8 x    -=< Word8 y.
public define Bool     Word16 x   -=< Word16 y.
public define Bool     Word32 x   -=< Word32 y.
public define Bool     Word64 x   -=< Word64 y.
public define Bool     Word128 x  -=< Word128 y.

public define Bool     Word4 x     -< Word4 y.
public define Bool     Word8 x     -< Word8 y.
public define Bool     Word16 x    -< Word16 y.
public define Bool     Word32 x    -< Word32 y.
public define Bool     Word64 x    -< Word64 y.
public define Bool     Word128 x   -< Word128 y.
   )
   As  usual we  don't define  $att(>=+), $att(>+),  $att(>=-) and  $att(>-). They  are just  the symmetrics  of the
   previous ones and are defined automatically by the compiler.$p

   Word types may also be considered as  quotients of the ring of the integers. Precisely,
   $att(Word8) is  Z/(2$sup(8))Z, $att(Word16) is  Z/(2$sup(16))Z, etc... For  this reason, it is  legitimate to
   introduce the  corresponding ring  operations (which are  independant of the  notion of
   signed/unsigned).
   $acode(
public define Word4     Word4 x    + Word4 y.      Addition modulo 2^4
public define Word8     Word8 x    + Word8 y.      etc...
public define Word16    Word16 x   + Word16 y.
public define Word32    Word32 x   + Word32 y.
public define Word64    Word64 x   + Word64 y.
public define Word128   Word128 x  + Word128 y.

public define Word4     Word4 x    - Word4 y.      Substraction modulo 2^4
public define Word8     Word8 x    - Word8 y.      etc...
public define Word16    Word16 x   - Word16 y.
public define Word32    Word32 x   - Word32 y.
public define Word64    Word64 x   - Word64 y.
public define Word128   Word128 x  - Word128 y.

public define Word4                - Word4 y.      Opposite modulo 2^4
public define Word8                - Word8 y.      etc...
public define Word16               - Word16 y.
public define Word32               - Word32 y.
public define Word64               - Word64 y.
public define Word128              - Word128 y.

public define Word4     Word4 x    * Word4 y.      Multiplication modulo 2^4
public define Word8     Word8 x    * Word8 y.      etc...
public define Word16    Word16 x   * Word16 y.
public define Word32    Word32 x   * Word32 y.
public define Word64    Word64 x   * Word64 y.
public define Word128   Word128 x  * Word128 y.
   )
   Of course, there  is a priori no  euclidian division since rings like  Z/(2$sup(n))Z are far
   from  being euclidian  rings  (they are  first  of all  not  integral domains).   Given
   elements $att(a) and $att(b), such that $att(b) is not zero in the given ring, the problem:
   $ecode(
     a = b*q + r
     r +< b             (comparison as 'unsigned')
   )
   may have several solutions. For example, in $att(Word4):
   $ecode(
     5 = 3*1  + 2
     5 = 3*12 + 1
   )
   What  we see  is that  neither the  remainder nor  the quotient  are  uniquely defined.
   However, as  soon as the quotient  is chosen, the remainder  is determined by $att(r  = a - b*q).
   Hence,  there is  a unique solution  with the  smallest (again relatively  to the
   $em(unsigned) comparison) possible quotient (the first one in our examples). This solution
   is computed by:
   $acode(
public define Maybe((Word4,Word4))        Word4 x   / Word4 y.
public define Maybe((Word8,Word8))        Word8 x   / Word8 y.
public define Maybe((Word16,Word16))      Word16 x  / Word16 y.
public define Maybe((Word32,Word32))      Word32 x  / Word32 y.
public define Maybe((Word64,Word64))      Word64 x  / Word64 y.
public define Maybe((Word128,Word128))    Word128 x / Word128 y.
   )
   The result  is $att(failure) if you divide  by 0. Otherwise, it  is $att(success((q,r))), where
   $att(q) and $att(r) are the quotient and  the remainder.$p

   Words may also be seen as digits in appropriate numerations basis. For example, a datum
   of type $att(Word8) is  nothing else than a digit in basis  256. Anubis provides primitives
   for converting between  integers (type $att(Int), primitive in Anubis;  see below) to lists
   of such digits, and conversely.$p

   Notice  that  the  order  of  the  $em(digits) in  these  lists  is  $em(least  significant
   first). These operations ignore the sign.
   $acode(
public define Int            to_Int(List(Word4)   x). The result is positive or zero.
public define Int            to_Int(List(Word8)   x). Idem.
public define Int            to_Int(List(Word16)  x). ...
public define Int            to_Int(List(Word32)  x).
public define Int            to_Int(List(Word64)  x).
public define Int            to_Int(List(Word128) x).

public define List(Word4)    to_Word4(Int   x).         The sign of 'x' is ignored.
public define List(Word8)    to_Word8(Int   x).         Idem.
public define List(Word16)   to_Word16(Int  x).         ...
public define List(Word32)   to_Word32(Int  x).
public define List(Word64)   to_Word64(Int  x).
public define List(Word128)  to_Word128(Int x).
   )
   The following tools can be useful.
   $acode(
public define Int      to_Int(Word32 x).           Returns x as a non negative Int

public define Word8    truncate_to_Word8 (Int n).  Reduction modulo 2$sup(8).
public define Word32   truncate_to_Word32(Int n).  Reduction modulo 2$sup(32).
   )


   $subsubsection(The types $att(RGB) and $att(RGBA))
   $acode(
public type RGB:
   rgb(Word8 red,
       Word8 green,
       Word8 blue).
   )
   A datum of this type is just a color suitable for use in a computer.
   $acode(
public type RGBA:
   rgba(Word8 red,
        Word8 green,
        Word8 blue,
        Word8 alpha).
   )
   This is the  same one, but with  an $em(alpha) (transparency) channel. The  color is fully
   transparent  (invisible)  if   alpha  is  zero.   It  is  fully   opaque  if  alpha  is
   255. Transparency is used by several tools defined below. For example, you
   can paint a  more or less transparent image  over another image, so that  the latter is
   more or less visible through the former. See the section on images below.


   $subsection(Useful parameters and informations)

   $end

      *** (3.1) Determination of the host system.

   It may  be useful (in particular  when using the  tool 'execute' defined below  in this
   file) to know which host system the program is running on. Host systems are defined by:

public type HostSystem:
   beos,
   linux,
   windows.

   The next tool gives the host system:

public define HostSystem   host_system.

public type HostArchitecture:
   x86,
   mipsel.

   The next tool gives the host architecture:

public define HostArchitecture   host_arch.

      You may also know if the system is little endian or big endian:

public type Endianness:
   little_endian,
   big_endian.

public define Endianness    system_endianness.


      *** (3.2) Version numbers of your Anubis system.

   You can use these in a program, if you need the current version of the system.

public define Word32           major_version_number.
public define Word32           minor_version_number.


      *** (3.3) Anubis directories (where the system is installed).

public define String          anubis_directory.
public define String          my_anubis_directory.


   Try this  (copy the paragraph  below to a  file (remove white spaces  before 'global'),
   compile and execute it):

   global define One
     informations
       (
         List(String) args
       ) =
   print("Anubis version "+to_decimal(major_version_number)+"."+
         to_decimal(minor_version_number)+", installed in:\n   "+
         anubis_directory+"\n   "+
         my_anubis_directory+"\n").


      *** (3.4) Getting and setting environment variables.

public define Maybe(String)   get_environment_variable(String name).
public define Maybe(One)      set_environment_variable(String name, String value).

   For example, the term

      get_environment_variable("ANUBIS")

   may return something like:

      success("/home/georges/anubis")


      *** (3.6) Informations on virtual machines.

public define Word32    virtual_machine_id.

   This number identifies the virtual  machine executing this operation (this is analogous
   to  'getpid'  under  UNIX, but  is  not  a  call  to  getpid, because  anbexec  handles
   multitasking within a single operating system thread).


public type LoadAverage:
   load_average (Float loadav1,              // load average for the past 1 minute
                 Float loadav5,              // load average for the past 5 minutes
                 Float loadav15).            // load average for the past 15 minutes


   Possible states of virtual machines:

public type VirtualMachineState:
   not_used,                       // the machine is currently not used
   running,                        // the machine is currently running
   waiting_for_event,              // the machine is waiting for an input/output event
   waiting_for_condition,          // the machine is in a 'wait for' loop
   waiting_for_completion,         // the machine is waiting for completion of an 'execute' command
   finished,                       // the machine has terminated normally
   need_bigger_stack,              // the machine has asked the system to enlarge its stack
   need_bigger_locked_files_stack, // idem for the stack of locked files
   need_more_memory,               // the machine has asked the system to enlarge the allocator
   invalid_instruction,            // the machine has executed an invalid instruction
   invalid_IP.                     // the machine has detected an invalid instruction pointer value

   Of course,  the last two should  never happen. Precisely, what  it means is  that if it
   happens,  the fault  is ours  not yours.  In that  case we  will be  happy to  get some
   imformations on the problem in order to fix it.


   Virtual machines do not only have a state, but are also making some kind of work:

public type VirtualMachineWorkSort:
   computing,                 // the machine is computing
   deleting,                  // the machine is running the garbage-collector
   equaling,                  // the machine is testing a boolean equality
   serializing,               // the machine is performing a serialization
   unserializing.             // the machine is performing an unserialization


   Now, here are the informations you can get on virtual machines:

   Note: 'starting_point' has been dropped since version 1.13, because meaningless if a process
   can execute code from several modules (which is the case with secondary modules).

public type VirtualMachineInfo:
   vm_info (Word32                      virtual_machine_id,
            VirtualMachineState         state,
            VirtualMachineWorkSort      work_sort,
            Word32                      instruction_pointer,  // current offset in the module
            Word32                      stack_size,           // in 32 bits words
            Word32                      stack_pointer,        // number of 32 bits words in the stack
            Float                       loadav1,              // load average for the past 1 minute
            Float                       loadav5,              // load average for the past 5 minutes
            Float                       loadav15).            // load average for the past 15 minutes


   You may want to get informations on all the machines of the system.

public type SystemInfo:
   sys_info(LoadAverage              load,
            List(VirtualMachineInfo) machines_info).      // infos on machines currently in use


   Use the following to get informations on all machines currently running in the system.

public define SystemInfo      system_info.

   Use the following to get informations on the machine you are currently running.

public define VirtualMachineInfo   virtual_machine_info.

   Returns information on specified machine

public define Maybe(VirtualMachineInfo)   virtual_machine_info(Word32 vm_id).

public define LoadAverage   get_load_average.

   'anbexec' has his own scheduler, which  starts the virtual machines one after the other
   for  a  maximum  number of  instructions.   Each  machine  may  be  in one  of  several
   states. When all the machines in  the system are 'waiting', 'anbexec' enters a sleeping
   state. It is  waked up by any input  arriving on one of the  connections (including the
   keyboard, graphical  screen, network, ...) for  which the machines  are waiting. Hence,
   when all the virtual machines are waiting, 'anbexec' does not consume processor time.


   You may force a virtual machine to wait for input/output events. Just execute this:

public define One        wait_for_event.

   The machine will sleep until  an input/output event arrives (perhaps concerning another
   virtual machine). At that time the value 'unique' is returned.


      *** (3.7) Informations on the memory allocator.

   Virtual  machines  use   a  memory  allocator  which is shared by all virtual machines.
   You can get informations on the allocator. It
   is a chain of memory segments  (called 'main' segments). Within main segments the chain
   of  'free  storage' segments  is  constructed.  When  an  allocation  is required,  the
   allocator carves  a piece  of memory  in a free  storage segment.   If no  free storage
   segment is  big enough, a new  main segment is  added to the allocator  (this operation
   also adds  a new free storage  segment, which occupies almost  all the room  in the new
   main segment). The size  of this new segment is big enough  to satisfy the requirement.
   The  amount  of  memory currently  allocated  by  the  allocator is  approximately  the
   difference between the total  size of main segments and the total  size of free storage
   segments. More precisely, it is exactly given by the following formula (measured in  32
   bits words):

     total_main_size - total_free_storage_size - 2*number_of_main_segments

   You can also get the number of  allocated segments (i.e. the number of pieces currently
   carved from the chain of free storage segments). You must know that one 32 bits word is
   reserved for the  allocator in each allocated segment, and  that each allocated segment
   also contains a  32 bits word for garbage collection (a  reference counter). Hence, the
   total number of 32 bits words currently used for actual data is obtain by subtracting

     2*number_of_allocated_segments

   from the previous computation.

public type AllocatorInfo:
   alloc_info(Word32 allocator_id,        // unique number identifying the allocator (not used since there is only one)
              Bool corrupted,             // if true, the allocator is corrupted (should never be true)
              Word32 size_of_last_main_segments,   // (in 32 bits words)
              Word32 number_of_main_segments,
              Word32 number_of_free_storage_segments,
              Word32 total_main_size,          // total size (in 32 bits words) of main segments
              Word32 total_free_storage_size,  // total size (in 32 bits words) of free storage segments
              Word32 number_of_allocated_segments,
              Word32 total_segregated_size,       // total size (in 32 bits words) of segregated segments
              Word32 total_free_segregated_size).  // total size (in 32 bits words) of free segregated segments


   'allocator_info' returns  informations on the  allocator used by the  currently running
   virtual machine.

public define AllocatorInfo      allocator_info.

   Note: since version 1.7, the allocator  has been enhanced with 'segregated lists'. This
   means  that small  segments  are  allocated from  lists  of segments  all  of the  same
   size. This reduces significantly the time needed for finding a segment to be allocated.


      *** (3.8) Automatic restarting of 'anbexec'.

   You may want to restart 'anbexec' when  it has finished to execute its module. This may
   be useful in  the case you change the  module file (*.adm). Your program  may know that
   the file has  been changed (for example,  by checking the date of  last modification of
   the '.adm'  file), and  decide to  stop execution.  Normally,  in this  case, 'anbexec'
   stops  and nothing more  happens.  'anbexec'  knows if  it must  restart or  not.  This
   depends on the state  of an internal flag.  You can change the  value of this flag with
   the following primitive:

public define One        restart(Bool b).

   If you execute  'restart(true)', 'anbexec' will restart with the  same arguments on the
   command line (and the same name for the module file), but only when the current work is
   finished.

   Notice  that  by default,  'anbexec'  will not  restart  automatically  (i.e. the  flag
   initially has the value 'false').  You may also get the value of the flag with:

public define Bool       will_restart.

   Note: since version 1.13 this feature can in most cases be replaced by a technique
   using secondary modules. Search for 'load_adm' below in this file.


   *** (4) Operations on strings, byte arrays, integers and floating point numbers.


      *** (4.1) Strings (type 'String').

public define String          constant_string(Int   n,
                                              Word8 c).

   Example: constant_string(10,'a') is "aaaaaaaaaa"

public define Bool            string_less(String x,
                                          String y).

   'string_less(x,y)' is  'true' if 'x'  comes before 'y'  in the alphabetical  order. The
   comparison of  characters is case-insensitive.  If the strings are  equal 'string_less'
   returns false.

public define Int     length(String s).


   Example:   length("abcd")  is  4.

public define Maybe(Word8)     nth(Int n,
                                   String s).

   Examples:  nth(2,"gabuzomeu")   is success('b')
              nth(0,"gabuzomeu")   is success('g')
              nth(-4,"gabuzomeu")  is failure
              nth(8,"gabuzomeu")   is success('u')
              nth(9,"gabuzomeu")   is failure

public define Maybe(Int)      decimal_scan(String s).

   This function  tries to read (scan)  an integer (of  type Int) from within  a character
   string.

public define Maybe(Float)    string_to_float(String s).

   The  above functions  try  to read  an  integer (or  a floating  point  number) from  a
   string. Of course this may fail. This is  the reason why they do not produce a datum of
   type 'Int' or 'Float', but of type 'Maybe(Int)' or 'Maybe(Float)'.

public define Maybe(String)   sub_string(String s,
                                         Int start,
                                         Int length).

   For example:  sub_string("gabuzomeu",2,2) is success("bu"). The result  is 'failure' if
   at least one of the limits of the sub_string is outside the given string.

   A function to quickly find a string into another string. Search begins at 'start' position:

public define Maybe(Int)      find_string(String s,
                                          String looking_for,
                                          Int start).

public define String          String x + String y.

   For example: "ga" + "bu" + "zo" + "meu" is "gabuzomeu"

public define String          concat(List(String) l).

   For example: concat(["ga","bu","zo","meu"]) yields: "gabuzomeu"

   Note: It is more efficient to write 'concat([a,b,c,d])' than 'a + b + c + d',
   because in the first case the same string can be copied several times, whilst
   in the second case each string is copied only once.
   However, since 2015/07/11, you don't have to worry about this because the
   compiler automatically optimizes by eliminating '+' in favor of 'concat'.

to do: create implode/explode for byte arrays.
public define String          implode(List(Word8) l).
public define List(Word8)     explode(String s).

   Examples:

         explode("abcd")              is [65,66,67,68]
         implode([65,66,67,68])       is "abcd"

   Printing to the standard output:

public define One             print(String s).

   The same one, but the printing is immediate (the outout buffer is immediately flushed):

public define One             iprint(String s).

   Printing into a stream:

public define One             print(WStream file, String s).

   Putting a string into the 'CRLF' format. Actually, this function removes all '\r' and replaces
   all '\n' by '\r\n'.

public define String          toCRLF(String s).

   The next one puts a string into the 'LF' format. Actually, it just removes all '\r'.

public define String          toLF(String s).


      *** (4.2) Byte arrays (type 'ByteArray').

   'ByteArray' is  a primitive type. It is  almost like 'String', except  that byte arrays
   may contain bytes with value 0. Here are some tools for byte arrays:

public define Int              length(ByteArray s).
public define Word32           length32(ByteArray s).    // the length as a Word32

to do: create a 'nth(Word32,ByteArray)'.
public define Maybe(Word8)     nth(Int n, ByteArray s).

   A variant for 'nth' (which returns 0 if out of bounds):

public define Word8            force_nth(Int n, ByteArray b).

to do: create a put(ByteArray,Word32,Word8).
public define Maybe(One)       put(ByteArray s, Int n, Word8 c).

   This   puts   the   character   'c'   at   position  'n'   in   's'   (if   result   is
   'success(unique)'). Result is 'failure' if 'n'  is out of bounds. In that case however,
   you don't have to worry. Nothing happens. This will not generate a segment violation.

   Of course,  this is a side  effect, and all references  to this byte array  will have a
   byte changed.

   The functions below construct a new byte array filled by a word.

public define ByteArray       constant_byte_array     (Int   n, Word8   c).
public define ByteArray       constant_byte_array_16  (Int   n, Word16  w).

   The size 'n' is always in bytes. For example, 'constant_byte_array_16(5,0x6566)' produces
   a 5 bytes byte array containing the bytes:  fefef   Notice that the 16 bits word is stored
   in little endian mode ('e' = 0x65, 'f' = 0x66) (on a little endian machine; on a big endian
   machine, I don't know what happens !).

   Comparing byte arrays: compares a and b and returns 'before', 'same' or 'after'. The comparison
   uses the lexicographic order.

public define Compare        ByteArray a >=< ByteArray b.


public define One             truncate(ByteArray s, Int size).

   The  above function  truncates the  byte array  's'  to 'size'  bytes. This  is a  side
   effect. If 'size' is negative, or greater than the length of 's', nothing is done.


public define ByteArray       extract(ByteArray s, Int start, Int end).

   This function extracts from 's' a copy  of the portion of 's' which is between position
   'start' (included)  and position  'end' (non  included). Of course,  the result  may be
   shorter than 'end -  start', if 'end' and/or 'start' are out  of bounds. In particular,
   it may be the empty byte array. There is no side effect.

   The function below writes a byte array 'src' into a byte array 'dest' at a given position.

public define One             write(ByteArray scr, ByteArray dest, Int position).

   If some bytes of 'src' are to be written outside 'dest' (on one side or the other one),
   they are simply not written. Of course, 'write' produces a side effet on 'dest'.

public define ByteArray       ByteArray s + ByteArray t.

   This concatenates byte arrays.


   The  following two  primitives transform  a byte  array into  a string.  The  first one
   'to_hexa' transforms  each byte in the byte  array into a sequence  of two hexadecimal
   digits. For example, if the byte array 's' has 3 bytes with respective values 4, 10 and
   55, we have:

      to_hexa(s) = "040a37"

   Note that 'to_hexa' transforms a byte array of length n into a string of length 2*n.

   On the contrary, 'to_string' copies into a new string the bytes of 's' until either the
   end of 's' or  the first zero byte is reached. Hence 'to_string(s)'  is at most as long
   as 's'.  For example, if s has the following 5 bytes:

      'a' 'b' 0 'c' 'd'

   we have: to_string(s) = "ab".

public define String           to_hexa      (ByteArray s).    // new name for 'to_ascii'
public define String           to_string    (ByteArray s).

   'to_byte_array' transforms a string into a byte array (of the same size):

public define ByteArray        to_byte_array(String s).

   'to_text_mode' replaces all CRLF by LF and  isolated CR by LF within the argument. This
   is a destructive process,  i.e. it acts on the given argument  itself which is returned
   as the result.

public define ByteArray        to_text_mode(ByteArray s).

   The next two functions are analogous to those defined above for strings.

public define ByteArray        toCRLF(ByteArray s).
public define ByteArray        toLF(ByteArray s).

   The function below searches for the first occurrence of 'pattern' in 'text'
   starting at position 'start'. It uses the Boyer-Moore algorithm. If the pattern
   is found it returns its offset since the beginning of 'text'.

public define Maybe(Int)       find_byte_array(ByteArray  text,
                                               ByteArray  pattern,
                                               Int        start).

      *** (4.3) True integers (type 'Int').

   The  type 'Int'  of  arbitrary large  (thousands of  digits  if you  like) integers  is
   primitive in  Anubis.

   Integers  written  literally   (eventually  preceded  by  a  +  or   -  sign)  have  an
   interpretation as 'Int'.  Anubis provides the following primitive functions:

public define Bool                  Int x  <  Int y.      Strict comparison.
public define Bool                  Int x  =< Int y.      Non strict comparison.

public define Int                   Int x  +  Int y.      Addition.
public define Int                   Int x  -  Int y.      Substraction.

public define Int                          -  Int x.      Opposite.

public define Int                   Int x  *  Int y.      Multiplication.
public define Maybe((Int,Int))      Int x  /  Int y.      Euclidian division.

   Minimum and maximum:

public define inline Int                   min(Int x, Int y).    returns the smallest of x and y
public define inline Int                   max(Int x, Int y).    returns the bigest of x and y
public define Int                   min(List(Int) l,
                                        Int       default).    returns the smallest of the list
                                                               ('default' if list is empty)
public define Int                   max(List(Int) l,
                                        Int       default).    returns the bigest of the list
                                                               ('default' if list is empty)


   The division  is the euclidian  division. In other  words, if 'a'  and 'b' are  of type
   'Int',  and 'b'  is not  '0', 'a/b'  is  'success((q,r))', where  'q' and  'r' are  the
   quotient and the remainder of the euclidian division of 'a' by 'b', i.e., we have:

          a = b*q + r
          0 =< r < |b|

   where '|b|' is the absolute value of 'b'. The result is 'failure' if 'b' is zero.

public define String                abs_to_decimal(Int x).
public define String                abs_to_hexa(Int x).

   These two functions provide the decimal and hexadecimal representations of the absolute
   value  of  an  integer.  In  other  words,  these  functions  ignore  the sign  of  the
   integer. You have to determine the sign yourself and eventually concatenate it in front
   of the result (see the standard library for such tools).

   Furthermore,  'abs_to_hexa' does not  produce any  prefix like  "0x". It  produces only
   hexadecimal digits.

   Canonical example: define the 'factorial' function:

   define Int
     fact
       (
         Int x
       ) =
     if x =< 0 then 1 else x*fact(x - 1).

   global define One
     print_fact_1000
       (
         List(String) args
       ) =
   print(abs_to_decimal(fact(1000))+"\n").

   Executing 'anbexec print_fact_1000' will give this:

   402387260077093773543702433923003985719374864210714632543799910429938512398629020592044
   208486969404800479988610197196058631666872994808558901323829669944590997424504087073759
   918823627727188732519779505950995276120874975462497043601418278094646496291056393887437
   886487337119181045825783647849977012476632889835955735432513185323958463075557409114262
   417474349347553428646576611667797396668820291207379143853719588249808126867838374559731
   746136085379534524221586593201928090878297308431392844403281231558611036976801357304216
   168747609675871348312025478589320767169132448426236131412508780208000261683151027341827
   977704784635868170164365024153691398281264810213092761244896359928705114964975419909342
   221566832572080821333186116811553615836546984046708975602900950537616475847728421889679
   646244945160765353408198901385442487984959953319101723355556602139450399736280750137837
   615307127761926849034352625200015888535147331611702103968175921510907788019393178114194
   545257223865541461062892187960223838971476088506276862967146674697562911234082439208160
   153780889893964518263243671616762179168909779911903754031274622289988005195444414282012
   187361745992642956581746628302955570299024324153181617210465832036786906117260158783520
   751516284225540265170483304226143974286933061690897968482590125458327168226458066526769
   958652682272807075781391858178889652208164348344825993266043367660176999612831860788386
   150279465955131156552036093988180612138558600301435694527224206344631797460594682573103
   790084024432438465657245014402821885252470935190620929023136493273497565513958720559654
   228749774011413346962715422845862377387538230483865688976461927383814900140767310446640
   259899490222221765904339901886018566526485061799702356193897017860040811889729918311021
   171229845901641921068884387121855646124960798722908519296819372388642614839657382291123
   125024186649353143970137428531926649875337218940694281434118520158014123344828015051399
   694290153483077644569099073152433278288269864602789864321139083506217095002597389863554
   277196742822248757586765752344220207573630569498825087968928162753848863396909959826280
   956121450994871701244516461260379029309120889086942028510640182154399457156805941872748
   998094254742173582401063677404595741785160829230135358081840096996372524230560855903700
   624271243416909004153690105933983835777939410970027753472000000000000000000000000000000
   000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
   000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
   000000000000000000000000000000000000000000000


   On a 1.66 GHz Pentium, this  computation is quite instantaneous.  With 10000 instead of
   1000, the computation takes about 3 seconds (and the result has 35660 decimal digits).


      *** (4.4) Floating point numbers (type 'Float'). (obsolete in a near future)

   Many 'float'  operations return a  datum of type  'Maybe(Float)'.  This is  because the
   operation may  fail to give  an actual number.  This may be  due to many  reasons. Most
   often the reason is overflow. See 'library/tools/maybefloat.anubis' for useful tools.

public define Maybe(Float)    Float x + Float y.
public define Maybe(Float)    Float x - Float y.
public define Maybe(Float)    Float x * Float y.
public define Maybe(Float)    Float x ^ Float y.
public define Maybe(Float)    Float x / Float y.
public define Float           sin(Float x).
public define Float           cos(Float x).
public define Maybe(Float)    tan(Float x).
public define Maybe(Float)    asin(Float x).
public define Maybe(Float)    acos(Float x).
public define Float           atan(Float x).
public define Maybe(Float)    exp(Float x).
public define Maybe(Float)    log(Float x).
public define Maybe(Float)    sqrt(Float x).
public define Bool            Float x < Float y.
public define Bool            Float x =< Float y.

public define String          float_to_string(Float n, Int prec).

   where 'prec' is the number of digits to print after the dot.


public define Word32          integral_part_to_Word32(Float n).
public define Int             integral_part(Float n).

public define Float           to_Float(Word32 x).
public define Float           to_Float(Int n).


      *** (4.5) Floating point numbers. (types 'Float32' and 'Float64'). (still under construction)

   The following  implementation of  floating point numbers  follows the  IEEE754 standard
   (http://en.wikipedia.org/wiki/IEEE_754).

 public type FloatSign:
   positive,
   negative.


   The types 'Float32Value' and 'Float64Value' are for actual (non infinite) numbers.

 public type Float32Value:...      opaque types
 public type Float64Value:...


 public type Float32:
   not_a_number,
   infinite      (FloatSign     sign),
   actual        (Float32Value  value).

 public type Float64:
   not_a_number,
   infinite      (FloatSign     sign),
   actual        (Float64Value  value).

   The alternatives 'actual'  correspond to zeros, normalized and  denormalized numbers as
   defined by the IEEE754 standard.

   Remark: The  conversion between x  and actual(x) also  does just nothing. The  datum is
   just typed differently.

   Data of  these types are  not implemented using  the standard algorithms of  the Anubis
   compiler. They are implemented as 32 bits and 64 bits words as described by the IEEE754
   standard.  They may actually be converted  to and fro (and of course, these conversions
   do just nothing):

 public define Word32   to_Word32(Float32 f).
 public define Word64   to_Word64(Float64 f).
 public define Float32  to_Float32(Word32 w).
 public define Float64  to_Float64(Word64 w).


   Current operations:

 public define Float32         Float32 x + Float32 y.
 public define Float32         Float32 x - Float32 y.
 public define Float32         Float32 x * Float32 y.
 public define Float32         Float32 x ^ Float32 y.
 public define Float32         Float32 x / Float32 y.
 public define Float32         sin(Float32 x).
 public define Float32         cos(Float32 x).
 public define Float32         tan(Float32 x).
 public define Float32         asin(Float32 x).
 public define Float32         acos(Float32 x).
 public define Float32         atan(Float32 x).
 public define Float32         exp(Float32 x).
 public define Float32         log(Float32 x).
 public define Float32         sqrt(Float32 x).

 public define Float64         Float64 x + Float64 y.
 public define Float64         Float64 x - Float64 y.
 public define Float64         Float64 x * Float64 y.
 public define Float64         Float64 x ^ Float64 y.
 public define Float64         Float64 x / Float64 y.
 public define Float64         sin(Float64 x).
 public define Float64         cos(Float64 x).
 public define Float64         tan(Float64 x).
 public define Float64         asin(Float64 x).
 public define Float64         acos(Float64 x).
 public define Float64         atan(Float64 x).
 public define Float64         exp(Float64 x).
 public define Float64         log(Float64 x).
 public define Float64         sqrt(Float64 x).


   The same  operations taking actual numbers return  in general numbers which  may not be
   actual numbers, except in some cases, like 'sin', 'cos' and 'atan'. Of course, from the
   implementation view point they are exactly the same as above.

 public define Float32         Float32Value x + Float32Value y.
 public define Float32         Float32Value x - Float32Value y.
 public define Float32         Float32Value x * Float32Value y.
 public define Float32         Float32Value x ^ Float32Value y.
 public define Float32         Float32Value x / Float32Value y.
 public define Float32Value    sin(Float32Value x).
 public define Float32Value    cos(Float32Value x).
 public define Float32         tan(Float32Value x).
 public define Float32         asin(Float32Value x).
 public define Float32         acos(Float32Value x).
 public define Float32Value    atan(Float32Value x).
 public define Float32         exp(Float32Value x).
 public define Float32         log(Float32Value x).
 public define Float32         sqrt(Float32Value x).

 public define Float64         Float64Value x + Float64Value y.
 public define Float64         Float64Value x - Float64Value y.
 public define Float64         Float64Value x * Float64Value y.
 public define Float64         Float64Value x ^ Float64Value y.
 public define Float64         Float64Value x / Float64Value y.
 public define Float64Value    sin(Float64Value x).
 public define Float64Value    cos(Float64Value x).
 public define Float64         tan(Float64Value x).
 public define Float64         asin(Float64Value x).
 public define Float64         acos(Float64Value x).
 public define Float64Value    atan(Float64Value x).
 public define Float64         exp(Float64Value x).
 public define Float64         log(Float64Value x).
 public define Float64         sqrt(Float64Value x).


   Comparison are defined only for actual numbers. Notice that up to conversion, these are
   the same operations as '-<' and '-=<' for Word32 and Word64 (signed comparison).

 public define Bool            Float32Value x <  Float32Value y.
 public define Bool            Float32Value x =< Float32Value y.
 public define Bool            Float64Value x <  Float64Value y.
 public define Bool            Float64Value x =< Float64Value y.


   Conversions to and from integers.

 public define Int             integral_part(Float32Value x).
 public define Int             integral_part(Float64Value x).
 public define Float32         to_Float32(Int n).
 public define Float64         to_Float64(Int n).


   Decimal representation. The precision is the number of decimal digits after the dot.

 public define String          to_decimal(Float32 f, Int precision).
 public define String          to_decimal(Float64 f, Int precision).


   *** (5) Files.

      *** (5.1) Opening files.

   You can open a connection to a file  with the following commands. Of course, there is a
   'Maybe' because  result is not  guaranteed. You don't  have to worry about  closing the
   file.  It  is automatically closed by  the garbage-collector when needed  (i.e. when no
   more reference to this file exists).

public type ReadFileMode:
   read.                       // this is for reading in the file (from the beginning)

public type ReadWriteFileMode:
   new,                        // this creates a new empty file
   append.                     // you can write at the end of an existing file

public define Maybe(RStream)  file(String filename, ReadFileMode mode).
public define Maybe(RWStream) file(String filename, ReadWriteFileMode mode).


      *** (5.2) Unix file system interface.

public type ReadMode:
  non_readable,             // -
  readable.                 // r

public type WriteMode:
  non_writable,             // -
  writable.                 // w

public type ExecMode:
  non_executable,           // -
  executable.               // x

public type PrivilegedExecMode:
  non_executable,           // -
  executable,               // x
  may_change_id_no_exec,    // S     undocumented (?) Unix: means suid (guid) bit set but not executable
  may_change_id.            // s

public type FileMode:                          // corresponding UNIX permission
  file(ReadMode user_readable,                 // r--------
       WriteMode user_writable,                // -w-------
       PrivilegedExecMode user_executable,     // --x------   --s------    --S------
       ReadMode group_readable,                // ---r-----
       WriteMode group_writable,               // ----w----
       PrivilegedExecMode group_executable,    // -----x---   -----s---    -----S---
       ReadMode others_readable,               // ------r--
       WriteMode others_writable,              // -------w-
       ExecMode others_executable).            // --------x

public define Maybe(FileMode) get_file_mode(String file_name).
public define Maybe(One)      set_file_mode(String file_name, FileMode mode).

   'get_file_mode' returns 'failure' if the file cannot be found.  'set_file_mode' returns
   'success(unique)' if the mode has been changed, 'failure' otherwise.

public type FileTimes:
   times  (Word32      last_modified,
           Word32      last_accessed).

public define Maybe(FileTimes)    get_file_times(String filename).
public define Maybe(One)          set_file_times(String filename, FileTimes  times).

   Under UNIX there  is another time stamp which  is the time of the  last modification of
   the  attributes  of  the  file.  Furthermore,  this time  stamp  cannot  be  set  under
   Linux. Under Windows there  is another file stamp which is the  time of creation of the
   file. In order to have a uniform semantics, we did not consider them here.


      *** (5.3) Standard files.

public define RStream     stdin.     // standard input (keyboard)
public define WStream     stdout.    // standard output (console)
public define WStream     stderr.    // standard error output
                                     //   (console unless redirected)


      *** (5.4) Getting the size of a file.

public define Int           file_size(RStream file).
public define Int           file_size(WStream file).
public define Int           file_size(RWStream file).

   These functions return 0 if either the size of the file cannot be determined (which
   is not a normal situation) or if the 'file' is a network connection or a standard
   file (see (5.3)).

   Have a  look at 'anubis/library/tools/file_and_dir.anubis'  for a 'file_size' taking  the file
   name as its argument.


      *** (5.5) Weakening file modes.

   You  can weaken  the type  of a  readable and  writable connection.  This  is sometimes
   necessary for type compatibility.

public define RStream       weaken(RWStream f).
public define WStream       weaken(RWStream f).


      *** (5.6) Managing directories.

public define String get_current_directory.

   Returns the full path of the current directory.

public define Bool   set_current_directory(String name).

   Changes  the  current   directory  and  returns  'true'.   If   not  possible,  returns
   'false'. Warning:  this primitive changes the  current directory for  anbexec, i.e. for
   all virtual machines currently running within  anbexec. Hence, it is not very reliable,
   as soon as several virtual machines may use it.


public type SearchMode:
  non_searchable,
  searchable.


   Creating a directory.

public type MakeDirectoryResult:
  permission_denied,
  name_already_exists,
  too_many_links,
  not_enough_room,
  read_only_file_system,
  ok.

public type DirectoryMode:
  directory(ReadMode user_readable,
            WriteMode user_writable,
            SearchMode user_searchable,
            ReadMode group_readable,
            WriteMode group_writable,
            SearchMode group_searchable,
            ReadMode others_readable,
            WriteMode others_writable,
            SearchMode others_searchable).

   Have a look at 'library/tools/basis.anubis' for a default directory mode.

public define MakeDirectoryResult     make_directory(String name, DirectoryMode mode).


   Removing a directory.

public type RemoveDirectoryResult:
  directory_does_not_exist,
  permission_denied,
  read_only_file_system,
  directory_not_empty,
  ok.

public define RemoveDirectoryResult   remove_directory(String directory_name).


   Reading the content of a directory (according to a file name mask).

to do: type FileDescription: some Word32 should be Int or ''Time''.
public type FileDescription:

  no_info    (String name),  // this is a file whose only the name is known. This may be due
                             // to a file system problem, and normally should not happen.

  file       (String name,              // regular file
              Int    size,              // size in bytes
              FileMode mode,            // see above
              Word32 last_modified),    // date of last modification (may be converted with
                                        // 'convert_time')

  link       (String name,              // symbolic link
              String value,             // path of file pointed to
              FileMode mode,            // see above
              Word32 last_modified),    // see above

  directory  (String name,              // directory
              DirectoryMode mode,       // see above
              Word32 last_modified).    // see above


   The  next  function  finds all  the  names  of  the  files,  links and  directories  in
   'directory_name', matching the given name mask.

public define List(String)      directory_list(String  directory_name,
                                               String  file_name_mask).

   The same one, but with full informations on each file, link, or directory. Furthermore,
   we allow the use of different masks for each sort of file.

public define List(FileDescription)
  directory_full_list
    (
      String            directory_name,
      String            file_name_mask,
      String            link_name_mask,
      String            directory_name_mask
    ).

   If  you are  not interested  in some  sort of  files, use  the empty  string ""  as the
   corresponding mask.


      *** (5.7) Creating symbolic links.

   You can create symbolic links to file with:

public define Bool
   create_symbolic_link
     (
       String file_path,
       String link_name
     ).

   Note: Does'nt work under MicroSoft Windows, because there is no notion of link.


      *** (5.8) Reading and writing files (and also TCP/IP connections).

   See 'anubis/library/tools/connections.anubis' for an unified treatement of all sorts of
   connections (files, TCP/IP and SSL).

   Reading at most n  bytes from a file or TCP connection. A  result of 'error' means that
   an unrecoverable error has occured. If time is out, the result is 'timeout'. Otherwise,
   a byte array is returned (which may be empty).

public type ReadResult:
    error,
    timeout,
    ok(ByteArray).


to do: timeout should be of type Time or UTime.
public define ReadResult
  read
    (
      RStream file,
      Int n,
      Int timeout       // in seconds
    ).

   Writing to a file or TCP connection.  A result of 'failure' means that an unrecoverable
   error has occured. In that case, the connection has been closed.

public define Maybe(Int)    // number of bytes written
  write
    (
      WStream file,
      ByteArray data
    ).

   Reading a whole line.

public type ReadLineResult:
    error,
    timeout,
    eof,
    ok(String).

to do: timeout should be of type Time or UTime.
public define ReadLineResult
  read_line
    (
      RStream file,
      Int n,
      Int timeout       // in seconds
    ).

   Reading a whole file.

public type ReadFileResult:
  cannot_find_file,
  read_error(ByteArray),
  ok(ByteArray).

public define ReadFileResult
  read_from_file
    (
      String file_name
    ).

   Writing a whole file.

to do: type WriteFileResult: Word32 bytes_written should be Int.
public type WriteFileResult:
  cannot_open_file,
  write_error(Word32 bytes_written),
  ok.

public define WriteFileResult
  write_to_file
    (
      String file_name,
      ByteArray data
    ).


   You may  also want to go directly  to an offset in  a file without reading  it (this is
   called 'seeking'), and you may want to know at which offset you are currently in a file
   (this is called 'telling').

public define Bool          seek(RStream  file, Int where).
public define Bool          seek(RWStream file, Int where).
public define Int           tell(RStream  file).
public define Int           tell(RWStream file).

   'seek' returns 'false' if an error has occured.

   'tell' returns the current offset (position) in  the file, 0 if the connection is not a
   disk file, and -1 if an error has occured.


      *** (5.9) Removing and renaming files.

public define Bool          remove(String file_name).

   returns 'true' if  the file has been removed, false otherwise.  Note: this command does
   not remove directories. Use 'remove_directory' for that purpose.

public define Bool          rename(String old_name,
                                   String new_name).

   Result is 'true' on success.


      *** (5.10) Flushing files.

      Writable streams can be 'flushed' (i.e. the content of the buffer is sent). The result
      is 'true' if successful.

public define Bool           flush  (RWStream  file).
public define Bool           flush  (WStream   file).


   $begin

   $subsection(Network interface)

   Anubis manages several sorts of connections over the IP (Internet Protocol):
   $list(
     $item TCP
     $item UDP
     $item SSL
   )
   SSL connections  are treated below in  another section. Raw sockets  are also available
   (see below).


   $subsubsection(Connecting to a TCP/IP server ($att(connect)))

   We need  a type which encapsulates  all network connection errors.   It participates to
   the type of thing returned by $att(connect).
   $acode(
public type NetworkConnectError:
   cannot_create_the_socket,
   address_port_not_available,
   connection_refused,
   network_unreachable,
   address_port_already_in_use,
   out_of_time.
   )
   You  can open  a connection  to a  local or  remote TCP/IP  server, with  the following
   command.  Of course,  there is a $att(Result) schema because  connecting is not guaranteed.
   You don't  have to worry about closing  the connection.  It is  automatically closed by
   the garbage-collector when needed.

   $comment(to do: IP ports should be Word16.)
   $acode(
public define Result(NetworkConnectError,RWStream)
   connect(Word32 ip_address,
           Word32 port).
   )
   $bold(Note:) To read data  on a client connection $att(c), just use  $att(*c). This blocks the virtual
   machine until a  datum is available for  reading. Of course, this does  not block other
   virtual machines, and the scheduler switches  immediatly to another machine if no datum
   is available  on the connection. Hence the  virtual machine is dedicated  to the client
   connection. This is the reason why, you should not forget to use
   $att(delegate) if you want
   to perform some other task while waiting for input on a client connection.$p

   When the client  connection is closed (and only in this  case), $att(*c) returns $att(failure).
   Notice that a connection  is also closed automatically when it is  no more needed (i.e.
   when there is no more reference to it).$p

   $bold(Subsequent note:) Actually,  $att(connect to  network), $att(*c)  and $att(c  <- ?)  are
   more or less obsolete. Use
   $att(connect) (defined above), $att(read) and $att(write).$p

   Two   functions  $ref(send_datum)($att(send_datum))   and
   $ref(send_datum)($att(receive_datum))  are   defined  for  transmitting  serializable  data   over  a  TCP/IP
   connection.


   $subsubsection(Querying IP addresses)
   $acode(
public define (Word32,Word32)       local_IP_address_and_port (RWStream connection).
public define (Word32,Word32)       remote_IP_address_and_port (RWStream connection).
   )
   Return  the  local   and  other  end  (remote)  IP  address  and   port  for  a  TCP/IP
   connection. Returns $att((0,0)), if not a TCP/IP connection.


   $subsubsection(Creating a TCP/IP network server ($att(start_server)))

   A TCP/IP server is a datum of the following opaque type:
   $acode(
public type Server:...
   )
   When  a server  is  up,  it runs  an  $em(infinite) loop,  always  testing for  connection
   requests. After accepting a connection, it delegates the handling of this connection to
   another  virtual  machine.   Of  course,  several  such  delegated   machines  may  run
   simultaneously, i.e. the server can handle any number of clients at the same time.$p

   If you want to start a server use the following.
   $acode(
public type StartServerResult:
   cannot_create_the_socket,
   cannot_bind_to_port,
   cannot_listen_on_port,
   ok(Server).

public define StartServerResult
  start_server
    (
      Word32                         ip_addr,
      Word32                         ip_port,
      (RStream) -> Bool              can_accept,
      Server -> ((RWStream) -> One)  handler,
      Var(Bool)                      shutdown_required,
      Word8                          listener_priority,
      Word8                          handler_priority
    ).
   )
   $att(can_accept) must return $att(false) if the connection is iundesirable. $att(handler) is the function which
   handles the request. The server is shut down as soon as the dynamic variable $att(shutdown_required) contains
   the value $att(true). $att(listener_priority) and $att(handler_priority) set the priority of the listening process
   and of handler precesses.$p

   For compatibility with versions prior to 1.14, we keep the following:
   $acode(
public define StartServerResult
  start_server
    (
      Word32                        ip_addr,
      Word32                        ip_port,
      (RStream) -> Bool             can_accept,
      Server -> ((RWStream) -> One) handler,
      (One) -> One                  notify,
      Var(Bool)                     shutdown_required
    ).

public define StartServerResult
  start_server
    (
      Word32                        ip_addr,
      Word32                        ip_port,
      Server -> ((RWStream) -> One) handler,
      (One) -> One                  notify,
      Var(Bool)                     shutdown_required
    ).

public define StartServerResult
  start_server
    (
      Word32                        ip_addr,
      Word32                        ip_port,
      Server -> ((RWStream) -> One) handler,
      (One) -> One                  notify
    ).
   )
   Two tools are useful  to manage servers. The first one shuts  down a server, the second
   one tests if a server is down.
   $acode(
public define One    shutdown(Server s).
public define Bool   is_down(Server s).
   )
   The function below returns the current number of client connections to the server.
   $acode(
public define Int    number_of_connections(Server s).
   )
   You have  examples of servers in  $fname(library/examples/client_server.anubis) and in
   $fname(library/web/multihost_http_server.anubis).


   $subsubsection(Creating an UDP client socket ($att(create_udp_client_socket)))

   Before you can send an UDP packet (as a client), you must first create an $em(UDP socket),
   i.e.  a  object of type  $att(UDP_Socket).  If you  send an UDP  packet on a  socket (using
   $att(udp_send)), you  get the  answer (one or  several packets)  on the same  socket (using
   $att(udp_receive)).$p

   $att(UDP_Socket) is an opaque type.
   $acode(
public type UDP_Socket:...
   )
   For creating an UDP socket as a  client, you don't need to provide any argument because
   the local  address:port is assigned automatically  by the system, and  you will provide
   the  destination address:port  when sending  data.   You can  use the  same socket  for
   sending packets to different addresses.
   $acode(
public type Create_UDP_Client_Socket_Result:
   cannot_create_the_socket, // maybe there are already too many sockets in the system
   ok(UDP_Socket).

public define Create_UDP_Client_Socket_Result
   create_udp_client_socket.

public define Create_UDP_Client_Socket_Result
   create_udp_client_broadcast_socket.
   )


   $subsubsection(Sending and receiving UDP packets)

   Once you have your UDP client socket at hand, you can send packets. You must provide as
   arguments the UDP client socket, the destination address:port and the data to be sent.$p

   There is no  warranty that the packet  will arrive at destination. The  only thing that
   the system can check is that it has access to the network.
   $acode(
public type UDP_Send_Result:
   network_unreachable,
   packet_sent.

public define UDP_Send_Result
   udp_send
     (
       UDP_Socket        socket,
       Word32            ip_address,  // where you want to send the data
       Word32            ip_port,
       ByteArray         data
     ).
   )

   Use the  primitive $att(udp_receive) for  waiting for the  answer from the UDP  server. You
   must know an  upper bound (named $att(max_packet_size) below) on the  length of the packets
   you are  going to  receive. If this  bound is  too small, the  received packets can be
   truncated, and some data will be irremediably lost. You must also provide a timeout.$p

   The  response you receive (if  any, before  time is  out, and  if the  network is
   reachable) includes  the data sent by the remote UDP system, the  indication that this
   data are truncated or not, and the address:port of the remote (sending) system.
   $acode(
public type Truncation:
   truncated,
   not_truncated.

public type UDP_Receive_Result:
   out_of_time,
   network_unreachable,
   ok(ByteArray  data,
      Truncation t,
      Word32      ip_address,   // IP address:port of the host who sent the packet
      Word32      ip_port).

public define UDP_Receive_Result
   udp_receive
     (
       UDP_Socket        socket,
       Word32            max_packet_size,
       Word32            timeout     // seconds
     ).
   )


   $subsubsection(Starting an UDP server ($att(start_udp_server)))

   You may  also want  to start  an UDP  server.  The server  itself is  an object  of the
   following opaque type:
   $acode(
public type UDP_Server:...

public type Start_UDP_Server_Result:
   cannot_create_the_socket,      // probably too many sockets alread opened
   cannot_bind_address_port,      // the address:port is invalid or already in use
   access_denied,                 // you must be superuser for using this port
   ok(UDP_Server).
   )
   In order to  start an UDP server, you  must provide an IP address and  port. IP address
   $att(0) means that the  server will listen on all interfaces of  the machine. You must also
   provide a $em(handler)  fonction whose task is to answer queries.   Of course, the handler
   function is called each time from within  a new virtual machine, so that the server may
   answer several clients at  the same time.  The maximal size of  packets the server will
   receive must  be known by  advance. It is  given as an argument  to $att(start_udp_server).
   The function $att(notify) is executed by the server each time there is a problem.$p

   The handler  function receives the following informations:
   $list(
     $item the UDP socket through which the answer must be sent,
     $item the query (the message received by the server),
     $item the indication that the query is truncated or not,
     $item the IP address:port of the client.
   )
   $comment(to do: 'max_packet_size' should be an Int.)
   $acode(
public define Start_UDP_Server_Result
   start_udp_server
     (
       Word32                       ip_address,  // address on which the server will listen
                                                 //    0 means: 'listen on all interfaces'
       Word32                       ip_port,     // port on which the server will listen
       (UDP_Socket,
        ByteArray,
        Truncation,
        Word32   ip_address,
        Word32   ip_port) -> One    handler,     // the function for handling the queries
       Word32                       max_packet_size,   // maximal size of queries
       One -> One                   notify       // used when something wrong happens
     ).
   )
   You can test if an UDP server was shutdown.
   $acode(
public define Bool      is_down(UDP_Server server).
   )
   You can also shutdown the UDP server you created with $att(start_udp_server).
   $acode(
public define One       shutdown(UDP_Server server).
   )


   $end


      *** (6.8) Low level sockets.


public type SocketLinger:
   linger(Bool       onoff,
          Word16     timeout).

public type SocketOption:
   // Socket level
   so_broadcast(Bool),         // Allows transmission of broadcast messages on the socket.
   so_debug(Bool),             // Records debugging information.
   so_dontroute(Bool),         // Does not route: sends directly to interface.
                               //   Not supported on ATM sockets (results in an error).
   so_keepaline(Bool),         // Sends keep-alives. Not supported on ATM sockets (results in an error).
   so_linger(SocketLinger),    // Lingers on close if unsent data is present.
   so_rcvbuf(Word32),          // Specifies the total per-socket buffer space reserved for receives.
                               //   This is unrelated to SO_MAX_MSG_SIZE or the size of a TCP window.
   so_sndbuf(Word32),          // Specifies the total per-socket buffer space reserved for sends.
                               //   This is unrelated to SO_MAX_MSG_SIZE or the size of a TCP window.
   so_reuseaddr(Bool),         // Allows the socket to be bound to an address that is already in use.
                               //   (See bind.) Not applicable on ATM sockets.
   // TCP level
   tcp_nodelay(Bool).          // Disables the Nagle algorithm for send coalescing.


public type SocketError:
    proto_no_supported,      // EPROTONOSUPPORT The protocol type or the specified protocol is not
                             //   supported within this domain.
    family_not_supported,    // EAFNOSUPPORT The implementation does not support the specified address
                             //   family.
    out_of_kernel_memory,    // ENFILE Not enough kernel memory to allocate a new socket structure.
    out_of_entry,            // EMFILE Process file table overflow.
    no_permission,           // EACCES Permission to create a socket of the specified type and/or
                             //   protocol is denied.
    out_of_memory,           // ENOBUFS or ENOMEM Insufficient memory is available. The socket
                             //   cannot be created until sufficient resources are freed.
    invalid_proto_or_family, // EINVAL Unknown protocol, or protocol family not available.
    other_error(Word32).     // Other errors may be generated by the underlying protocol modules.

public type SocketOptionError:
   bad_socket,                 // EBADF The argument s is not a valid descriptor.
   bad_address,                // EFAULT The address pointed to by optval is not in a valid part of
                               //   the process address space. For getsockopt(), this error may also
                               //   be returned if optlen is not in a valid part of the process address
                               //   space.
   bad_optlen,                 // EINVAL optlen invalid in setsockopt().
   unknown_option,             // ENOPROTOOPT The option is unknown at the level indicated.
   not_a_socket,               // ENOTSOCK The argument s is a file, not a socket.
   unknown.                    // All other errors.

public type BindError:
   no_permission,              // EACCES The address is protected, and the user is not the superuser.
   addr_in_use,                // EADDRINUSE The given address is already in use.
   bad_socket,                 // EBADF sockfd is not a valid descriptor.
   already_bound,              // EINVAL The socket is already bound to an address.
   not_a_socket.               // ENOTSOCK sockfd is a descriptor for a file, not a socket.

public type CreateSocketError:
  socket_error(SocketError),
  option_error(SocketOptionError),
  bind_error  (BindError).

public type RecvError:
   no_data,             // EAGAIN   The socket is marked non-blocking and the receive operation would
                        //   block, or a receive timeout had been set and the timeout expired before
                        //   data was received.
   bad_socket,          // EBADF    The argument s is an invalid descriptor.
   connection_refused,  // ECONNREFUSED A remote host refused to allow the network connection
                        //   (typically because it is not running the requested service).
   interrupted,         // EINTR     The receive was interrupted by delivery of a signal before any
                        //   data were available.
   invalid_argument,    // EINVAL  Invalid argument passed.
   out_of_memory,       // ENOMEM    Could not allocate memory for recvmsg().
   not_connected,       // ENOTCONN  The socket is associated with a connection-oriented protocol and
                        //   has not been connected (see connect(2) and accept(2)).
   not_a_socket,        // ENOTSOCK  The argument s does not refer to a socket.
   other_error.         // Other unknown error


public type SendError:
   no_permission,       // EACCES (For Unix domain sockets, which are identified by pathname)
                        //   Write permission is denied on the destination socket file, or search
                        //   permission is denied for one of the directories the path prefix.
                        //   (See path_resolution(2).)
   would_block,         // EAGAIN or EWOULDBLOCK The socket is marked non-blocking and the requested
                        //   operation would block.
   bad_socket,          // EBADF    An invalid descriptor was specified.
   connection_reset,    // ECONNRESET Connection reset by peer.
   dest_addr_required,  // EDESTADDRREQ The socket is not connection-mode, and no peer address is set.
   interrupted,         // EINTR     A signal occurred before any data was transmitted.
   invalid_argument,    // EINVAL  Invalid argument passed.
   is_connected,        // EISCONN   The connection-mode socket was connected already but a recipient
                        //   was specified. (Now either this error is returned, or the recipient
                        //   specification is ignored.)
   msg_size,            // EMSGSIZE  The socket type requires that message be sent atomically, and
                        //   the size of the message to be sent made this impossible.
   queue_is_full,       // ENOBUFS  The output queue for a network interface was full. This
                        //   generally indicates that the interface has stopped sending, but may
                        //   be caused by transient congestion. (Normally, this does not occur in
                        //   Linux. Packets are just silently dropped when a device queue overflows.)
   out_of_memory,       // ENOMEM    No memory available.
   not_connected,       // ENOTCONN  The socket is not connected, and no target has been given.
   not_a_socket,        // ENOTSOCK  The argument s is not a socket.
   flag_not_supported,  // EOPNOTSUPP  Some bit in the flags argument is inappropriate for the socket type.
   localy_closed,       // EPIPE The local end has been shut down on a connection oriented socket.
                        //   In this case the process will also receive a SIGPIPE unless MSG_NOSIGNAL
                        //   is set.
   other_error.         // Other unknown error

         *** () Packet sockets:

public type PacketSocket:...

public type PacketSocketProtocol:
   eth_p_all,                   /* Every packet (be careful!!!)            */
   eth_p_loop,                  /* Ethernet Loopback packet                */
   eth_p_ip,                    /* Internet Protocol packet                */
   eth_p_arp,                   /* Address Resolution packet               */
   eth_p_rarp,                  /* Reverse Addr Res packet                 */
   eth_p_8021Q,                 /* 802.1Q VLAN Extended Header             */
   eth_p_ipx,                   /* IPX over DIX                            */
   eth_p_ipv6,                  /* IPv6 over bluebook                      */
   eth_p_ppp_disc,              /* PPPoE discovery messages                */
   eth_p_ppp_ses,               /* PPPoE session messages                  */
   eth_p_mpls_uc,               /* MPLS Unicast traffic                    */
   eth_p_mpls_mc,               /* MPLS Multicast traffic                  */
   eth_p_atmmpoa,               /* MultiProtocol Over ATM                  */
   eth_p_atmfate,               /* Frame-based ATM Transport over Ethernet */
   eth_p_aoe,                   /* ATA over Ethernet                       */
   eth_p_tipc,                  /* TIPC                                    */
  /*
   *  Non DIX types. Won't clash for 1500 types.
   */
   eth_p_802_3,                 /* Dummy type for 802.3 frames             */
   eth_p_ax25,                  /* Dummy protocol id for AX.25             */
   eth_h_802_2,                 /* 802.2 frames                            */
   eth_h_tr_802_2.              /* 802.2 frames                            */

public type PhysicalAddress:...
public define PhysicalAddress
   mac_address(Word8 lowest, Word8 b1, Word8 b2, Word8 b3, Word8 b4, Word8 highest).
public define PhysicalAddress
   generic_address(Word8 lowest, Word8 b1, Word8 b2, Word8 b3, Word8 b4, Word8 b5, Word8 b6, Word8 highest).

public type PacketSocketAddress:
   packet_sockaddr(PacketSocketProtocol protocol,   /* Physical layer protocol */
                   Word32               ifindex,    /* Interface number */
                   Word16               hatype,     /* Header type */
                   Word8                pkttype,    /* Packet type */
                   PhysicalAddress      physaddr).  /* Physical layer address */

public type PacketSocketType:
   sock_raw,
   sock_dgram.


public define Result(CreateSocketError, PacketSocket)
   create_packet_socket
     (
       PacketSocketType           type,
       PacketSocketProtocol       protocol,
       List(SocketOption)         options,
       Maybe(PacketSocketAddress) addr,
     ).


         *** () Internet sockets:

public type IpAddress:
   ip_address(Word32).
to do: think about a general definition of a type of IP addresses.

   Remember: ip should be stored in reverse order.

public define IpAddress inaddr_loopback.
public define IpAddress inaddr_any.
public define IpAddress inaddr_broadcast.


public type InternetSocketProtocol:
  ipproto_udp,
  ipproto_tcp.

public type SocketType:
   sock_raw(InternetSocketProtocol  protocol),
   sock_dgram,
   sock_stream.

public type Socket:...

public type InternetSocketAddress:
  inet_sockaddr(IpAddress       ip,        /* internet address */
                Word16          port).     /* TCP / UDP port */

public define Result(CreateSocketError, Socket)
   create_socket
     (
       SocketType                   type,
       List(SocketOption)           options,
       Maybe(InternetSocketAddress) addr,
     ).


         *** () Sending data.

public type SendFlags:...

public define SendFlags no_flag.

public define SendFlags msg_dontroute.

   This is the MSG_DONTROUTE flag under Unix.  Don't use a gateway to send out the packet,
   only  send to  hosts  on directly  connected networks.  This  is usually  used only  by
   diagnostic or routing programs. This is  only defined for protocol families that route;
   packet sockets don't.

public define SendFlags msg_more.

   This is the MSG_MORE  flag under Unix. (Since Linux 2.4.4) The  caller has more data to
   send. This  flag is used  with TCP sockets  to obtain the  same effect as  the TCP_CORK
   socket option (see tcp(7)), with the difference that this flag can be set on a per-call
   basis.

   Since Linux 2.6, this flag is also supported for UDP sockets, and informs the kernel to
   package all of the  data sent in calls with this flag set  into a single datagram which
   is only transmitted when a call is performed that does not specify this flag. (See also
   the UDP_CORK socket option described in udp(7).)

public define SendFlags msg_nosignal.

   This is the  MSG_NOSIGNAL flag under Unix.   Requests not to send SIGPIPE  on errors on
   stream oriented  sockets when the other end  breaks the connection. The  EPIPE error is
   still returned.

public define SendFlags  msg_out_of_band.

   This is  the MSG_OOB flag  under Unix. Sends  out-of-band data on sockets  that support
   this  notion (e.g.  of  type SOCK_STREAM);  the underlying  protocol must  also support
   out-of-band data.

   Flags may be combined (ORed) with:

public define SendFlags SendFlags x | SendFlags y.

public define Result(SendError, Word32)
  sendto
    (
      PacketSocket                socket,
      ByteArray                   data,
      Maybe(PacketSocketAddress)  mb_dest,
      SendFlags                   flags
    ).


         *** () Receiving data.

public type RecvFlags:...

public define  RecvFlags no_flag.

public define  RecvFlags msg_peek.

   MSG_PEEK This  flag causes the receive operation  to return data from  the beginning of
   the receive queue without removing that data from the queue. Thus, a subsequent receive
   call will return the same data.

public define RecvFlags msg_out_of_band.

   MSG_OOB This  flag requests receipt of out-of-band  data that would not  be received in
   the normal data stream.  Some protocols place  expedited data at the head of the normal
   data queue, and thus this flag cannot be used with such protocols.


public define RecvFlags RecvFlags x | RecvFlags y.

public define Result(RecvError, (ByteArray, PacketSocketAddress))
   recvfrom
     (
       PacketSocket  socket,
       Word32        size,
       RecvFlags     flags
     ).


   $begin

   $subsection(Miscellaneous tools)

   $subsubsection(Executing an operating system command ($att(execute)))

   The primitive $att(execute)  allows the execution of a command of  your operating system as
   if you typed it on the command line in a console.$p

   Execution of  $att(execute) does not block  $att(anbexec).  It blocks only  the virtual machine
   which uses this  primitive. It works by  $em(forking) (in the UNIX sens),  i.e. starting a
   new UNIX  thread which will handle the  execution of the system  command.  The original
   thread  continues  to  execute  the   Anubis  scheduler,  i.e.  to  run  other  virtual
   machines. This is the reason why other virtual machines don't block.

   $comment(to do: check if return codes are actually Word8.)
   $acode(
public define Maybe(Word8)
   execute
     (
       Maybe(String)   mb_execution_directory,
       String          program_name,
       List(String)    operands
     ).
   )
   The return  value is $att(failure) if  an error occured  (for example, the program  was not
   found). Otherwise,  the return value  is $att(success(n)), where  $att(n) is the  (host system)
   return code of the command.$p

   The first operand  is the (non mandatory) execution directory,  i.e. the directory from
   within which the command will be executed. $att(failure) means: use the current directory.$p

   $att(program_name) is the name  of the program to be executed. It  is not necessary to give
   its full path,  because $att(execute) uses the  value of the shell variable  $tt(PATH) to find
   the program.$p

   The operands are all those that you want to put after the name of the program.$p

   The following convenience functions are provided:
   $acode(
public define Maybe(Word8)
   execute
     (
       String       program_name,
       List(String) operands
     ).

public define Maybe(Word8)
   execute
     (
       String       execution_directory,
       String       program_name,
       List(String) operands
     ).
   )


   $subsubsection(Capturing the output of $att(execute))

   $comment(to do: create unit tests for 'execute' (all versions).)

   The commands you are executing with  $att(execute) can produce output (through $att(stdout) and
   $att(stderr)).  You may want  to capture  these outputs. You may also want to feed them
   through their $att(stdin).  In this  case, use  the following primitive instead of the
   previous one.
   $acode(
public type ExecuteControl:...

public define Maybe(ExecuteControl)
   execute
     (
       Maybe(String)     mb_execution_directory,
       String            program_name,
       List(String)      operands
     ).
   )
   This function returns immediately without waiting.  If the result is not $att(failure), the
   execution is on the  way. In this case you get a datum  of type $att(ExecuteControl). The three
   implict   destructors  provide  the   necessary  stuff   for  controling   the  process
   executed. Assuming  that this datum of  type $att(ExecuteControl) is called  $att(ec), you have
   the following at hand:$p

   $list(
   $item of type $att(WStream):
      $list(
        $item $att(process_stdin(ec))   this writable connection is linked to the standard input
                       of the program executed. You can send data to the program
                       through this connection,
            )
   $item of type $att(RStream):
      $list(
        $item $att(process_stdout(ec))  the last two elements are linked to the standard output and
        $item $att(process_stderr(ec))  standard error output of the program executed. Through them
                       you can recover the output of the program executed.
          )
   )
   Now, you  may also want  to know if the  execution is finished  and if it is  the case,
   which code it returned. To that end use the following:
   $acode(
public type ExecuteStatus:
   still_running,
   abnormal_termination,
   finished(Word8 code).

public define ExecuteStatus
   check_execute_status
     (
       ExecuteControl   ec
     ).
   )
   $bold(Note:)  The child  process  is completely  liberated  when the  $att(ExecuteControl) objet  is
   garbage-collected.
   $comment(to do: Check the liberation of child processes.)


   $subsubsection(Random numbers ($att(random)))
   $acode(
public define Word32                 random(Word32 n).
   )
    $comment(to do: create a Int random(Int).)


   $att(random(n)) returns a random number between $att(0)  (inclusive) and $att(n) (exclusive).  If $att(n =< 1),
   it returns  always $att(0).  This random number  generator is seeded using  current number of
   microseconds  each   time  the  program  starts.    Its  quality  is   not  enough  for
   cryptographical purpose.


   $subsubsection(Date and time ($att(Date_and_Time), $att(now), $att(convert_time)))

   $comment(to do: create a type Time. 'now' should return a Time.)
   $acode(
public define Int            now.
   )
   $att(now) gives the  number of seconds since the $em(epoch) (January  1st 1970, 00:00:00). The
   result is UTC (aka GMT) time, i.e. the time at Greenwich.
   $acode(
public type UTime:
   utime(Int     seconds,
         Int     microseconds).

public define UTime            unow.
   )
   This variant returns a  pair $att(utime(s,m)) of two integers. The first  one is the number
   of seconds since the epoch, and the second one is the number of microseconds within the
   current second. This is also UTC time.

   $acode(
public type Date_and_Time:
  date_and_time(
    Int year,
    Int month,                    // from 1 = January to 12 = December
    Int day,                      // from 1 to 31
    Int hour,                     // from 0 to 23
    Int minute,                   // from 0 to 59
    Int second,                   // from 0 to 59
    Int week_day,                 // from 0 = sunday to 6 = saturday
    Int year_day,                 // from 0 = January 1st, to at most 365
    Bool  daylight_saving_time).  // if 'true' daylight saving time is applied
   )
   Time represented as a  datum of type $att(Date_and_Time) is supposed to  be local time, not
   UTC time.$p

   Time can  be converted to and fro  between $att(Int) (UTC time)  and $att(Date_and_Time) (local
   time).
   $acode(
public define Date_and_Time     convert_time(Int t).
public define Int               convert_time(Date_and_Time d).
   )
   $bold(Note:)  Of course, the  last function  does not  use the  two components  $att(week_day) and
   $att(year_day) in its computation.
   $acode(
public define One      set_time(UTime time).
   )
   This  function  sets the  system  time.  Under UNIX-like  systems  you  must have  root
   permission for setting time. The argument must be UTC time.$p

   See the $ref(sntp)(SNTP tools) (Simple Network Time Protocol) for how to get time from network servers.

   $acode(
public define One      set_time_zone(String time_zone_name).
   )
   This function  sets the system  time zone. Under  UNIX-like systems you must  have root
   permission for  setting the  time zone. The  argument $att(time_zone_name) is  the official
   name of the time zone.


   $end

   todo: Move the stuff below to another place, and comment it.


public define List($T)   reverse_append(List($T) l1, List($T) l2).
public define List($T)   reverse(List($T) l).
public define List($T)   append(List($T) l1, List($T) l2).
public define Bool       member(List($T) l,$T x).


   Let l be the  list (say) [a_1, a_2, a_3], whose elements are  of type $A, then map(f,l)
   computes:

      [f(a_1), f(a_2), f(a_3)]

public define List($B)
  map
    (
       $A -> $B    f,
       List($A)    l
    ).


    $begin

    $subsubsection(Reading a password from standard input ($att(get_password)))

   This command gets  a password  from standard  input. On  the console,  characters are
   replaced by $tt(*).
   $acode(
public define String      get_password.
   )


   $subsubsection(Loading a (secondary) $fname(.adm) module during execution)

   This is new to version 1.13. Up to this version (2013/07), $att(anbexec) was only able
   to execute one and only one $fname(.adm) file. The $em(datum) in this $fname(.adm) file was
   in all cases a function of type:$par

         $center($att(List(String) -> One)   ~~~~~  or  ~~~~~ $att(List(String) -> Word8))

   defined by a $att(global define) paragraph, where the argument represents the list of
   command line arguments, and the return type is either $att(One) if we don't care to
   return a UNIX execution code, or $att(Word8) if we want to return an execution code.$p

   From version 1.13, the datum stored in a $fname(.adm) file can have (almost) any type,
   and the $fname(.adm) file can be loaded dynamically during execution of $att(anbexec) in
   the same way as many systems load $em(external libraries).$p

   However, from now on, we have two kinds of modules:

    $list(
      $item $em(Primary modules), defined as:$par

       $center($att(global define One/Word8 name (List(String) args) =) ...)

      and the corresponding $fname(.adm) file can be given as a command line argument to anbexec.$p

      $item  $em(Secondary modules), defined as:$par

       $center($att(global define T name =) ...)
   )
   where $att(T) can be (almost) any type. The corresponding $fname(.adm) file cannot be given as
   a command line argument to $att(anbexec), but can be loaded dynamically during execution
   of $att(anbexec).$p

   $bold(Note:) $list(
      $item primary modules have an argument of type $att(List(String)),
      $item secondary modules have no argument at all.
      )

   For example, if you want to produce an Anubis library (secondary module) whose
   interface is made of several data definitions (which can be functions), you may
   write something like:
   $ecode(
   global define MyLibrary
      my_library
        =
      lib
        (
          // tools (maybe functions) available in this library:
          do_something,
          do_another_thing,
          compute_something,
          ...
        ).
   )
   This will produce the file $fname(my_library.adm) (stored in $fname(my_anubis/modules) as usual)
   and the $em(type) of this module file will be $att(MyLibrary), a type of your own.$p

   Also notice that a $att(global) paragraph cannot be a schema (you cannot have things
   like $att($T) in its definition).$p

   Now, how to use a secondary module ? Within your program you can write the following
   term:$par

      $center($att((LoadAdm(T))load_adm($nt(name))))

   where $nt(name) (any expression of type String) is the name (or path) of the $att(.adm) file
   to be loaded. The type of $att(load_adm($nt(name))) is $att(LoadAdm(T)) where $att(T)
   is the type of the secondary module (as declared in $att(global define T name =) $tt(...)). For
   example, if $att(name) is defined as:
   $ecode(
   global define String
      interesting_string
        =
      "blablabla".
   )
   the type of the module $fname(interesting_string.adm) will be $att(String). Of course, this example is quite particular, but
   it is possible to store a string onto a secondary module and to load it dynamically. For
   example, you could store dictionnaries of the same type for various natural languages into
   secondary modules and load only the required one at execution.$p

   The type schema $att(LoadAdm($T)) is the following:
    $acode(
public type LoadAdm($T):
     file_not_found,              // the .adm file has not been found (see below)
     read_error,
     timeout,
     file_damaged,                // checksum error
     bad_version(String expected, // the module was not compiled with the right
                 String found),   // version of Anubis (typically an older one)
     wrong_type(String  expected, // the type of the module is not 'T'
                String  found),   //   (expected = T, found = actual type of module)
     ok($T).                      // you got your datum !
     )
   Notice that $att(expected) and $att(found) are ready-to-print (human readable) strings.

   $acode(
public define LoadAdm($T)
   load_adm
     (
       String     adm_file_name     // path
     ).
   )
   $att(adm_file_name) can be a relative or absolute file path. If relative, it is relative to the
   anbexec current execution directory. However, if not found, it is also searched for in
   $fname(my_anubis/modules), i.e. at the place it was created.$p

   You can also master the timeout for read operations (timeout is 10 seconds if you
   don't give it as shown above):
   $acode(
public define LoadAdm($T)
   load_adm
     (
       String     adm_file_name,     // path
       Int        timeout            // timeout for read operations (in seconds)
     ).
   )
   You can see the type of $fname(name.adm) file by executing:

   $ecode(anbexec name --info)

   The type of the module is the last expression in the description. It is preceded
   by the definitions of all the required types.
   The format is exactly the same as that of $att(expected) and $att(found) in
   the $att(wrong_type) alternative of $att(LoadAdm($T)).$p

   $bold(Practical issue:) If you decide to make a module for dynamic loading via $att(load_adm),
   you need to ensure that the calling module and the called module share the same
   definition of the type of the called module. One clean way of doing this without
   recompiling the called module while compiling the calling module (which is one of the
   advantages of this new feature, since it will drasticaly reduce compilation time),
   is to have an Anubis file containing the type definitions required by the called module
   and nothing more. This file must be $att(read) by both module sources, hence is compiled when
   the calling module is compiled and also compiled when the called module is compiled.
   However, the compilation of this common file should not last much since it is assumed to
   contain only type definitions, not the complete module sources. Beware of $att(read)'s within
   this file, which could lead to recompile too many things. In most cases,you don't need many
   $att(read) in this common $em(module type definition) file. These $att(read) should refer to files
   also containing only type definitions.


   $subsection(Dynamic Variables ($att(Var(T)), $att(MVar(T)), $att(var), $att(mvar) and monitoring))


   $subsubsection(Creating, reading and writing.)


   Dynamic variables are locations (in computer memory) which contain a datum.  Their type is
   $att(Var(T)), where  $att(T) is the type  of the content  of the variable. Dynamic  variables are
   created by:
   $acode(
public define Var($T)         var($T init).
   )
   where $att(init)  is the initial value  (i.e. content) of the  variable.  Dynamic variables
   are not local variables  in the usual sens. Indeed, you can  create a dynamic variable,
   and return it as  the result of a function. You can also  create a dynamic variable and
   use $att(delegate)  to start another  virtual machine.  If the term  to be executed  by the
   other machine refers  to the variable, it  will be available to the  two machines. This
   allows communication between virtual machines. Indeed, dynamic variables can be seen as
   some  kind of mail  boxes, through  which virtual  machines can  transmit data  to each
   other.  But of  course, dynamic  variables may  also  be used  to store  the states  of
   automatons, as described below.$p

   Reading  the value  (content) of  such a  dynamic variable  $att(v) (of  type  $att(Var(T))) is
   performed by:$par

                     $center($att(*v))

   which  is of  type $att(T).  Writing a  value  $att(a) (of  type $att(T))  into the  variable $att(v)  is
   performed by:$par

                 $center($att(v <- a))

   which is of type $att(One). Now, you may  also want to exchange the content of the variable
   with a new value. The following term performs the exchange:$par

                               $center($att(v <-> a))

   It  puts  the value  $att(a)  in  the  variable, and  returns  the  previous value  of  the
   variable. As a consequence, $att(v <-> a) is  of type $att(T), not of type $att(One) (except if $att(T)
   is $att(One) of course).$p

   $bold(Warning:) exchanging:$par

            $center($att(v <-> a))

   is not equivalent with:$par

            $center($att(with old = *v,
              v <- a;
              old))

   This is because,  the value of the  variable can be changed by  another virtual machine
   between $att(*v) and $att(v <- a).$p


   For example, if you want to construct some  kind of automaton, you may provide a set of
   variables in order to store its state. You may write something like this:
   $ecode(
   type AutomatonState:
     state(Var(Int)          x,
           Var(List(String)) l).
   )
   Here, the  state of the  automaton is described  by an integer  and a list  of strings.
   Creating the automaton amounts to create a datum of type $att(AutomatonState):

     $center($att(state(var(0),var([]))))

   assuming that in  the initial state, the values  of $att(x) and $$att(l) are $att(0)  and $att([]). This
   state may be transmitted as an argument to the transition function of the automaton, or
   even better, the transition function can be defined (using the sign '|->') in a context
   containing the state, and hence can refer to it.$p

   Of course,  the garbage-collector manages  automatically the destruction of  this state
   (including the variables and their contents) precisely when it is no more used.$p

   However, assigning a value to a variable using $att(v  <- a) or $att(v <-> a), is a $em(surgery) which
   can create  loops in reference  counting.  For example  you may have defined  a (silly)
   recursive type like this:
   $ecode(
   type T:
     a,
     b(Var(T)).
   )
   and created a variable $att(u) of type $att(Var(T)), with initial value $att(a):$par

          $center($att(with u = var((T)a)))

   Later, you may write:$par

            $center($att(u <- b(u)))

   The result is that $att(u) refers to its  value $att(b(u)), which refers to $att(u). This creates a
   loop  in reference  counting.  The  garbage-collector is  not able  to handle  loops in
   reference counting. This means that the memory  used for holding $att(u) and its value will
   never  be  collected.   This  piece  of   memory  will  never  be  reused  for  another
   purpose. This has no other inconvenient,  in particular this will not crash the system.
   Nevertheless you should  avoid creating such loops, which are  in any case meaningless.
   A future version of the compiler may include a tool for detecting (and forbidding) such loops.$p

   Since dynamic variables are physical  (versus abstract) objects, it is sometimes useful
   to have  some way of  precisely identifying a  variable. In some sens  variables should
   have some kind of $em(identity number).  Actually, it is the case, and the identity number
   of a variable (which non ambiguously identifies the variable) is given by:
   $acode(
public define Word32        var_id(Var($T) v).
   )


   $subsubsection(Multiple dynamic variables)

   You  can also use  $em(multiple dynamic  variables), which  are almost  the same  thing as
   $em(tables) in other languages. The difference with the previous dynamic variables is that
   the multiple variable may hold not only one datum of type T, but several. Each datum is
   stored into a  location called a $em(slot) of the multiple  variable. A multiple dynamic
   variable is created by $att(mvar) below, where $att(n)  is the number of slots you want to have
   in the  variable, and $att(init) the  initial value of all  the slots of  the variable. The
   type of a multiple variable holding data of type $att(T) is $att(MVar(T)).

   $comment(to do: mvar(Word32,$T) should be mvar(Int,$T).)
   $acode(
public define MVar($T)
   mvar
     (
       Word32 n,     // number of slots in the variable you want to create
       $T init       // initial value for all slots
     ).
   )
   Notice that if $att(n < 1), $att(n) is replaced by $att(1) and no virtual copy of $att(init) is needed.$p

   The compiler implements  multiple dynamic variables in a  reasonably efficient way. The
   number of bits allocated  for each slot is the least power of  2 able to accomodate the
   data. So  for example, if you  create a multiple dynamic  variable containing booleans,
   each slot occupies just 1 bit in computer memory. if you use $att(Maybe(Bool)) for example,
   whose cardinality is 3, each slot occupies 2  bits, because 2^2 is the least power of 2
   greater than or equal to 3. If you  use $att(Word8), each slot occupies 8 bits.  If you use
   $att(RGB),  whose bit  width is  24, each  slot occupies  32 bits  (the same  as for  $att(RGBA) or
   $att(Word32)). Of course, in the case of $att(RGB), 8 bits are wasted in each slot.$p

   Reading and  writing a multiple variable  is performed slot  by slot. If the  term $att(mv)
   represents a multiple variable with $att(n) slots,

            $att(mv(i))

   (where $att(i) is a $att(Word32) such that $att(0 =<  i < n)) represents the $att(i)$sup(th) slot of the variable.
   However, $att(mv(i)) is not a term of the language, it is only used in the following terms:
   $list(
      $item   $box(100)($att(*mv(i)))            which allows to read the value of the $att(i)$sup(th) slot of $att(mv),
      $item   $box(100)($att(mv(i) <- a))        which puts $att(a) into the $att(i)$sup(th) slot of $att(mv),
      $item   $box(100)($att(mv(i) <-> a))       which puts $att(a) in the $att(i)$sup(th) slot of $att(mv), and returns the
                                previous value of this slot.
   )

   These terms  are meaningful  only if $att(0  =< i  < n). If  it is not  the case,  the system
   replaces $att(i) by $att(0) if  $att(i < 0), and by $att(n-1) if $att(i >= n). Of  course, for a multiple variable of
   type $att(MVar(T)), $att(*mv(i)) is of type $att(T), $att(mv(i)  <- a) of type $att(One), and $att(mv(i) <-> a)
   of type $att(T).$p

   You can recover the number of slots in a multiple dynamic variable with:

   $comment(to do: length(MVar($T)) should return an Int.)
   $acode(
public define Word32      length(MVar($T) mv).
   )

   Multiple variables also have an identification number, given by:
   $acode(
public define Word32        mvar_id(MVar($T) mv).
   )


   $subsubsection(Monitoring)


   Dynamic variables may  be $em(monitored).  $em(Monitoring) a variable  means attaching to the
   variable  a function of  type $att(One -> One)  ($att(Word32 ->  One) for  multiple variables)
   called a  $em(monitor), which  will be  executed each time  the value  of the  variable is
   set. Attaching such a  function to a variable is called $em(registering a monitor at the
   variable).   When you  register a  monitor at  a variable,  you receive  a $em(monitoring
   ticket) of the following opaque type:
   $acode(
public type MonitoringTicket($T):...
   )
   The registration is performed by the following command (for non multiple variable):
   $acode(
public define MonitoringTicket($T)
   register_monitor
     (
       Var($T)      variable,
       One -> One   monitor
     ).
   )
   The  variable   is  monitored  until  the   monitoring  ticket  is   destroyed  by  the
   garbage-collector. Hence, despite the fact that you cannot do much with the ticket, you
   must keep it somewhere all the time you want your variable to be monitored.$p

   When the  value of the  variable is set,  copies of all  the monitors attached  to this
   variable  are queued  in a  special $em(monitoring  queue). The  scheduler  executes these
   monitors (on the argument $att(unique)).$p

   Notice that the monitors  are executed every time the variable is  set, even if the new
   value is  the same as the  previous one. For example,  you may have a  variable of type
   $att(Var(One)).   The sole  value this  variable may  hold is  $att(unique).  Nevertheless, the
   monitors attached to this variable will be executed each time the value $att(unique) is put
   into the variable.$p

   Monitoring  does not  create  any problem  of  garbage-collection, because  no loop  in
   reference counting  is created.   However, monitoring may  create other  problems, like
   oscillators. For example, imagine that you  have a boolean variable $att(u), initialized at
   $att(true), and that you monitor this variable as follows:$par

       $center($att(register_monitor(u,(One _) |-> (u <- false))))

   If the  value of  the variable  is changed to  $att(false), the  monitor will  be executed,
   changing the value again to $att(false) (which  is not actually a change of value, but will
   nevertheless be considered  as such). But this implies a new  execution of the monitor,
   and so on indefinitly.$p

   Actually, the problem is comming (as  usual) from a circular reference: the variable is
   monitored by  a monitor which changes the  value of the variable  itself.  Consider the
   graph whose vertices are all pairs $att((v,m)),  where $att(v) is a dynamic variable, and $att(m) a
   monitor attached to  $att(v). For each pair of such pairs  $att((v_1,m_1)) and $att((v_2,m_2)), put
   an  arrow from  $att((v_1,m_1))  to $att((v_2,m_2))  if $att(m_1)  performs  a change  of value  of
   $att(v_2). There is a problem if this graph contains a cycle.$p

   For the time  being no mecanism is implemented for checking this  graph, and the
   user must be careful.$p

   Also, notice  that the monitors for  a given dynamic  variable $att(v) are executed  by the
   virtual machine which reassigns the variable, not by the virtual machine which attached
   the monitor. Also, if two virtual machines reassign a variable almost at the same time,
   the monitors  can be executed in parallel  by the two machines.  In some circumstances,
   this may create problems.$p

   $end

   Multiple variables  may also be monitored. However,  the monitor is of  type $att(Word32 ->
   One).  When  the value  of a slot  of the  multiple variable is  assigned a  value, the
   monitor is called with the index of  this slot as its argument. Register such a monitor
   with:

   $acode(
 public define MonitoringTicket($T)
   register_monitor
     (
       MVar($T) multiple_variable,
       Word32 -> One monitor
     ).
   )
   As for simple  dynamic variables, the multiple dynamic variable  is monitored until the
   monitoring ticket is collected by the garbage-collector.

   $begin


   $subsection(Serialization, saving and transmitting data)

   $subsubsection(Serializing and unserializing)

   Given a datum of almost any type, you can $em(serialize) it. This means that this datum is
   transformed into a byte array. This is achieved by:
   $acode(
public define ByteArray       serialize($T d).
   )
   If the type choosen is not  serializable, the compiler will complain. Conversely a byte
   array can be $em(unserialized) using:
   $acode(
public define Maybe($T)       unserialize(ByteArray s).
   )
   However, an  arbitrary byte array  may perhaps  not unserialize to  a datum of  a given
   type.  This is why  the result is not of type $att($T),  but of type $att(Maybe($T)). Nevertheless,
   if the datum $att(d) is serializable, we always have:$par

                          $center($att(unserialize(serialize(d)) = success(d)))

   In many cases, it is needed to type explicitly the datum to be serialized. For example:$par

                          $center($att(serialize((Word32)34)))

   because  $att(34)   has  several   interpretations,  and  $att(serialize) can  accept   any  of
   them.  Similarily,  the  result of  $att(unserialize)  must  in  most cases  be  explicitly
   typed. For example:$par

                 $center($att((Maybe(String)) unserialize(s)))

   because the term $att(unserialize(s)) contains no information on the type of the result.$p

   Byte  arrays themselves are  fixed points  of serialization/unserialization.   In other
   words, we always have:$par

           $center($att(serialize((ByteArray)s) = s))
           $center($att((Maybe(ByteArray))unserialize(s) = success(s)))

   The singleton type below is declared as $em(non serializable) in the source of the compiler.
   $acode(
public type OneNonSerial:   dummy_non_serial.
   )
   You can use this type as a 'dummy' component for making a type non serializable.


   $subsubsection(Saving and retrieving data ($att(save) and $att(retrieve)))

   We provide some very  useful tools to save a datum to a file  and to retrieve it. These
   tools are applicable to any datum which is serializable.$p

   If you want to save the datum $att(d) (of type $att(T)) into the file $fname(glouk), just write:$par

                                $center($att(save((T)d,"glouk"))

   This will open the file named $fname(glouk), serialize $att(d), and write the serialization into
   the file.$p

   Conversely, retrieve this datum with:$par

                 $center($att((RetrieveResult(T))retrieve("glouk")))

   where $att(T)  is the type of  $att(d). This will open  the file, read it,  and unserialize the
   result of the reading.$p

   Of course, many errors can happen during this process. This is why we need some types:
   $acode(
public type SaveResult:
   cannot_open_file,       // the directory may not exist or the disk may be full
   write_error,            // the disk may be full
   ok.                     // the datum is successfully saved

public type RetrieveResult($T):
   cannot_find_file,       // the file cannot be found
   read_error,             // problem while reading the file
   type_error,             // the content of the file is not of the given type
   ok($T).                 // the datum is retrieved successfully and here it is
  )

   Now, here are $att(save) and $att(retrieve):
   $acode(
public define SaveResult             save($T  datum, String file_name).
public define RetrieveResult($T)     retrieve(String file_name).
   )


   $subsubsection(Transmitting data)

   Of course, serialization may also be used  to transmit data of arbitrary types over the
   network. See an example in $fname(web/web_arg_encode.anubis).

   $end


   *** (9) Built-in cryptography.

      *** (9.1) Secure hash functions ('md5' and 'sha1').

   A  'secure  hash  function' (or  'message  digest  function')  is  a function  (in  the
   mathematical sens) from the set of all  character strings (in fact, as far as Anubis is
   concerned, from the type 'ByteArray') to  a finite set, in practice, either 2^128 (MD5)
   or 2^160 (SHA1) (in fact a subset of 'ByteArray' in Anubis).

   The function deserves  the name of 'secure  hash function' if it has  the following two
   properties:

     - it is hard to find two distinct elements of the source set with the same image,
     - it is hard to find an antecedent to a given element of the target set.

   By 'hard', we mean that doing it would require centuries of computation time, using the
   power of all the computers in the world.  Nobody has proved (as far as I know) that MD5
   and  SHA1  have  these  properties,  but  also  nobody  has  been  able  to  provide  a
   counterexample. Hence, it is reasonable to think that these functions actually have the
   stated properties.

   Because of the  first property, the result of  'hashing' a byte array is  also called a
   'fingerprint'.   It uniquely  identifies the  byte  array, with  a very  very very  low
   probability of  error. The advantage of the  fingerprint over the original  text, is at
   least that:

      - it hides the original (second property),
      - it has a constant size (16 bytes for MD5 and 20 bytes for SHA1)

   MD5 (Message Digest 5) has been designed  by Ron Rivest. SHA1 (Secure Hash Algorithm 1)
   has been designed  by the NSA (National Security Agency, U.S.A).  It is supposedly more
   secure than MD5.

public define ByteArray       md5($T d).
public define ByteArray       sha1($T d).

   Since byte arrays  are fixed point of serialization, these  functions coincide with the
   usual ones (as available for example under UNIX)  when 'd' is a byte array. When 'd' is
   not a byte array, 'd' is first serialized before the usual algorithm is applied to it.

   So, be carefull with strings. If you  use one of these functions on a character string,
   it will not give the standard result. In order to get the standard result, convert your
   string into a byte array first, like this:

       sha1(to_byte_array("...."))

to do: create a sha1(One -> Maybe(ByteArray) callback). The same for md5.
to do: what about other one way hashing functions ?


      *** (9.2) Symmetric cryptography ('blowfish_encrypt', 'blowfish_decrypt').

   The 'Blowfish'  algorithm is a block cipher  designed by Bruce Schneier  (see his book:
   'Applied  Cryptography', second edition  at Wiley).  This kind  of algorithm  is called
   'symmetric' because the same key is used for encryption and for decryption.

   We provide two public functions, one for encryption and one for decryption:

public define ByteArray      blowfish_encrypt(String key, $T datum).
public define Maybe($T)      blowfish_decrypt(String key, ByteArray source).

   You may encrypt any  serializable datum. The result is a byte  array (that you may save
   in  a file  for  example). You  may  decrypt the  byte  array (with  the  key used  for
   encryption, otherwise the  result is incoherent), and this gives  your datum back.  The
   reason for the 'Maybe' is that the decrypted datum is unserialized.  Hence, a result of
   'failure' means  that unserialization failed,  which may be  a consequence of  the fact
   that the key was  not the key used for encryption. Nevertheless,  this is not the right
   way to  test if the key is  the good one. For  a good test, use  hashing functions like
   'sha1'.  For example,  you may encrypt the pair  (sha1(datum),datum). After decryption,
   you may test if the recovered datum hashes correctly.

   Technical  note: The  blowfish  algorithm is  a  'block' cipher,  which  means that  it
   encrypts data  not byte  by byte (like  a stream ciphers  as RC4),  but by blocks  of 8
   bytes. Since the source  may have a number of bytes not divisible  by 8, the last block
   of the source is padded by zero's, so  that the length of the source becomes a multiple
   of 8.  Then  the blocks are encrypted, and finally,  a byte is added at  the end of the
   encrypted byte array, indicating  the number of bytes in the last  block of the source.
   This information  is used to  truncate the result  at the right size  after decryption.
   Hence, the encrypted  byte array may not  have the same length as  the serialization of
   'datum'.


      *** (9.3) SSL ('Secure Sockets Layer').

   The  Anubis executable 'anbexec'  is linked  with the  OpenSSL library.   The following
   primitives establish the interface with this library.

   If needed by the module to be executed, SSL is first initialized when 'anbexec' starts.
   At that point, the certificates are loaded, the ephemeral RSA key is computed, and more
   generally all the stuff needed for later starting either an SSL server or an SSL client
   is completed.

   Below are the primitives which allow to start an SSL server or an SSL client and to use
   it.


         *** (9.3.1) SSL connections.

   You may open  an SSL connection to an  SSL server.  This 'client SSL  connection' is of
   type (however, see 'anubis/library/tools/connections.anubis' for a unified treatement):

public type SSL_Connection:...        (an opaque type)

   Opening such an SSL connection may fail in various ways. Hence, the following type:

public type SSLConnectError:
  tcp_error(NetworkConnectError),     // this may fail at the level of TCP/IP
  cannot_create_SSL_object,           // this may be a lack of memory
  cannot_connect_under_SSL,           // the server refused the SSL connection
  cannot_trust_server_certificate.    // this depends on your 'accept policy' (see below)


   When you connect  to an SSL secured site,  you want in general to  identify the server,
   that is  to say to  be sure  that the server  you are connected  to is actually  who he
   pretends to be.  This is why 'open_SSL_connection' verifies  the certificate the server
   sends during the SSL handshake. This verification may fail.  In that case, your 'accept
   policy' is used in order to decide if you nevertheless trust the server or not.

   Your  'accept policy' is  defined by  a function  which returns  a boolean  ('true' for
   accepting,  'false'  for  refusing).   This   function  takes  as  argument  the  X.509
   certificate of the server (which may also be missing).


         *** (9.3.2) X.509 Certificates.

   First  of all,  here  is  a type  which  encapsulates an  X509  structure from  OpenSSL
   (representing a certificate in X.509 format):

public type X509:...         (an opaque type)

   Such a certificate may be 'printed' into a character string by:

public define String       to_string(X509 certificate).

   The next function  will store a certificate in  your 'ca directory' so that  it will be
   trusted for ever (in fact until it  becomes out of date).  Actually, this function just
   writes the  certificate (in PEM format) into  your 'ca' directory (as  declared in your
   configuration file).

public type Result_trust_X509_for_ever:
  ca_directory_not_found,
  cannot_create_file,             // the certificate itself
  cannot_create_symbolic_link,    // a symbolic link to the certificate (this is required
                                  //   by OpenSSL for accelerating the search)
  write_error,
  ok.

public define Result_trust_X509_for_ever
  trust_for_ever
    (
      X509 cert
    ).

   Note: OpenSSL  expects that each trusted certificate  has a symbolic link  to it, whose
   name is a hash of the subject name. This enables OpenSSL to select the file by advance,
   because the subject  name is known. When  'anbexec' starts, all the links  for the 'ca'
   directory (actually for all *.pem  files) are regenerated.  'trust_for_ever' also makes
   a  new link  when  a  new certificate  is  trusted. Hence,  all  this  'link stuff'  is
   automatic under Anubis.


         *** (9.3.3) Opening an SSL connection.

   To open your SSL (client) connection to a secured server, use:

public define Result(SSLConnectError,SSL_Connection)
  open_SSL_connection
    (
      String server_name,                 // 'common name' of server (such as "www.mybank.com")
                                          //   this is required for certificate checking
      Word32 ip_address,                  // numeric IP address of server
      Word32 ip_port,                     // for example 443 for HTTPS
      (Maybe(X509)) -> Bool
                          accept_policy   // your policy for accepting the server certificate in
                                          //   case of an invalid, non trusted or missing certificate
    ).

   When your SSL connection has been opened, you  want to read data from it and write data
   to  it.  Use the  following  functions  which come  in  two  flavors:  byte arrays  and
   strings. A result of failure means  that some unrecoverable error occured, and that the
   connection has been closed.

   Below is a variant suitable for transforming an ordinary TCP/IP connection into an SSL one.
   The only difference with the above is that you provide the already opened TCP/IP connection
   instead of a ip address and port.

public define Result(SSLConnectError,SSL_Connection)
  open_SSL_connection
    (
      String server_name,                 // 'common name' of server (such as "www.mybank.com")
                                          //   this is required for certificate checking
      RWStream tcp_connection,            // the already opened TCP/IP connection
      (Maybe(X509)) -> Bool
                          accept_policy   // your policy for accepting the server certificate in
                                          //   case of an invalid, non trusted or missing certificate
    ).


         *** (9.3.4) Reading and writing with SSL connections.

public define Maybe(ByteArray)
  read
    (
      SSL_Connection conn,
      Int n,                           // maximum number of bytes to read
      Int timeout                      // in seconds
    ).

public define Maybe(String)
  read
    (
      SSL_Connection conn,
      Int n,
      Int timeout
    ).


   If you get 'success(b)'  where 'b' is a byte array, the length of  'b' may be less than
   'n'. This is not an error. Use this function again for reading subsequent bytes.

public define Maybe(Int)
  write
    (
      SSL_Connection conn,
      ByteArray data
    ).

public define Maybe(Int)
  write
    (
      SSL_Connection conn,
      String data
    ).

   If you get  'success(m)' as the result of  'write', 'm' may be less than  the length of
   'data'. Again, this is not an error. Use the function again for writing more bytes.

   Of  course, you  don't have  to worry  about closing  SSL connections  or  managing SSL
   objects. The  system does such  things automatically when  needed (this is part  of the
   garbage-collector).


         *** (9.3.5) Creating an SSL server.

   Now, you may  also want to start an  SSL server.  It is of type  'Server' like ordinary
   servers.  Indeed,  a SSL server  is just the  same thing as  a TCP/IP server.  The sole
   difference is that when connections are  accepted, they are wrapped into an SSL object,
   thus making an SSL connections, but only at that moment.

   If you  want to start an  SSL server, use the  following. You have to  provide a server
   name, which must correspond to the so-called 'common name' of your server certificate.

public define StartServerResult
   start_ssl_server
     (
       Word32                               ip_addr,
       Word32                               ip_port,
       (RWStream) -> Bool                   can_accept,  // must return 'false' if the connection is undesirable
       String                               server_name,
       Server -> ((SSL_Connection) -> One)  handler,
       Var(Bool)                            shutdown_required,
       Word8                                listener_priority,
       Word8                                handler_priority
     ).

   For compatibility with versions prior to 1.14, we keep the following:

public define StartServerResult
   start_ssl_server
     (
       Word32                               ip_addr,
       Word32                               ip_port,
       (RWStream) -> Bool                   can_accept,       // must return 'false' is the connection is undesirable
       String                               server_name,
       Server -> ((SSL_Connection) -> One)  handler,
       (One) -> One                         notify,
       Var(Bool)                            shutdown_required
     ).

public define StartServerResult
   start_ssl_server
     (
       Word32                               ip_addr,
       Word32                               ip_port,
       String                               server_name,
       Server -> ((SSL_Connection) -> One)  handler,
       (One) -> One                         notify,
       Var(Bool)                            shutdown_required
     ).

public define StartServerResult
   start_ssl_server
     (
       Word32                               ip_addr,
       Word32                               ip_port,
       String                               server_name,
       Server -> ((SSL_Connection) -> One)  handler,
       (One) -> One                         notify
     ).

   See 'anubis/library/web/multihost_http_server.anubis'  for an  example of use  of these
   primitives.

   Miscellany:

public define (Word32,Word32)    local_SSL_address_and_port (SSL_Connection connection).
public define (Word32,Word32)    remote_SSL_address_and_port (SSL_Connection connection).


      *** (9.4) Simple (non cryptographic) hashing.

   It is  sometimes useful to  associate a small  integer value to  all the elements  of a
   type, in  order to dispatch these elements  into classes (one per  value). The function
   'simple_hash' computes such a  value.  The first argument is the number  of bits in the
   hash values. As a  consequence, the number of values is 2^n, where  n is this number of
   bits. The second argument is a serializable  datum. The result is called a 'simple hash
   value'.


public define Word32
   simple_hash
     (
       Word32      number_of_bits,
       $T          datum
     ).


   *** (10) Images.

   In order  to use  a graphic screen,  we have  to manage images.   We provide  tools for
   manipulating such images.  In section (11) we also provide a tool for copying (mapping)
   images to a window of the host system.

   We also  provide tools for creating  images (painting tools), reading  them from images
   files (JPEG only for the time being), and writing them to files (JPEG only).


      *** (10.1) Types of images.

   We consider the following types of images:

     * RGBA images:

        images with 32 bits per pixel, 8 bits  for red, 8 bits for green, 8 bits for blue,
        and 8 bits for alpha channel (transparency).

public type RGBAImage:...           (an opaque type)


     * Host images:

        We  represent host  images  in some  way  which is  as close  as  possible to  the
        representation of images in the host system.  As far as Anubis is concerned, 'host
        images' are represented by the following type:

public type HostImage:...           (an opaque type)


     * Bitmaps:

          images with  only one bit  per pixel. These  images are generally used  as mask,
          cursors, characters and symbols.

public type BitMapImage:...         (an opaque type)

   Of course, the implicit destructors 'width'  and 'height' are available, but you cannot
   access the array of pixels directly.


      *** (10.2) Creating images.

   You can create 'empty' images. Actually,  they are not empty, but filled uniformly with
   a 'background' color.

to do: sizes of images should be Float32. The same for coordinates, etc...
public define RGBAImage        create_rgba_image(Int width,
                                                 Int height,
                                                 RGBA background).

public define BitMapImage      create_bitmap_image(Int width,
                                                   Int height,
                                                   Bit background).


   You can transform an RGBA image into a host image (and apply an integral reduction factor).

public define HostImage
   to_host_image
     (
       RGBAImage image,
       Word32 reduction_factor
     ).


   Get the size, i.e. a pair (width,height) for a host image.

public define (Word32,Word32)
   size
     (
       HostImage im
     ).


      *** (10.3) Drawing into images.


         *** (10.3.1) Drawing pixels.

   You can  draw individual pixels into  an image (at  a given position (x,y)).   The next
   functions simply do nothing  if (x,y) is out of range (outside  the image). There is no
   danger, but a well behaved program should not try to draw outside an image.


public define One
   draw_pixel
     (
       RGBAImage      image,
       Int            x,
       Int            y,
       RGBA           color
     ).

   In  the case of  an RGBA  image, 'color'  is painted  over the  color at  (x,y), taking
   transparencies (alpha channels) into account. Computations are performed as follows.

   The  resulting  color  (red,green,blue)   when  mixing  two  pixels  (r1,g1,b1,a1)  and
   (r2,g2,b2,a2) depends  on the transparency of  the second pixel (which  is painted over
   the first one). The new red value is a barycenter of the original red values, using a2:

            (255-a2)*r1 + a2*r2
       r = ---------------------
                   255

   Notice that  if a2  = 255 (second  pixel is opaque),  the formula  reduces to: r  = r2.
   Similarly, if a2 = 0 (second pixel is  invisible), the formula reduces to: r = r1.  The
   same method is used for green and blue. The new transparency is given by:

                (255-a1)*(255-a2)                        (255-a1)*(255-a2)
       255-a = -------------------,     hence a = 255 - -------------------
                       255                                      255

   because (255-a1)/255 is the factor of transparency for the first pixel. For example, if
   a1 = 0, 100  percent of the light passes through the pixel. On  the contrary, when a1 =
   255, 0 percent of the light passes through the pixel. The above is equivalent to:

                      a1*a2
       a = a1 + a2 - -------
                       255

   For example, if one pixel is opaque (say  a1 = 255), the result is opaque. If one pixel
   is completely transparent (a1 = 0), the result has the opacity of the other one.


public type BitPaintMode:
   zero,
   one,
   invert.

public define One
   draw_pixel
     (
       BitMapImage image,
       Int x,
       Int y,
       BitPaintMode how
     ).

   In the case of a bitmap image, you provide a bit paint mode. If you choose:

     zero      the new pixel is zero
     one       the new pixel is one
     invert    the new pixel is the opposite (one for zero, zero for one) of the old one


public define One
   draw_pixel
     (
       HostImage image,
       Word32 x,
       Word32 y,
       RGB color
     ).


         *** (10.3.2) Getting pixels.

   Given an image, you can get (or read) the pixel at a given position (x,y).

public define RGBA
   get_pixel
     (
       RGBAImage image,
       Int x,
       Int y
     ).

   The previous  function returns a fully  transparent (black) pixel  (all four components
   are zero) if out of range.

public define Bit
   get_pixel
     (
       BitMapImage image,
       Int x,
       Int y
     ).

   This function returns 'zero' if out of range.


         *** (10.3.3) Drawing rectangles.

   This  is  similar  to  drawing  pixels,  but  we  first  need  to  describe  rectangles
   (rectangular areas of pixels):

public type Rectangle:
   rect(Word32 x,
        Word32 y,
        Word32 u,
        Word32 v).

// Helper for migration to Int
public define Rectangle
  rect
  (
    Int x,
    Int y,
    Int u,
    Int v
  ).


   First coordinate  is understood from  left to right,  and second cordinate from  top to
   bottom. The above rectangle is actually the set of all points (a,b) such that:

         x =< a < u
         y =< b < v

   i.e. the width of the rectangle is u-x, and its height is v-y.

   0      x                u
 0 +------------------------------------+
   |      :                :            |
   |      :                :            |
   |      :                :            |
 y |......+----------------+            |
   |      |                |            |
   |      | rectangle      |            |
   |      |                |            |
   |      |                |            |
 v |......+----------------+            |
   |                                    |
   |                                    |
   |                                    |
   |                              image |
   +------------------------------------+


public define One
   draw_rectangle
     (
       RGBAImage destination,
       Rectangle rect,
       RGBA color_of_rectangle
     ).

   See 'draw_pixel'  above for details  on how colors  and transparencies are  handled. Of
   course, the rectangle is automatically clipped as needed.


public define One
   draw_rectangle
     (
       BitMapImage destination,
       Rectangle rect,
       BitPaintMode how
     ).

   See 'draw_pixel' above for details.

public define One
   draw_rectangle
     (
       HostImage destination,
       Rectangle rect,
       RGB color_of_rectangle
     ).


         *** (10.3.4) Cropping and encrusting, rotating and flipping.

   You can also crop a rectangle from an image and encrust it into another image (possibly
   applying a rotation or flipping).

   Not  the whole  source  image  is encrusted  into  the destination  image,  but only  a
   rectangle (say 'rect(x,y,u,v)') which is cropped from the source image.  The upper left
   corner of the cropped rectangle is positioned at (a,b) in the destination.


     source image                             destination image

          x                                             a
   +------------------------+               +-----------------------------+
   |      :                 |               |           :                 |
   |      :                 |               |           :                 |
  y|......+------------+    |               |           :                 |
   |      |            |    |               |           :                 |
   |      |  cropped   |    |              b|...........+------------+    |
   |      |  rectangle |    |               |           |            |    |
   |      |            |    |               |           |  cropped   |    |
   |      +------------+....|v              |           |  rectangle |    |
   |                   :    |               |           |            |    |
   |                   :    |               |           +------------+    |
   +------------------------+               |                             |
                       u                    |                             |
                                            +-----------------------------+


   Transparency is taken into account, depending on the types of image:

   * for incrusting  an RGBA image into an  RGBA image, the colors  and transparencies are
   computed as for 'draw_pixel' above.

   * for  incrusting a  bitmap into  an RGBA  image,  a filter  color (an  RGBA color)  is
   used. This  filter color  is mixed with  each destination  pixel (for which  the source
   pixel is 1) before encrustation, using the same method as for 'draw_pixel' above.

   * for encrusting  a bitmap image into  a bitmap image,  a function (Bit,Bit) ->  Bit is
   used (details below).

   By  the  same  time,  a  geometric   transformation  may  be  applied  to  the  cropped
   rectangle. It may be rotated or flipped or both. Actually, a group (in the mathematical
   sens) of  transformations is available, which  is generated by  an orthogonal symmetry,
   and  rotation by  90  degrees (rotations  are  measured clockwise).  This  group has  8
   elements and is called the dihedral 'D4' group.

   Let (r,s)  be the  coordinates of a  point in the  source image,  and let (p,q)  be its
   coordinates in the destination image. Each transformation is defined by a 2x2 matrix M,
   such that:

            (p-a)         (r-x)
            (q-b)   =   M (s-y)

   (so that in any  case, the upper left corner (x,y) of  the cropped rectangle arrives at
   (a,b)).

public type Dihedral4:                     // matrix M used

   as_is,                                  // ( 1  0)
                                           // ( 0  1)

   rotated_90,                             // ( 0 -1)
                                           // ( 1  0)

   rotated_180,                            // (-1  0)
                                           // ( 0 -1)

   rotated_270,                            // ( 0  1)
                                           // (-1  0)

   flipped_horizontally,                   // ( 1  0)
                                           // ( 0 -1)

   flipped_vertically,                     // (-1  0)
                                           // ( 0  1)

   flipped_diagonally,                     // ( 0 -1)
                                           // (-1  0)

   flipped_codiagonally.                   // ( 0  1)
                                           // ( 1  0)


   For  example, if you  choose 'rotated_90',  the point  (r,s) arrives  at (y-s+a,r-x+b),
   since:

             (p)     ( 0 -1)(r-x)   (a)
             (q)  =  ( 1  0)(s-y) + (b)

   Of course, the  cropped rectangle is clipped as  needed, in order to fit  both into the
   source and destination (this has no influence on the geometric transformation).


public define One
   crop_and_encrust       // encrusting an RGBA image into an RGBA image
     (
       RGBAImage source,
       RGBAImage destination,
       Rectangle cropped,
       Int a,           // position in destination
       Int b,
       Dihedral4 t
     ).


public define One
   crop_and_encrust       // encrusting a BitMap image into an RGBA image
     (
       BitMapImage source,
       RGBA filter,
       RGBAImage destination,
       Rectangle cropped,
       Int a,      // position in destination
       Int b,
       Dihedral4 t
     ).


   You can  also crop and encrust from  a bitmap to a  bitmap.  In this case,  there is no
   notion of color, but a 'bit paint mode'.

public define One
   crop_and_encrust
     (
       BitMapImage        source,
       BitMapImage   destination,
       Rectangle         cropped,
       Int                  a,      // position in destination
       Int                  b,
       BitPaintMode   paint_mode,
       Dihedral4               t
     ).


         *** (10.3.5) Drawing system characters.

   Anubis  has system  character fonts  available in  several styles,  weights  and sizes.
   These fonts are coded according to the ISO 8859-15 standard, containing 256 characters,
   some of which are  empty. The table below shows the ISO  8859-15 encoding.  It has been
   made with  the Anubis program in  'library/system_fonts/font_table.anubis'. However, it
   will be correct in your ASCII editor only if your editor uses the same encoding.


                                   ISO 8859-15
   /*
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   000-015  |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   016-031  |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   032-047  |   | ! | " | # | $ |   | & | ' | ( | ) | * | + | , | - | . | / |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   048-063  | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | : | ; | < | = | > | ? |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   064-079  | @ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   080-095  | P | Q | R | S | T | U | V | W | X | Y | Z | [ | \ | ] | ^ | _ |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   096-111  | ` | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   112-127  | p | q | r | s | t | u | v | w | x | y | z | { | | | } | ~ |   |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   128-143  |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   144-159  |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   160-175  | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   176-191  | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   192-207  | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   208-223  | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   224-239  | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   240-255  | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � | � |
   ---------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
   */


   Note: The  above encoding  is almost  the same as  the ISO  8859-1 encoding.   The only
   difference is  the character  number 164: �  which is  the 'currency' character  in ISO
   8859-1,  and the  'euro'  character in  ISO 8859-15.   Also,  note that  the first  256
   characters of the  UNICODE 16 bits encoding  (used by MS Windows) are  identical to ISO
   8859-1.

   The Anubis fonts are located in  'library/system_fonts'.  A C-X11 program has been used
   for automatically transforming X11-LINUX fonts  into the Anubis font format. The Anubis
   font  file format  is  pure ASCII  and  readable with  a text  editor.   The format  is
   self-explanatory by  inspection. You can use all  means at your disposal  to create new
   system fonts (fulfilling the conditions described here).

   The Anubis system fonts have names of the following form:

                                   style_weight_angle_size

   where                             is something like
      'style'                           'times', 'helvetica', ...
      'weight'                          'bold', 'medium', ...
      'angle'                           'oblique', 'italic', 'regular', ...
      'size'                            '8', '10', '12', ...

   In order  to get  the list  of all available  font names,  use 'get_system_font_names',
   defined  in  'library/tools/basis.anubis',  or  just  have  a  look  to  the  files  in
   'library/system_fonts'.

   Before you can use a system font, you must load it from the disk. This is acheived by:

public type SystemFont:...        (an opaque type)

public define Maybe(SystemFont)
   load_system_font
     (
       String font_name
     ).

   As usual, the result is 'failure' if some  problem arose (the font does not exist or is
   corrupted).  Of  course, you  don't have to  worry about  unloading a system  font. The
   garbage-collector of the Anubis system does that automatically.


   Characters in system fonts have the following geometrical parameters:

                     +------+...............
                     |      |             ^
                     |      |             |
                     |      |             |
                     | XXXX |             height
                     |XX X  |             |
                     |X   X |             |
                     |XX  X |             |
       reference     | XXX  |             v
       point ------->+-X----+...............
                     | XXXX |             ^
                     |X    X|             |
                     |XX  XX|             depth
                     | XXX  |             |
                     |      |             v
                     +------+...............
                     :      :
                     :      :
                     :width :


   System characters may be drawn within RGBA images and within bitmap images (notice that
   (x,y)  is the  position of  the reference  point, not  of the  top left  corner  of the
   character):

public define Word32
   draw_system_character
     (
       RGBAImage               destination,       // where to draw the character
       Rectangle               clip,              // clipping rectangle on destination
       Word32                  x,                 // position of topmost leftmost point of
       Word32                  y,                 //   characters in destination
       SystemFont              font,
       Word32                  character_code,
       RGBA                    character_color
     ).

public define Word32
   draw_system_character
     (
       BitMapImage             destination,       // where to draw the character
       Rectangle               clip,              // clipping rectangle on destination
       Word32                  x,                 // position of topmost leftmost point of
       Word32                  y,                 //   characters in destination
       SystemFont              font,
       Word32                  character_code,
       BitPaintMode            paint_mode
     ).

   The returned value (of  type Word32) is either 0 if the  character cannot be drawn (the
   character code  is invalid), or the  width of the character  if it has  been drawn. All
   characters for a given size have the  same height and depth.  Only the width depends on
   the particular character (this is called 'proportional spacing').


public define Word32
   draw_system_character
     (
       HostImage               destination,       // where to draw the character
       Rectangle               clip,              // clipping rectangle on destination
       Word32                  x,                 // position of reference point of
       Word32                  y,                 //   characters in destination
       SystemFont              font,
       Word32                  character_code,
       RGB                     character_color
     ).


         *** (10.3.6) System characters and fonts informations.

   You may query informations about system fonts and characters.

   Informations on fonts:

public type SystemFontInfo:
   font_info(Word32   first_char,       // code of first character in font
             Word32   num_char,         // number of characters in font
             Word8    height,           // height of font above the base line
             Word8    depth).           // depth of font below the base line


public define SystemFontInfo     get_font_info(SystemFont font).


   Informations on individual characters:

public type SystemCharacterInfo:
   char_info(Word8    height,           // above base line
             Word8    depth,            // below base line
             Word8    width).

public define SystemCharacterInfo  get_char_info(SystemFont font,
                                                 Word8 code).


      *** (10.4) Handling JPEG/JFIF image files.

   The following functions  are an interface to the IJG  (Independant JPEG Group) library,
   which has been linked with 'anbexec'.

public type JPEG_ImageFormat:
  rgb,                        // 24 bits per pixel (8 for red, 8 for green, 8 for blue)
  greyscale.                  // 8 bits per pixel

public type JPEG_BitMapImage:
  img         (JPEG_ImageFormat f,
               Word32 width,                      // width of image in pixels
               Word32 height,                     // height of image in pixels
               ByteArray samples).               // the color samples

   Color sample are ordered in the byte array as follows:

     samples for first (top) line from left to right,
     samples for second line from left to right,
     ...
     samples for last (bottom) line from left to right.

   For rgb images,  each color sample is 3  bytes (red, green, blue, in  this order).  The
   size of  the byte array is  3*width*height. For greyscale,  there is only one  byte per
   pixel.


         *** (10.4.1) Converting to 'HostImage'.

   An image  of type 'JPEG_BitMapImage' may  be converted to a  host image for  use on the
   graphic screen.

public define HostImage
   to_host_image
     (
       JPEG_BitMapImage image,
       Word32 reducing_factor
     ).

   The reducing factor  is applied in both directions. For example,  for a reducing factor
   of 3,  the image is reduced  3 times vertically  and 3 times horizontally.   A reducing
   factor which is negative or zero is replaced by 1.

   There  is no  need  for a  conversion in  the  opposite direction,  because images  are
   transformed into  host images only for the  purpose of displaying on  the screen. Image
   manipulations are never performed on host images.


         *** (10.4.2) Converting to 'RGBAImage'.

   Similarly, JPEG images may be converted to RGBA for manipulations.

public define RGBAImage
   to_RGBA
     (
       JPEG_BitMapImage image,
       Word32 reducing_factor
     ).

   and conversely:

public define JPEG_BitMapImage
   to_JPEG
     (
       RGBAImage  image
     ).


         *** (10.4.3) Writing (creating) a JPEG file.

   Here is the public tool for writing an image into a file in JPEG format.

public type Result_JPEG_write:
  cannot_create_file,
  compression_error,
  ok.

public define Result_JPEG_write
  write_image_to_JPEG_file
    (
      JPEG_BitMapImage image,
      String file_name,
      Word32 quality             // from 0 (poorest) to 100 (best)
    ).


         *** (10.4.4) Reading a JPEG file.

   Here is the tool for reading an image from a JPEG file.

public type Result_JPEG_read:
  cannot_open_file,
  decompress_error,
  ok(JPEG_BitMapImage).

public define Result_JPEG_read
  read_image_from_JPEG_file
    (
      String file_name
    ).


   *** (11) Managing the graphic screen.

   Preferably, do not use the tools below directly, but through the 'high level' interface
   defined in 'anubis/library/widgets4/'.  Nevertheless,  there are examples of direct use
   of  the  functions  below  in  'anubis/library/examples/graphism/paint.anubis'  and  in
   'anubis/library/examples/graphism/diaporama.anubis'.


      *** (11.1) Types for screen, mouse and keyboard handling.

   The following types are self-explanatory.

public type KeyboardState:
   kbdstate(Bool shift,           // 'true' if 'shift' (left or right) is pressed down
            Bool ctrl,            // etc...
            Bool alt,
            Bool mouse_left,      // true if left button of mouse is down
            Bool mouse_middle,    // idem middle button
            Bool mouse_right).    // idem right button


public type KeyboardSpecialKey:
   escape,
   f1, f2, f3, f4, f5, f6, f7, f8, f9, f10,
   backspace,
   home, end,
   tab, enter,
   insert, del,
   page_up, page_down,
   up, down, left, right.


public type KeyboardKey:
   unknown,
   char(Word8),
   unicode(Word8,Word8),
   special(KeyboardSpecialKey).


public type MouseClick:
   left_down,
   left_up,
   middle_down,
   middle_up,
   right_down,
   right_up.


   The next type describes the events which may happen in a host window:

public type HostWindowEvent($E):
   // generated by system and user:
   quit,
   expose,
   pointer_entering,
   pointer_leaving,
   key_down           (KeyboardState, KeyboardKey),
   mouse_move         (KeyboardState, Word32 x, Word32 y),
   mouse_click        (KeyboardState, MouseClick, Word32 x, Word32 y),
   mouse_wheel        (KeyboardState, Word32 delta, Word32 x, Word32 y),
   tick,
   // never generated by system:
   repaint            (List(Rectangle)),
   specific           ($E).


   Of course, the  system generates events, but  not all sorts of events.  On the contrary
   the user may generate all sorts of events, using 'queue_event' (see below).

   The event 'tick' is received by each host window approximately 25 times per second. The
   event 'repaint(l)' is not  generated by the system. When it is  received, the window is
   repainted within  each rectangle of the  given list.  The event  'specific(...)' is for
   fitting the  particular needs  of your application.   $E may  be any type  of 'specific
   events'. Of course, the system never generates a specific event.

public type HostWindow:...

   'HostWindow' is  an opaque type representing a  window of the host  system.  You cannot
   create a  'HostWindow' directly, and when  you have one  at hand, you cannot  extract a
   component.   You can  only  open a  host  window using  'open_host_window', and  define
   functions using such  data.  For example, in  order to have a running  window, you will
   have to write a 'paint method', which is of type '(HostWindow,Rectangle) -> One'.


      *** (11.2) Tools.

   The  size (width,height) of  a host  window (in  pixels) is  returned by  the following
   function. The size is the size of the client area of the window.

public define (Word32,Word32)
   size
     (
       HostWindow   hw
     ).


   You can change the size of the window (the given size is the new inner size):

public define One
   resize
     (
       HostWindow   hw,
       Word32       width,
       Word32       height
     ).


   The size (width,height) of the screen itself (in pixels) is returned by:

public define (Word32,Word32)      screen_size.

   You can change the title of a window during its lifetime.

public define One
   change_title
     (
       HostWindow hw,
       String new_title
     ).


      *** (11.4) Opening a host window.


public type HostWindowResizability:
   not_resizable,
   resizable.

public type HostWindowSort:
   managed(HostWindowResizability),  // the window is managed by the window manager: it has a border,
                                     //   a close button, and the window manager manages moves of the window
   transient.                        // the window is not managed by your window manager: it has
                                     //   no border no button, and the window manager will never move it


   Now, here is  the function you can use for  opening a host window, and  let it live its
   life.

public define Maybe(HostWindow)
   open_host_window
     (
       Rectangle                                  r,       // the rectangle occupied by the window
       String                                     title,
       HostWindowSort                             sort,
       (HostWindow,List(Rectangle)) -> One        paint_method,
       (HostWindow,HostWindowEvent($E)) -> List(Rectangle)    event_handler,
       List(HostWindowEvent($E)) -> List(HostWindowEvent($E)) compress
     ).

   The value  returned is 'failure' if  the window cannot be  created, and 'success(win)',
   where 'win' is the new window itself, otherwise.  If successful, this function starts a
   virtual machine dedicated to the window (using 'delegate' above).  This virtual machine
   manages the window, using the given paint method and event handler.

   Notice that the above function does not show the window on the screen. In order to show
   the window, use the following:

public define One
   show
     (
       HostWindow win
     ).

   You can also hide the window with:

public define One
   hide
     (
       HostWindow win
     ).


   From that point  on, the window has its  own life. You cannot destroy  it directly, but
   you can  communicate with it through  dynamic variables. Actually, you  can destroy the
   window by generating a 'quit' event for it with 'queue_event' (see below).


      *** (11.5) Queuing an event to a host window.

   When you  have a host window  at hand (for example  when executing a  paint function or
   event handler), you can queue a new event for that window.

public define Bool
   queue_event
     (
       HostWindow w,
       HostWindowEvent($E) e
     ).


      *** (11.6) Basic paint functions.

   Basic paint functions  are needed in order to create a  'paint method'. These functions
   should be executed only from within a paint method.

   Paint a rectangle of a given color.

public define One
   paint_rectangle
     (
       HostWindow            hw,
       Rectangle             r,
       RGB                   color
     ).


   We can also do that into a buffer.

public define One
   paint_rectangle
     (
       HostImage             buffer,
       Rectangle             r,
       RGB                   color
     ).


   Paint an image at  a given position.  Paints the image at  position (x,y) in the window
   (after clipping).

                                                   window
       +-------------------------------------------------+
       |                                                 |
       |       x               image                     |
       |     y ......................                    |
       |       .                    .                    |
       |       .     a       rect   .                    |
       |       .   b +---------+    .                    |
       |       .     |         |    .                    |
       |       .     |         |    .                    |
       |       .     |         |    .                    |
       |       .     +---------+ v  .                    |
       |       .               u    .                    |
       |       ......................                    |
       |                                                 |
       |                                                 |
       +-------------------------------------------------+


   The upper  left corner  of the image  comes at  (x,y) in the  window regardless  of the
   clipping rectangle  rect(a,b,u,v). All coordinates are relative to the window.

public define One
   paint_image
     (
       HostWindow              hw,
       Rectangle               clip,      // rect(a,b,u,v) above
       Word32                  x,         // position of image in the window
       Word32                  y,
       HostImage               image
     ).


   We may also paint an image to a buffer (HostImage) instead of a window:

public define One
   paint_image
     (
       HostImage               buffer,
       Rectangle               clip,
       Word32                  x,         // position of image in buffer
       Word32                  y,
       HostImage               image
     ).


public define One
   map_to_host_window
     (
       RGBAImage               image,
       HostWindow              hw,
       Rectangle               clip,
       Word32                  a,        // (a,b) = upper-left corner of rectangle in 'image'
       Word32                  b,
       Word32                  w,        // (w,h) = size of rectangle in 'image'
       Word32                  h,
       Word32                  x,        // (x,y) = where upper-left corner of rectangle is mapped
       Word32                  y         //   in the host window
     ).


   *** (12) SQLite3 interface.

   'anbexec'  is linked against  the SQLite3  database library.  For more  informations on
   SQLite3, see the web site 'http://www.sqlite.org'.


      *** (12.1) Errors.

   Errors returned by the SQLite3 library  are formated into the following type. The first
   component is the SQLite3 code of the  error. The second component in the alternative is
   a english  text giving an explanation  on the error.  Error codes are those  defined by
   the documentation at http://www.sqlite.org.

public type SQLite3Error:
   sqlite3 (Word32   code,
            String   text).


      *** (12.2) Opening a data base.

   A database must be opened before  any operation may take place. The resulting 'database
   handle' as an Anubis datum is of the opaque type:

public type SQLite3DataBase:...

   In order  to open  (or create,  if it  does not exist)  the database  you just  have to
   provide the name (path) of the file which contains (or will contain) the data base:


public define Result(SQLite3Error,SQLite3DataBase)
   sqlite3_open
     (
       String  filepath
     ).

   If the database cannot be opened or created an error is returned.

   You  don't need  to close  the database.  The garbage-collector  calls  the appropriate
   function of the SQLite3 library for closing the database when needed.

   SQLite3 provides the possibility of loading  extensions to the SQL language. Since this
   may  open  security  holes, extension  loading  is  not  enabled  by default.  You  can
   enable/disable extension loading as follows:

public type SQLite3ExtensionEnable:
   disable,
   enable.

public define One
   sqlite3_extension_loading
     (
       SQLite3DataBase          db,
       SQLite3ExtensionEnable   e
     ).


      *** (12.3) Data types.

   The  data which  may  be put  in the  cells  of a  table  may be  of several  different
   types. The following type definition is adhoc for handling such data.

public type SQLite3Datum:
   no_such_column, // returned if you are asking for a datum from a non existing column
   integer   (Int),
   float     (Float),
   text      (String),
   blob      (ByteArray),
   null.


      *** (12.4) Querying a database.

   If you  have a database  handle, you can  query the corresponding database.   The query
   itself is an  SQL query (in the form  of a String which must be  acceptable by SQLite3;
   see  http://www.sqlite.org).  The  string may  also contain  'parameters', in  the form
   '@name' for representing  literal data.  These parameters must be  bind to actual data.
   Remark: any non bound parameter is by default bind to 'NULL'.

   The result of a query is a table (if  no error occurs). A table is a finite sequence of
   rows, and each row is a list of SQLite3Datum. There is also a row of headers (a list of
   String) containing the names of the columns (headers).

   However,  this table  is returned  in the  form of  a triplet  of functions.  The first
   function, of type:

                                          One -> List(String)

   returns (when applied  to 'unique') the list  of names (headers) of the  columns in the
   table.

   The second function is  the 'cursor' which may be used for  walking into the table. The
   cursor is of type:

                                           One -> SQLite3Row

   where:

public type SQLite3Row:
   error(SQLite3Error),            // an error occured
   no_more_row,                    // there is no more row in the table
   row(Int -> SQLite3Datum).       // this is the next row

   The  cursor should  be called  repeatedly and  returns one  row at  each call  until it
   returns 'no_more_row'.  A  row is returned in  the from of a function  mapping a column
   number (beginning at  1) to a datum.  Be careful because this function  is volatile. It
   must be used before you go to the next row.

   You may also reset  the cursor in order to reexecute the  same query, normally with new
   values of the parameters. A 'reset function' of type:

                            List(SQLite3Bind) -> SQLite3Result

   is used for this purpose. The argument is a list of parameter bindings:

public type SQLite3Bind:
  bind_Int       (String name, Int value),          // bind parameter 'name' to given value
  bind_Float     (String name, Float value),
  bind_String    (String name, String value),
  bind_ByteArray (String name, ByteArray value),
  bind_NULL      (String name).

   The result of the reset function is of type:

public type SQLite3Result:
  error(SQLite3Error),           // some error occured
  ok.                            // the query has been reset successfully

   For example, in  order to bind the parameter  whose name is '@ga' to  the integer value
   34, the parameter '@bu'  to the string "bu", and to reset  the query, use the following
   (assuming that the reset function is represented by the symbol 'reset'):

                     reset([bind_Int("@ga",34), bind_String("@bu","bu")])

   The query must  be 'initiated' (or 'prepared' in the Sqlite3  terminology). This is the
   job of the  function sqlite3_query declared below. It returns a  datum of the following
   type:

public type SQLite3QueryResult:
   error(SQLite3Error),                                   // an error occured
   ok(One -> List(String)                      headers,   // for getting the list of column names
      One -> SQLite3Row                        cursor,    // for getting the rows, one at a time
      List(SQLite3Bind) -> SQLite3Result       reset).    // for binding parameters and reseting

   You initiate the query with the following:

public define SQLite3QueryResult
   sqlite3_query
     (
       SQLite3DataBase        db,                   // the database
       String                 sql_command,          // the SQL query
       List(SQLite3Bind)      initial_bindings      // initial parameter bindings
     ).

   For  your convenience,  we  also  provide the  following  variant to  be  used when  no
   parameter binding is needed.  This is the  case whenever the SQL query does not contain
   any parameter name.  In this case the reset function returned  by sqlite3_query is also
   of no use.

public define SQLite3QueryResult
   sqlite3_query
     (
       SQLite3DataBase        db,
       String                 sql_command
     ).

   *** Low level Sqlite3 Interface (August 2008).

/**
 * A precompiled statement.
 */

public type SQLite3Stmt:...

/**
 * Compiling An SQL Statement
 *
 * To execute an SQL query, it must first be compiled into a byte-code program using one of these routines.
 * The first argument, "db", is a database connection obtained from a prior call to sqlite3_open().
 * The second argument, "sql_command", is the statement to be compiled, encoded as UTF-8.
 * On success, it returns a compiled prepared statement that can be executed using sqlite3_step().
 */

public define Result(SQLite3Error, SQLite3Stmt)
   sqlite3_prepare
     (
       SQLite3DataBase        db,                   // the database
       String                 sql_command           // the SQL query
     ).

/**
 * Binding Values To Prepared Statements
 *
 * In the SQL strings input to sqlite3_prepare(), literals may be replaced by a parameter in one of these forms:
 *
 *    * ?
 *    * ?NNN
 *    * :VVV
 *    * @VVV
 *    * $VVV
 *
 * In the parameter forms shown above NNN is an integer literal, and VVV is an alpha-numeric parameter name.
 * The values of these parameters (also called "host parameter names" or "SQL parameters") can be set using the
 * sqlite3_bind() function.
 */

public define SQLite3Result
   sqlite3_bind
     (
       SQLite3Stmt        stmt,
       List(SQLite3Bind)  bindings
     ).

/**
 * Evaluate An SQL Statement
 *
 * After a prepared statement has been prepared using sqlite3_prepare(), this function must be called one or
 * more times to evaluate the statement.
 */

public define SQLite3Row
   sqlite3_step
     (
       SQLite3Stmt        stmt,
     ).

/**
 * Reset A Prepared Statement Object.
 *
 * The sqlite3_reset() function is called to reset a prepared statement object back to its initial state, ready
 * to be re-executed. Any SQL statement variables that had values bound to them using the sqlite3_bind() API retain
 * their values.
 */
public define SQLite3Result
   sqlite3_reset
     (
       SQLite3Stmt        stmt,
     ).

/**
 * Low level utility function allowing to construct a SQLite3QueryResult from a prepared and eventually binded statement.
 * This function is used by higher level function 'sqlite3_query'.
 */
public define SQLite3QueryResult
  make_SQLite3QueryResult
  (
    SQLite3Stmt        stmt,
  ).


   *** (13) Fast lexical analysis.

   We provide a small tool for compiling lexers described using lists into 'fast
   lexers'. Here we have only low level tools. High level tools, including an LEX/FLEX-like algorithm
   for constructing a low level lexer from a set of regular expressions (to be used preferably)
   are in 'library/lexical_analysis/'.


      *** (13.1) Describing a lexer.

   A 'lexer' is an automaton made of 'states' and 'transitions'.  To each state is
   attached a set of 'transitions' (having this state as their 'source state'). A
   transition is a pair made of a character (Word8) and a state name (Word16) (the 'target'
   state for this transition).

public type FastLexerTransition:
   transition         (Word8    character,        // if we read this character ...
                       Word16   state_name).      // ... we go to this state

   There are three sorts of states: 'accepting' states, 'rejecting' states and 'ignoring'
   states. By convention, the lexer returns a result if it cannot read more in an
   accepting or rejecting state, and restarts from state 0 (without stopping) if it
   cannot read more in an ignoring state. It also returns when it reaches the end of
   the input buffer. The automatic reloading of this buffer and restarting of the lexer
   is written in 'library/lexical_analysis/fast_lexer_5.anubis'.

public type FastLexerState:   // description of states (names of states are generated automatically)
   rejecting   (List(FastLexerTransition) transitions),
   accepting   (List(FastLexerTransition) transitions),
   ignoring    (List(FastLexerTransition) transitions).

   For example, a lexer able to accept non empty sequences of lower case letters and
   ignoring 'whites' characters (spaces, tabulators and line feeds), may be an automaton
   like this one:

                        'a',...,'z'
                   ---------------------
                  |                     |     ----------
                  |                     V    |          |
              +---------+             +---------+       | 'a',...,'z'
              | state 0 |             | state 1 | <-----
              | (reject)|             | (accept)|
              +---------+             +---------+
                 |
   ' ','\t','\n' |
                 V
              +---------+
              | state 2 |
              | (ignore)|
              +---------+

   The automaton starts in state 0 and reads a character. If it is white it goes to state
   2. In this state (Whixh has no transition) the automaton ignores the result obtained
   so far and restarts from state 0. If it reads a lowercase letter, it goes to state 1,
   otherwise it rejects the input. While in state 1, the automaton reads as many lower case
   letters as possible and accepts the input. This automaton may be represented as the following
   datum of type 'List(FastLexerState)':

   [
     /* state 0 */
     rejecting([transition(' ',2),transition('\t',2),transition('\n',2),
                transition('a',1),
                ...
                transition('z',1)]),

     /* state 1 */
     accepting([transition('a',1),
                ...
                transition('z',1)]),
     /* state 2 */
     ignoring([])
   ]

   Notice that a state is identified by its rank in the list. The starting state is always state 0.
   Also notice that ignoring states may have transitions. Indeed, if we want to
   accept sequences of at least two 'a' and ignore anything else, we may have an automaton
   like this one:

                     'a'                      'a'
             ---------------------    -------------------
            |                     |  |                   |
            |                     v  |                   v
       +---------+          +-----------+         +-------------+
       | state 0 |          |  state 1  |         |   state 2   |
       | ignore  |          | ignore    |         | accept      |-----
       +---------+          +-----------+         +-------------+     |
            |                         |                     ^         | 'a'
            |                         |                     |         |
            |   anything except 'a'   |                      ---------
            v                         |
       +---------+                    |
       | state 3 |<-------------------
       | ignore  |
       +---------+

   The automaton always tries to read the longuest possible sequence. Hence, transitions
   always have precedence over the sort of the state (rejecting, accepting, ignoring).

   Of course, it is possible to write down Anubis functions for running this automaton.
   But this may work quite slowly. This is the reason why we provide a sort of 'compiler'
   for this kind of automaton.  This 'compiler' produces a 'fast lexer', which is actually
   made of two byte arrays which are used as decision and transition tables by an automaton
   written in C (which is a single instruction of the virtual machine).

   Also notice that lexer descriptions as above don't have to be written by hand. They are
   generated from sets of regular expressions by Anubis programs that you can find in
   'library/lexical_analysis/fast_lexer_5.anubis'.


      *** (13.2) Compiling a description.

   Each (low level) fast lexer is actually seen as a function taking several arguments
   (see below).

   During its execution the fast lexer doesn't return until one of the following conditions is met:

     - (1) no transition is possible and the current state is a not an ignoring state,
     - (2) the end of the input is reached (no character to read).

   Notice that if no transition is possible (we have read the longest possible lexeme) and if the current
   state is 'ignoring', the lexer doesn't return but instead restarts in state 0. This is the reason
   why no action (in the sens of 'fast_lexer_5.anubis') can be attached to an ignoring state.

   Also notice that if in some state 's' a lexeme is accepted, and if there is a possible transition,
   the lexer continues to read. However, it is possible that no longer lexeme can be accepted, and in
   this case, the lexeme accepted in state 's' must be returned. This is why the lexer maintains a
   'possible last accepted lexeme' of the type below:

public type FastLexerLastAccepted:
   none,                               // nothing was previously accepted
   last(Word16   state,                // something was accepted in this state
        Int      ending_position).     // position in the input buffer where the last accepted lexeme ends

   The starting position of the accepted token is not a component in the alternative 'last' because,
   it can be recovered by other means. Also the role of the component 'state' in the alternative 'last'
   is mainly to allow the recovering of the corresponding action.

   The type below describes all possible situations when the lexer returns:

public type FastLexerOutput:
   rejected        (Word16 where, Int start, Int end),
   accepted        (Word16 where, Int start, Int end, Int current),
   ignored_to_end  (Word16 where).

   'start' and 'end' delimit a sequence of characters in the input buffer, precisely the characters whose
   offsets are between 'start' included and 'end' not included.

   Notice that when the lexer is called, a current position of reading is given together with a state.
   This is because it can be necessary to resume a reading which was interrupted by the necessity to
   reload the input buffer.

   rejected(where,start,end) means:
      - nothing was accepted (in particular, there was no 'last accepted')
      - the current state is 'where',
      - 'start' and 'end' delimit a lexeme which cannot be accepted (to be used in an error message),
      - 'end' is also the current position of reading.
      In this case, we can know if we are at the end of the input buffer by comparing 'end' with
      the length of the buffer. We can also check that 'where' is a rejecting state, which it is necessarily.
      The component 'where' is necessary in order to resume reading if we have to reload the buffer. Indeed,
      despite the fact that the sequence delimited by 'start' and 'end' was rejected, it is still possible
      that it is the beginning of an acceptable token that can be recognized only after the buffer is reloaded.

   accepted(where,start,end,current) means:
      - a token is accepted which is delimited by 'start' and 'end',
      - 'current' is the current position of reading (it is always greater then or equal to 'end'),
      - 'where' is the state which was current when the token was accepted.
      In this case, the reason why we need to know the current position of reading is the following.
      Assume that "a" is an acceptable token, that "abc" is another acceptable token, but not "ab", and that the last
      two bytes of the input are "ab". In other words, "abc" could be accepted after the buffer is reloaded. In
      this case, the lexer reads "a" and "b" and is obliged to return because at the end of the input buffer. It
      had first accepted "a" as a token, so that there is a last accepted token, and it returns:

        accepted(w,s,e,c)

      where 'w' is the state which was current just at the moment the token "a" was accepted, and where
      's' and 'e' delimit this token "a". In other words, assuming that the length of the buffer is 10, "a" is
      at position 8 and "b" at position 9. We have 's' = 8 and 'e' = 9. But we also have 'current' = 10, because
      the buffer was read to its end. Here, we need to know 'current' because if we knew only 'end', we could not
      know that the buffer must be reloaded. Notice that despite the fact that the lexer returns accepted, the state
      reached after reading "b" is rejecting. However, the state 'w' is an accepting state because it is the state
      which was current just after reading "a".

   ignored_to_end(where) means:
      The lexer did not accept not reject anything but saw only tokens to be ignored (maybe many of them, since
      it doesn't return when ignoring tokens), and reached the end of the input buffer. The component 'where'
      is important for restarting the lexer in the right state after a reloading of the buffer.

   The above informations were of course essential for the writting of 'library/fast_lexer_5.anubis'.

   Now, here is the tool for making a fast lexer. First, the return type of 'make_fast_lexer':

public type MakeFastLexerResult:
   // error conditions:
   unknown_state(Word16),          // found a transition to a non existing state
   too_many_states,                // maximum is 65530
   // otherwise, the fast lexer itself (this is a function discussed below):
   ok((ByteArray                   input,
       FastLexerLastAccepted       last_accepted,
       Int                         current_reading_position,
       Int                         token_start,
       Word16                      starting_state) -> FastLexerOutput).

public define MakeFastLexerResult
   make_fast_lexer
     (
       List(FastLexerState)        lexer
     ).

   Hence, the low level fast lexer itself is a function of type:

      (ByteArray                   input,
       FastLexerLastAccepted       last_accepted,
       Int                         current_reading_position,
       Int                         token_start,
       Word16                      starting_state)
         -> FastLexerOutput

   The arguments are:    - the input buffer
                         - a possible last accepted token position
                         - the current position of reading within the buffer (where to resume reading)
                         - the position where the currently read token candidate starts within the buffer
                         - the state into which to resume reading

   'token_start' is where the currently read token begins in the input buffer. Actually, this will be actual
   beginning of the returned token if a token is recognized and if nothing is ignored before a token is recognized.
   If nothing is ignored, this will be the beginning of either a recognized token or of a rejected lexeme.

   The reason for the above arguments is mainly that when the low level lexer is called again, a token
   was maybe already partially read. For example, we can have this ("abracad" was already read by a previous call):

         "abracadabrantesque ..."
          ^   ^  ^     ^
          |   |  |     |
          |   |  |     c
          |   |  reading position
          |   last accepted
          start of token currently read

   which means that we have already read "abracad", that "abra" was accepted (that "abrac", "abraca" and "abracad"
   were not accepted) and that we restart reading after "abracad". If we cannot accept a token longer
   than "abra", accepted(s,0,4,c) will be returned (where c is the curent position of reading when the call returns)
   and at the next call, we have to read form position 'last_accepted' in the state 's' which was current when this
   token was accepted).


      *** (13.3) Precompiled fast lexers.

   It is possible to 'precompute' a fast lexer at compile time, so that you don't have to
   compute it at run time (nevertheless, it is sometimes necessary to compile a lexer at run
   time if regular expressions are given only at run time). The result of this precompilation
   is a datum of type:

public type PrecompiledFastLexer:
   precompiled_fast_lexer(ByteArray    fba,     // the two (opaque) byte arrays which are the actual fast lexer
                          ByteArray    sba).

   The following function transforms a list of fast lexer states into a precompiled fast
   lexer:

public type PrecompiledFastLexerResult:
   unknown_state(Word16),          // found a transition to a non existing state
   too_many_states,                // maximum is 65530
   ok(PrecompiledFastLexer).

public define PrecompiledFastLexerResult
   precompile_fast_lexer
     (
       List(FastLexerState)        lexer
     ).

   The type PrecompiledFastLexer is serializable. Hence the precompiled fast lexer can be
   stored into a file for example, or send accross the network. It is also possible to
   transform a precomplied fast lexer into an Anubis source text, since there is the
   { ... } notation for 'lexical' byte arrays. This possibility is used
   in 'library/lexical_analysis/fast_lexer_5.anubis'.

   For retrieving a fast lexer from a precompiled fast lexer, use the following:

public define (ByteArray                   input,
               FastLexerLastAccepted       last_accepted,
               Int                         current_position,
               Int                         token_start,
               Word16                      starting_state) -> FastLexerOutput
   retrieve_fast_lexer
     (
       PrecompiledFastLexer   pl
     ).


   *** (14) Dynamically linking an external library.

   anbexec can be dynamically (i.e. during  its execution) linked with an external library
   (*.dll under Windows or *.so under linux).


      *** (14.1) Overview.

   In  order to  link  anbexec to  a  library, you  actually need  to  create yourself  an
   intermediate library,  some kind of 'glue' to  be put between anbexec  and the external
   library.  This  intermediate library  may also be  seen as  a wrapper for  the external
   library.  From now on  we will  call it  the 'wrapper'.  anbexec communicates  with the
   wrapper but not directly with the external library.

                       +-----------+         +----------------------+
                       |  anbexec  | <-----> |   wrapper            |
                       +-----------+         |       +------------+ |
                                             |       |  external  | |
                                             |       |  library   | |
                                             |       +------------+ |
                                             +----------------------+

   Of course,  the role  of the  wrapper is essentially  to transform  data in  the Anubis
   format into  data in the  external library format  and conversely.  The wrapper  may be
   written in any language able to  produce dynamic libraries. However, for the purpose of
   these explanations, we assume that the external library has a C interface, and that you
   write the wrapper functions in C.


      *** (14.2) Restrictions.

   Since anbexec  is mulitasking by itself,  it cannot wait for  anything, otherwise other
   virtual machine will  not work. For that reason,  it is fundamental that any  call to a
   library  function   returns  quickly.   You  must   arrange  so  as   to  satisfy  this
   requirement. For example, if  the call must wait for something, you  must arrange so as
   to nevertheless return and come back later.


      *** (14.3) How data are transmitted.

   You  want to call  the interface  functions of  the external  library from  within your
   Anubis program.   Of course, data  do not necessarily  have the same  representation in
   Anubis and in the library.  This is  why each external library function must be wrapped
   into a function of your own that we call a 'wrapper function'.

   Here is how the call is executed:

      - your input data needs to be serialized into a byte array,

 public define TempByteArray       tempserialize($T d).

        The type 'TempByteArray'  is similar to 'ByteArray' except that  it is opaque from
        the Anubis viewpoint.  You cannot do  anything with a temporary byte array, except
        transmit it to the function 'wrapper_library_call' (to be declared below).

      - back to Anubis code, this second byte array is  unserialized in  order to  produce
        output data.

      - This result must be unserialized using:

 public define Maybe($U)           tempunserialize(TempByteArray s).

   The advantage of this  method is that it preserves the integrity  of Anubis in the sens
   that if the byte array constructed by  the wrapper function is incorrect, the result of
   unserializing  it  will just  be  'failure', and  nothing  illegal  will happen  within
   anbexec.

   The reason  why there are two  distinct types 'ByteArray' and  'TempByteArray', and two
   distinct families  of function serialize/unserialize  and tempserialize/tempunserialize
   is that the  temporary functions allow more types  to be serialized/unserialized. These
   functions can serialize/unserialize the types 'Opaque(Name)' to be discussed below.


      *** (14.4) Loading the external library.

   The external library  (actually the wrapper library) must be loaded  before you can use
   it. This is acheived by:

public type Library:...    an opaque type

public define Result((Word32, String), Library)
   load_library
     (
       String    library_name
     ).

   A result of  'error' means that the library  has not been loaded. You will have the  OS
   dependant error code and message into the  (Word32, String) pair.  In  this case  check
   that  the library  exists and  that its  name is  well written.   There is  no  need to
   'unload' the library.  This is done automatically by the garbage-collector when needed,
   i.e. when you have no more reference to the datum of type 'Library'.


      *** (14.5) How to call a library function.

public type LibraryCallError:
   symbol_not_found,
   error(Word32 error_code, String message).

public define Result(LibraryCallError, ByteArray)
   library_call
     (
       Library      library,
       String       name_of_function,
       ByteArray    arguments,
       Int          ideal_output_size
     ).


   Here is what happens when 'extension_library_call' is called:

     (1) the wrapper function is searched by its name (which is 'name_of_function' above),
         if not found, 'error(symbol_not_found)' is returned.
     (2) the wrapper function is called on 'arguments' and 'ideal_output_size':
       (2a) Anubis allocates an output buffer of size 'ideal_output_size'.
       (2b) Anubis calls the function (possible exceptions are catched). If anything
            goes wrong, the output buffer is freed and 'error(external_call_failed)'
            is returned. Otherwise, 'success(b)' is returned, where 'b' is the byte array
            containing the result (in serialized form).

   The fourth parameter (ideal_output_size) must be set to the ideal output size for that
   function. Knowing what the function should do, the caller can make a better choice for
   the default size of the output ByteArray. Don't worry, if the size is too small (this may
   be the case when the output size can't be known exactly), the VM will increase the buffer
   to the correct size and make a new try (see next paragraph).


      *** (14.6) How to write an extension function.

   Again, we assume that  the wrapper is written en C.  An extension function (let's call it
   'my_extension_function') is declared like this:

   int my_extension_function
       (
         void * input_parameters,     // buffer containing serialized data (not the ByteArray itself, but the data it contains)
         size_t input_size,           // size of the input buffer
         void * ouput_buffer,         // buffer where output data must be put by the library function
         size_t * output_size         // size of the output buffer
       );

   The returned value should be 0 if the function has been successfully executed. Negative
   numbers represents error code (TODO: document error code). One of them has a special meaning:
   NEED_MORE_MEMORY (-2). The function should return this code if the output buffer is too
   small.
   Whether the function succeeds or not, the desired (or real) output size should be set into
   the output_size parameter. In case of failure, the Anubis VM will call it again giving it an
   output buffer of the expected size. In case of success, the ByteArray will be resized to the
   correct size.


      *** (14.7) Description of data format.

   The input datum (say of type 'T' as above) and the output datum (of type 'U') are
   in the 'Anubis  serial format'. It could  have been possible to explain  this format in
   details here, but we have prefered to provide a 'description tool', much more handy for
   you.

   If you want  to now how the type  'T' is serialized, just write  this special paragraph
   within an Anubis source file:

 describe T.

   Of course,  as usual, the  initial keyword 'describe'  must be written in  the leftmost
   column.  The keyword 'describe' must  be understood as 'describe the serialization of',
   since this  is not  the type  which will  be described but  how data  of this  type are
   serialized.  Write as many such paragraphs as  you need. You may also put several types
   in a single paragraph, for example:

 describe T, U, V.

   These  paragraphs  produce  a   file  named  'serializations.txt'  containing  all  the
   informations  you need  about the  format of  the data  you want  to exchange  with the
   external library. Notice  that if the type 'T'  has a component of type 'S',  it is not
   necessary  to  ask  for  the  description  of  type  'S'.  The  above  paragraphs  work
   recursively.


      *** (14.8) External concrete data housekeeping.

   External libraries often  make use of pointers to  structures (in the sens of  C) or of
   'handles'  for  holding  opaque  informations.   These  data,  which  are  returned  by
   particular library  functions, must in general be  kept in some safe  place before they
   are used (one or several times) as arguments of other library functions. They must also
   eventually be  given to  a 'delete' function  provided by  the library for  freeing the
   structure.

   Of course, the wrapper library cannot  in general keep these pointers for many reasons,
   for  example  the  fact that  anbexec  performs  its  own  multitasking. They  must  be
   encapsulated into  Anubis data, and kept  by Anubis itself.  For this reason we  have a
   special primitive type:

                                           Opaque(Name)

   This type is opaque  at the level of Anubis, as its  name indicates. The parameter Name
   is any Anubis symbol beginning by an upper case letter. There is no need to define such
   a type.

   So, we only need to explain how data of this type are handled in a wrapper function.

   The serialization of a datum of type 'Opaque(Name)' is as follows:

                 +-----------------+-----------------+--------------------------------+
                 |       del       |        n        |         n bytes of data        |
                 +-----------------+-----------------+--------------------------------+
                                   ^
                                   |
                                   ptr


   The first  field 'del'  (4 bytes) is  the address  of the delete  function if  one such
   function is needed. Otherwise, it must be  0.  The second field (4 bytes) is the number
   of bytes of data.

   When the  garbage-collector decides to delete  the structure, it just  applies 'del' to
   'ptr' (only  if 'del' is  not 0 of  course), where 'ptr' is  as indicated on  the above
   figure, i.e. 'ptr' point to where the number of data bytes is stored.

   Be  careful:  The data  you  put  into  an 'Opaque'  must  not  be shared  between  two
   'Opaque'. Otherwise,  the garbage collector  may free the  first 'Opaque' and  call the
   'del' function, making the data in the second Opaque meaningless.

   Be careful:  Deletion of opaque data by  the garbage-collector may require the presence
   of the library. Hence, you must  ensure  that  the library  is not collected before all
   opaque data are collected.

   Be careful:  The order  of the  bytes within 'del'  and 'n'  is not  necessarily little
   endian. It must be the byte order of the underlying machine.


      *** (14.9) Calling back an Anubis function from within a library function.

   It is sometimes (often ?) the case that a library function requires a 'callback function'
   as one of its arguments (what is explained here is easily extendable to several callbacks).
   Consider a library fonction f of type T -> U as above, and assume that f (a C function)
   needs to call the Anubis function g, say of type V -> W.

   Intead of defining the return type of f as U, define it as:

   type Return_for_f:
      call_g(V),
      finished(U).

   and define the wrapper function for f so that it gives to f as the callback argument
   a function g1 declared (in C) as:

   W1 g1(V1)

   where V1 (resp. W1) is the C counterpart of V (resp. W), and defined as follows:

   W1 g1(V1 v)
   {
     return 'the serialisation of call_g(v)';
   }

   Hence the wrapper function for f does as if  ...

        (... still under construction ...)


   *** (15) Generic Database interface (dbapi).

      *** (15.1) DB Clients.

public type DbClient:
  db_oracle,
  db_sqlserver,
  db_interbase,
  db_sqlbase,
  db_odbc,
  db_db2,
  db_informix,
  db_sybase,
  db_mysql,
  db_postgresql,
  db_sqlite.

      *** (15.1) Errors.

   Errors returned by the DBAPI library  are formated into the following type. The first
   component is the DBAPI code of the  error. The second component in the alternative is
   a english  text giving an explanation  on the error.

public type DbError:
  db_error(Word32   code,
           String   text).


      *** (15.2) Connecting to a data base.

   A database must be opened before  any operation may take place. The resulting 'database
   handle' as an Anubis datum is of the opaque type:

public type Database:...

   In order  to open  (or create,  if it  does not exist)  the database  you just  have to
   provide the name (path) of the file which contains (or will contain) the data base:


public define Result(DbError,Database)
  db_connect
  (
    String    dbstring,
    String    user,
    String    password,
    DbClient  client
  ).

   If the database cannot be opened or created an error is returned.

   You  don't need  to close  the database.  The garbage-collector  calls  the appropriate
   function for closing the database when needed.


   Returns the database server connection status for a particular connection object

public define Bool
  db_is_alive
  (
    Database db
  ).


public type DbVersion:
  db_version(Word16 major, Word16 minor).

public define DbVersion db_server_version( Database db ).
public define DbVersion db_client_version( Database db ).

      *** (15.3) Data types.

   The  data which  may  be put  in the  cells  of a  table  may be  of several  different
   types. The following type definition is adhoc for handling such data.

public type DbDatum:
  no_such_column, // returned if you are asking for a datum from a non existing column
  db_bool     (Bool),
  db_integer  (Int),
  db_float    (Float),
  db_datetime (Date_and_Time),
  db_text     (String),
  db_blob     (ByteArray),
  null.


      *** (15.4) Querying a database.

   If you  have a database  handle, you can  query the corresponding database.   The query
   itself is a  DbCommand.  The  string may  also contain  'parameters', in  the form
   ':name' for representing  literal data.  These parameters must be  bind to actual data.
   Remark: any non bound parameter is by default bind to 'NULL'.

   The result of a query is a table (if  no error occurs). A table is a finite sequence of
   rows, and each row is a list of DbDatum. There is also a row of headers (a list of
   String) containing the names of the columns (headers).

   However,  this table  is returned  in the  form of  a triplet  of functions.  The first
   function, of type:

                                          One -> List(String)

   returns (when applied  to 'unique') the list  of names (headers) of the  columns in the
   table.

   The second function is  the 'cursor' which may be used for  walking into the table. The
   cursor is of type:

                                           One -> DbRow

   where:

public type DbRow:
   error(DbError),            // an error occured
   no_more_row,                    // there is no more row in the table
   row(Int -> DbDatum).       // this is the next row

   The  cursor should  be called  repeatedly and  returns one  row at  each call  until it
   returns 'no_more_row'.  A  row is returned in  the from of a function  mapping a column
   number (beginning at  1) to a datum.  Be careful because this function  is volatile. It
   must be used before you go to the next row.

   You may also reset  the cursor in order to reexecute the  same query, normally with new
   values of the parameters. A 'reset function' of type:

                            List(DbBind) -> DbQueryResult

   is used for this purpose. The argument is a list of parameter bindings:

public type DbBind:
  db_bind(String name, DbDatum value).

   The result of the reset function is of type:

public type DbResult:
  error(DbError),           // some error occured
  ok.                            // the query has been reset successfully

   For example, in  order to bind the parameter  whose name is ':ga' to  the integer value
   34, the parameter ':bu'  to the string "bu", and to reset  the query, use the following
   (assuming that the reset function is represented by the symbol 'reset'):

                     reset([db_bind(":ga", db_int(34)), db_bind(":bu", db_string("bu"))])

   The query must  be 'initiated' (or 'prepared' in the Sqlite3  terminology). This is the
   job of the  function sqlite3_query declared below. It returns a  datum of the following
   type:

public type DbQueryResult:
   error(DbError),                              // an error occured
   ok(One -> List(String)            headers,   // for getting the list of column names
      One -> DbRow                   cursor,    // for getting the rows, one at a time
      List(DbBind) -> DbResult       reset).    // for binding parameters and reseting

   You initiate the query with the following:

public define DbQueryResult
   db_query
     (
       Database         db,                   // the database
       String           sql_command,          // the SQL query
       List(DbBind)     initial_bindings      // initial parameter bindings
     ).

   For  your convenience,  we  also  provide the  following  variant to  be  used when  no
   parameter binding is needed.  This is the  case whenever the SQL query does not contain
   any parameter name.  In this case the reset function returned  by sqlite3_query is also
   of no use.

public define DbQueryResult
   db_query
     (
       SQLite3DataBase        db,
       String                 sql_command
     ).

public define DbQueryResult
   db_stored_procedure
     (
       SQLite3DataBase        db,
       String                 procedure_call
     ).

   *** Low level DBAPI Interface (August 2008).

/**
 * A precompiled statement.
 */

public type DbStmt:...

/**
 * Compiling An SQL Statement
 *
 * To execute an SQL query, it must first be compiled into a byte-code program using one of these routines.
 * The first argument, "db", is a database connection obtained from a prior call to db_connect().
 * The second argument, "sql_command", is the statement to be compiled, encoded as UTF-8.
 * On success, it returns a compiled prepared statement that can be executed using db_step().
 */

public define Result(DbError, DbStmt)
   db_prepare
     (
       Database         db,                   // the database
       String           sql_command           // the SQL query
     ).

/**
 * Binding Values To Prepared Statements
 *
 * In the SQL strings input to sqlite3_prepare(), literals may be replaced by a parameter in one of these forms:
 *
 *    * ?
 *    * ?NNN
 *    * :VVV
 *    * @VVV
 *    * $VVV
 *
 * In the parameter forms shown above NNN is an integer literal, and VVV is an alpha-numeric parameter name.
 * The values of these parameters (also called "host parameter names" or "SQL parameters") can be set using the
 * sqlite3_bind() function.
 */

public define DbResult
   db_make_bindings
     (
       DbStmt        stmt,
       List(DbBind)  bindings
     ).

/**
 * Evaluate An SQL Statement
 *
 * After a statement has been prepared using db_prepare(), this function must be called once
 * to evaluate the statement.
 */
public define DbResult
   db_execute
     (
       DbStmt        stmt,
     ).

/**
 * Retrieves statement rows
 *
 * After a prepared statement has been evaluated using db_execute(), this function must be called one or
 * more times to retrieve each row.
 */
public define DbRow
   db_step
     (
       DbStmt        stmt,
     ).

/**
 * Returns the column count for the current statement.
 */
public define Int
   db_column_count
     (
       DbStmt     stmt
     ).

/**
 * Reset A Prepared Statement Object.
 *
 * The sqlite3_reset() function is called to reset a prepared statement object back to its initial state, ready
 * to be re-executed. Any SQL statement variables that had values bound to them using the sqlite3_bind() API retain
 * their values.
 */
public define DbResult
   db_reset
     (
       DbStmt        stmt,
     ).

/**
 * Low level utility function allowing to construct a SQLite3QueryResult from a prepared and eventually binded statement.
 * This function is used by higher level function 'sqlite3_query'.
 */
public define DbQueryResult
  make_DbQueryResult
  (
    DbStmt        stmt,
  ).


   *** (16) Confining.

   For security reasons, it may be necessary to ``confine'' the execution of certain terms.
   This means that the resources allocated to the computation of this term are limited in
   space, in time, and in priority.

   If the execution of a term is confined, its execution can fail because one of the
   resources is exhausted. Hence, if the type of the term is (say) $T, the type of
   result returned by the confinement is more elaborate:

public type ConfineResult($T):
   out_of_system_memory,  /* the memory of the whole system (anbexec instance) is exhausted */
   out_of_memory          (Int   kbytes_used),    /* the memory allowed for the confined term is exhausted */
   out_of_time            (Int   millisec_used),  /* the computation time allocated to the confined term is exhausted */
   ok                     ($T).  /* no limitation was reached */

   The confinement is parametrized by a list of options:

public type ConfineOption:
   memory   (Int     kilobytes),     /* max memory which can be allocated for execution of the confined term */
   time     (Int     milliseconds),
   priority (Word8   level).         /* 255 is the highest priority */

   The syntax of the confine primitive is as follows:

public define ConfineResult($T)    confine(List(ConfineOption)     options,
                                           $T                      confined).


   Note: What happens if the memory of the whole system is exhausted ?
         If there is no confinement, anbexec waits for some memory to be liberated.
         Precisely, the scheduler runs only the processes which don't allocate memory
         or which allocate small enough segments of memory.
         This can be enough for restarting properly.

         On the contrary, if this happens during the execution of a confined term,
         the result of this execution is 'out_of_system_memory(...)' and most segments
         allocated during the execution of the confined term are liberated. Hence, this
         is more radical, and it may be a good idea to confine parts of your program.


   *** (17) Manipulating types and terms as data.

   This is new to version 1.14. Have a look at the 'New Anubis Manual 1.14' in order to have examples
   of use of these new features. This system is inspired by the well known system of macros of LISP,
   the most powerful system of macros ever. Because the syntax of Anubis which is not very complex
   is still more complex than the ultrasimple syntax of LISP, the system needs relatively complex data
   types (below), but fundamentally, the system is almost the same as LISP's.

   Before we embark into the description of this system, we recall that since version 1.13.3, we
   have the possibility to define a top-level function as a 'macro' via a paragraph such as:

   define macro <return type>
      <function name>
      (
        <arguments>
      ) =
      <body>.

   The difference with the same definition without the keyword 'macro' is that when it is defined
   as a macro, a term of the form:

       <function name>(...)

   does not call the function. On the contrary, the code of the function (the <body>) replaces
   the applicative term above after the occurences of the formal arguments have been replaced
   by the actual arguments (Note: this replacement is done cleanly, and no capture of variable
   can occur). The consequence is that an argument which is not used by the function is not
   computed and an argument which is used twice by the function is computed twice. Hence, this
   feature must be used with care. More on this in the 'New Anubis Manual 1.14'.

   We want to be able to consider types, terms and paragraphs as data, so that we can perform manipulations
   on them, and in particular go back and forth between syntax and semantics even within terms.
   This is realized through the following.

      *** (17.1) Types for describing Anubis types.

public type AnubisType:...          // defined below

public type AnubisPrimitiveType:    // the actual type names prefixed by an underscore
                                    // all these types are documented in this file
   _ByteArray,
   _Float,
   _Int,
   _Listener,
   _MVar(AnubisType),
   _RStream,
   _RWStream,
   _String,
   _StructPtr(String name),
   _Var(AnubisType),
   _WStream.

public type AnubisType:
   parameter       (String name),                              // $T    (the 'name' does not includes the $)
   primitive       (AnubisPrimitiveType),
   functional      (List(AnubisType) sources,                  // (T1,...,Tk) -> U
                    AnubisType       target),
   instance        (Int              id,                       // unique id of instance of type
                    String           name,                     // For example:  List(String)
                    List(AnubisType) operands).                //          or:  Result(Error,$T)
                                                               //    but also:  Bool   (with an empty list of operands)

public type AnubisComponent:
   comp   (AnubisType        type),        // anonymous component
   comp   (AnubisType        type,
           String            name).

public type AnubisAlternative:
   alt   (String                  name,           // the name can be a convention like "[.]" for non-empty lists
          List(AnubisComponent)   components).    // for example:  [$T h . List($T) t] is represented by:
                                                  //    alt("[.]",[arg(parameter("T"),"h"),
                                                  //               arg(instance("List",[parameter("T")]),"t")])


      *** (17.2) Types for describing Anubis terms.

public type AnubisTerm:...        // defined below

public type AnubisArg:
   arg    (AnubisType        type,
           String            name).

public type AnubisCase:     // case in a conditional
   _case   (String            name,
            List(AnubisArg)   resurgent_symbols,
            AnubisTerm        body).

public type AnubisTerm:
   _apply       (AnubisTerm         function,          // f(a,b,c)
                 List(AnubisTerm)   arguments),
   _byte_array  (ByteArray          content),
   _cond        (AnubisTerm         test,              // if <test> is { ... cases ...}
                 List(AnubisCase)   cases),
   _integer     (Int                value),
   _delegate    (AnubisTerm         priority,
                 AnubisTerm         delegated,         // delegate <delegated>, <body>
                 AnubisTerm         body),
   _float       (Float              value),
   _function    (List(AnubisArg)    arguments,         // (X x, Y y) |-> <body>
                 Maybe(String)      function_name,     // (X x, Y y) |-f-> <body>
                 AnubisTerm         body),
   _micro_symbol(String             name),             // appears within the body of |-> function when not an argument
   _of_type     (AnubisType         type,              // (<type>)<term>    (explicit typing)
                 AnubisTerm         term),
   _operation   (String             name,
                 Int                id),
   _protect     (AnubisTerm         protected),
   _read        (AnubisTerm         v),                //  *v
   _select_cond (AnubisTerm         test,
                 Int                index_of_selected,
                 AnubisCase         selected_case,
                 AnubisTerm         default),
   _serialize   (AnubisTerm         term),
   _small_datum (AnubisType         type,
                 Int                value),
   _string      (String             value),
   _symbol      (String             name),
   _type_desc   (AnubisType         type),
   _unserialize (AnubisType         type,
                 AnubisTerm         byte_array),
   _wait_for    (AnubisTerm         condition,
                 AnubisTerm         body),
   _with        (String             symbol,            // with <symbol> = <value>, <body>
                 AnubisTerm         value,
                 AnubisTerm         body),
   _write       (AnubisTerm         v,                 // v <- value
                 AnubisTerm         value).


      *** (17.3) Types for describing Anubis instances of types and data.

   This stuff is used by the -a2a ('Anubis to Anubis') option.

   In Anubis, paragraphs may be schemas, i.e. contain type parameters (such as '$T').
   This is true for type definitions and for data definitions. An 'instance' of
   a paragraph is obtained by replacing type parameters by actual types.

public type AnubisScope:
   private,
   public.


public type AnubisTypeInstance:
   type          (Int                             id,               // unique id of instance of type
                  AnubisType                      the_type,         // description of type
                  Maybe(List(AnubisAlternative))  alternatives).    // alternatives if it is a sum type

public type SyscallName:                                   // examples (see compiler/src/predef.anubis):
   simple        (String                   name),          // strconcat
   parametrized  (String                   name,           // word_to_hexa
                  Int                      parameter).     // 16

public type AnubisDatumInstance:
   constructor   (Int                      id,             // unique id of constructor
                  String                   name,
                  Int                      index,          // alternative number for this constructor
                  List(AnubisType)         source_types,
                  AnubisType               target_type),   // which is the type the constructor belongs to
   primitive     (Int                      id,             // primitive function of the Anubis system
                  String                   name,
                  Int                      line,           // line number in 'predef.anubis'
                  SyscallName              syscall_name,   // name of syscall
                  AnubisType               type),
   datum         (Int                      id,             // unique id of instance of datum
                  String                   name,           // name of defined datum (all instances have the same name)
                  String                   filename,       // absolute path of file where the datum is defined
                  Int                      line,           // line where it is defined
                  AnubisScope              scope,
                  AnubisType               target_type,
                  List(AnubisArg)          arguments,
                  AnubisTerm               body).


      *** (17.4) Evaluating and quoting.

   Before going further we need to be precise about what we call a ``syntactic type''.
   By definition, a ``syntactic type'' is one of the types defined in section (17.1)
   and section (17.2). They all begin by 'Anubis'. A datum whose type is a syntactic
   is called a ``syntactic datum''.

   If t is a term of type AnubisTerm, interpretable in the empty local context
   (which means that it does not depend on declared symbols with unknown values),
   its value can be computed. This value is not a ``term'', but a datum of type
   AnubisTerm, i.e. a syntactic datum.

   Since any datum of type AnubisTerm clearly represents a term, you may want to insert
   this term at some position into your source text. In other words, instead of writting
   this term yourself, you compute it by a program (which is t above), and want to insert
   the result of this computation into the text. This can be done as follows:

       @t

    Indeed, when it encounters this expression, the compiler first computes the value
    of t (which is a datum of type AnubisTerm) and does as if it had read the term
    represented by this value instead of @t.

    It is also possible to write  @t  if t is not interpertable in the empty context.
    In this case the compiler does not compute anything, and keeps  @t as is. t will
    be computed later when used at an other place. For example, you can have this:

    define macro Int
       my_number
       (
         Int n
       ) =
       @_integer(n).

    which will not produce any computation because at this point, the value of n is
    not known. However, the compiler can check that  _integer(n)  is a correct datum
    of type Later you can write:

       my_number("34")

    the compiler will compute this term

    For this reason, @ is called the ``evaluation operator'', but it produces only
    things ready to be inserted into the text. When you write @t, the type of t must
    be a syntactic type, i.e. one of those defined in sections (17.1) and (17.2). In
    other words, the above discussion is also valid for any of these types. For example,
    if t is of type AnubisCase, you can write something as:

        if x is
        {
          failure then 0,
          @t
        }

     The compiler will replace @t by the value of t, and check the resulting expression.

     Maybe more surprisingly, if the type of t is AnubisCases instead of AnubisCase,
     writting this is permitted:

        if x is
        {
          @t
        }

     Of course, the resulting conditionnal is checked by the compiler, and is incorrect
     if the value of t does not represent an acceptable list of cases for the type of x.

     The expression   if x is { @t }  written like this in your source file is just an
     ordinary term, except that instead of writing some part of it you computed this part.

     Now, instead of producing such a term, you may want to produce the corresponding
     datum of type AnubisTerm. You could write this:

         _cond(_symbol("x"),@t)

      which clearly does the trick, but it is easier to write:

         'if x is { @t }

      i.e. the term itself prefixed by a quote. Indeed, if you put a single quote in front
      of a term, what you get is another term of type AnubisTerm whose value if the datum
      representing the quoted term. Of course, the same thing works for other expressions.
      For example, if t is a term of type AnubisTypes, then @t is an actual meta-list of
      types, and

          'List(@t)

      is a term of type AnubisType representing the same type as the term:

          _instance("List",@t)


      *** (17.5) Generating custom compiler error messages.

   This system allows to extend the syntax of Anubis and so requires that we can
   also extend the behavior of the Anubis compiler.

   The system described here allows to compute terms to be inserted (using @) into the text
   of the source file. Hence, you can define functions for performing such computations. During
   these computations it is possible that the data used for generating these terms is
   not conform to what is expected. In other words, the function computing the term should
   be able to generate a 'compiler error message'. This is achieved through the following tool:

                    compiler_error_message(message_text)

   and of course also:

                    compiler_warning_message(message_text)

   where 'message_text' is a term of type String.

   When the compiler encounters one of these terms, it first computes the argument
   'message_text' and prints the message on the console (of the compiler). In case
   of an error message, an error is counted, so that the current paragraph is flagged as
   incorrect. In the case of a warning, no error is counted, and the paragraph may
   still be correct.

   These terms are of type One.

   For example, you may want to define a tool returning the name of a symbol, to be used only
   with symbols. You can do this:

   public define macro String
      name_of_symbol
      (
        AnubisTerm t
      ) =
      if t is _symbol(name) then name
      else (compiler_error_message("The term: '"+format(t)+"' is not a symbol.");
            "").

   For example,   name_of_symbol('x)   will return "x", and   name_of_symbol('f(x)) will
   generate a compiler error message.

   It is important to define 'name_of' as a macro, since the code of the function will
   replace the term name_of(...). Indeed, the consequence is that the file, line and column
   indicated in the error message are those of this term not those of the definition of
   'name_of'.


      *** (17.6) Getting the definition of a type or of a term.

   The following is a regular term:

       definition_of_type <name>

   where <name> is a term of type String which is the name of a type schema visible at that point.
   The term   definition_of_type(<name>)   has type  AnubisTypeDefinition  provided that the compiler
   actually finds the type. If the compiler does not find the type, an error message is
   sent.

   Similarly, you can write:

       definition_of_term (<type>) <name>

   where <type> is a term of type AnubisType and where <name> a term of type String. If the
   compiler finds the type represented by <type> and finds a unique paragraph defining <name>
   of type <type>, the above term is of type AnubisTermDefinition and it is the definition of
   <name>. Otherwise, an error message is sent.


   *** (18) Find and replace.
      (Added August 2015 by AP)

   We define a 'multiple find and replace' tool. By 'multiple'
   we mean that we use a dictionary in the form of a list of pairs (key,value)
   and that the occurrences of any key are replaced (within a given text) by
   the corresponding value.

   You don't need to read this section because it contains only low level tools.
   The high level tools to be used are defined in 'library/tools/find_and_replace.anubis'.
   Nevertheless, below are the explanations for the low level tools.

   A key can be part of another key, but the function replaces the longuest
   possible occurrence. For example, if 'ab' and abc' are two keys in the
   dictionary, and if the text contains 'abc', the function replaces 'abc',
   not 'ab'.

   In order to be efficient, we compile the dictionary into an automaton
   and the automaton is executed by a syscall on the given text. The dictionary
   can be compiled in advance and the automaton used any number of times.
   This automaton uses Boyer-Moore-like techniques for searching, and we tried
   to make it as efficient as possible.


      *** (18.1) Compiled dictionaries.

   As said above, a dictionary must be compiled before it can be used. The type describing
   (user defined) dictionaries is defined in 'library/tools/find_and_replace.anubis',
   which also contains the dictionary compiler 'compile'. This 'dictionary compiler' produces
   a datum of type:

public type FR_CompiledDict:
   cdict    (ByteArray     automaton,     // the automaton proper
             ByteArray     jump_tables,   // an array of jump tables
             ByteArray     values).       // the array of replacement values for keys

   This type is clearly serialisable, so that you can save your compiled dictionary
   into a file and reuse it at will. However, you can imagine that completely incorrect
   compiled dictionaries can be produced, just because you can create arbitrary
   byte arrays.

   For this reason, a datum of type 'FR_CompiledDict' cannot be used before it is
   'certified'.


      *** (18.2) Certifying a dictionary.

   A certified dictionary is of type:

public type FR_CertifiedDict:...     (an opaque type)

   and you have the function:

public define Maybe(FR_CertifiedDict)      certify   (FR_CompiledDict  d).

   that you can call in order to certify your compiled dictionary. Of course,
   the result if 'failure' if the dictionary cannot be certified. This 'failure'
   does not give any information on the reason why the compiled dictionary
   cannot be certified. However, if you compile a 'user defined' dictionary
   with the function 'compile' defined in 'library/tools/find_and_replace.anubis',
   you get detailed informations on the reasons why your dictionary is not acceptable.

   Notice that if certification succeeds, this does not mean that your compiled
   dictionary will do the find and replace job correctly. It only means that
   the certified dictionary will not produce a crash nor a deadlock. We have
   enforced this filter in order to satisfy the axiom that 'an Anubis program
   can never end abnormally'. Of course, the type 'FR_CertifiedDict' is not serializable
   so that you cannot forge a dangerous datum of type 'FR_CertifiedDict' (at least
   if you don't modify anything in the very source of the Anubis compiler).

   If you want find_and_replace to work properly, you need to certify a dictionary
   produced by the function 'compile' defined in 'library/tools/find_and_replace.anubis'.

   The type 'FR_CertifiedDict' is actually a clone of 'FR_CompiledDict' (i.e. a datum
   of this type is a triplet of byte arrays). However, 'FR_CertifiedDict' has a 'OneNonSerial'
   component, so that it is non serializable, and its unique constructor
   has a private name not accepted by the user's version of the compiler. Consequently,
   you cannot forge a datum of this type.


      *** (18.3) Changing the array of values.

   Since the automaton and jump tables do not depend on the values associated to
   the keys, it is possible to change the array of values without modifying the
   other two byte arrays. This is performed by:

public define Maybe(FR_CertifiedDict)
   change_values
   (
     FR_CertifiedDict    d,
     ByteArray           new_values
   ).

   Of course, this can still fail because the new array of values must be compatible with
   the automaton.

   Don't try to construct the byte array 'new_values' by hand. Use the function 'make_values'
   defined in 'library/tools/find_and_replace.anubis' instead.


     *** (18.4) Replacing within a string or a byte array.

   When you have your certified dictionary at hand, you can use it for finding and replacing
   within a string or a byte array:

public define ByteArray  find_and_replace(FR_CertifiedDict d, ByteArray text).
public define ByteArray  find_and_replace(FR_CertifiedDict d, String    text).
public define String     find_and_replace(FR_CertifiedDict d, ByteArray text).
public define String     find_and_replace(FR_CertifiedDict d, String    text).

   Notice that the above functions do not produce any side effect. Indeed, the result
   they return is a fresh copy of the original text (except if nothing is to be
   replaced, in which case the original itself is returned).

   The above functions must be used only if 'text' is the whole text to be searched for.
   If your text arrives in chunks, you must use more sophisticated tools which are defined
   in 'library/tool/find_and_replace.anubis'. The next section below provides the
   corresponding low level tools.


     *** (18.5) Replacing by chunks.

   We must use two different functions for the last chunk and for the other chunks.
   For the last chunk, we use the function 'find_and_replace' declared in (18.4)
   above. For the other chunks, we use the following:

public define (Int,ByteArray)  chunk_not_last(FR_CertifiedDict d, ByteArray chunk).
public define (Int,ByteArray)  chunk_not_last(FR_CertifiedDict d, String    chunk).
public define (Int,String)     chunk_not_last(FR_CertifiedDict d, ByteArray chunk).
public define (Int,String)     chunk_not_last(FR_CertifiedDict d, String    chunk).

   These 'not last' functions return:

      - the number of bytes not searched for at the end of the chunk,
      - the result of the replacement in the chunk not including the bytes not searched for.

   More precisely: Since an occurrence of a key can span over two consecutive chunks, the
   'chunk_not_last' function stops searching when the number of bytes still to be searched in the
   input chunk is less than the maximum of the lengths of the keys in the dictionary. The number of
   bytes of text not searched for is returned together with the result of the replacement
   within the beginning of the chunk (i.e. the whole text minus these bytes not searched for).

   Hence, after the 'chunk_not_last' function returns, we must call it again but with a
   chunk including the bytes which were not treated by the previous call. If the source is
   a file, this can easily be performed by using the 'seek' mecanism.

   See 'library/tools/find_and_replace.anubis' for the realisation of this program.


public type DNS_Result:
  host_not_found,        // the name of the host has not been found in the data base
  no_address_found,      // the name has been found, but no corresponding address
  try_again,             // try again, because DNS server busy
  non_recoverable_error, // do not try again
  ok(Word32 address).    // ok, here is the wanted address


   *** Obsolete stuff.

public define String           to_ascii     (ByteArray s).    // obsolete; use 'to_hexa' instead

   --- Previous 'sql_query' (obsolete) ---------------------------------------------------

public type SQLite3HeadersOrRow:
  headers,
  next_row.

 public type SQLite3Row:
   error(SQLite3Error),
   no_more_row,
   row(Int -> SQLite3Datum).

public define Result(SQLite3Error, SQLite3HeadersOrRow -> SQLite3Row)
   sql_query
     (
       SQLite3DataBase        db,
       String                 sql_command
     ).


   The datum  of type 'SQLite3HeadersOrRow  -> SQLite3Row' which  is returned if  no error
   occurs, is  called a 'cursor'.  This  is a non  deterministic function which has  to be
   called repeatedly until it returns 'no_more_row'.  At each call before the last one, it
   returns a row of the resulting table in the form of a function of type:

                                      Int -> SQLite3Datum

   This  function,  when  applied  to  a   column  number,  returns  the  content  of  the
   corresponding cell. If it returns 'no_such_column', the column name was erroneous.

   Warning: since the  cursor is non deterministic,  you must be careful in  the orders of
   evaluation. Never  apply a cursor  to 'unique' within  the arguments of a  function (in
   particular, remember that the  list constructor '[ . ]' is such  a function). The right
   thing to do in  order to ensure that evaluation are performed in  the right order is to
   use the 'with' syntax. Indeed, in the term:

                                          with x = a, t

   it is warrantied that 'a' is evaluated before 't'.

   Also,  the  function  of  type  'Int  -> SQLite3Datum'  obtained  for  each  row  is
   volatile. It becomes meaningless at the next  call to the cursor. Hence, you should use
   it before going to the next row, i.e. before calling the cursor again.


   --- End of previous 'sql_query' -------------------------------------------------------


   Previous paradigm (obsolete):

public type LibraryError:
  cant_load_library,
  symbol_not_found,
  external_call_failed,
  unknown_error.

   In order to call an external library function, use the following:

public define Result(LibraryError, ByteArray)
   extension_library_call
     (
       Library      library,
       String       name_of_function,
       ByteArray    arguments,
       Int          ideal_output_size
     ).


   --- End of predefined.anubis ------------------------------------------------------