This is bigloo.info, produced by makeinfo version 4.5 from bigloo.texi.

  This file documents Bigloo, an implementation of an extended version
of the Scheme programming language.

  Copyright (C) 1992-99, 2000-02 Manuel Serrano

     This program is free software; you can redistribute it
     and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public
     License along with this program; if not, write to the Free
     Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
     MA 02111-1307, USA.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* bigloo: (bigloo).            The Bigloo Scheme compiler
END-INFO-DIR-ENTRY


File: bigloo.info,  Node: Top,  Next: Acknowledgements,  Prev: (dir),  Up: (dir)


                                         ,--^,
                                   _ ___/ /|/
                               ,;'( )__, ) '
                              ;;  //   L__.
                              '   \    /  '
                                   ^   ^

* Menu:

* Acknowledgements::             Brief history and helpers
* Overview::                     A brief summary of Bigloo facilities
* Modules::                      Modules description
* Core Language::                Syntax, expressions and definitions
* Standard Library::             The Bigloo standard library
* Pattern Matching::             Non linear Bigloo pattern matching
* Object System::                Documentation for the Bigloo object layer
* Threads::                      Bigloo threads
* Regular Parsing::              Pre-compiled regular grammars
* Lalr Parsing::                 Pre-compiled Lalr grammars
* Errors and Assertions::        Bigloo error handling and Bigloo assertions
* Eval::                         Use of the interpreter
* Macro Expansion::              The two available macro schemes
* Command Line Parsing::         Parsing binaries command line invocation
* Explicit Typing::              Improving the compiler's code quality
* C Interface::                  Interfacing to C
* Java Interface::               Interfacing to Java
* SRFIs::                        SRFIs supported by Bigloo
* Bigloo Libraries::             Creating and using your own libraries
* Extending the Runtime System:: Creating and using your own libraries
* DSSSL Support::
* Compiler Description::         Interfacing with the compiler
* User Extensions::              User compiler extensions
* Bee::                          The Bigloo development environment
* Global Index::                 Global Bigloo document index
* Library Index::                Index for forms, functions and variables
* Bibliography::


File: bigloo.info,  Node: Acknowledgements,  Next: Overview,  Prev: Top,  Up: Top

Acknowledgements
****************

  Bigloo has been developed at Inria-Rocquencourt by the Icsla team
from 1991 to 1994, at the University of Montreal in 1995 and at
Digital's Western Research laboratory in 1996, University of Geneva
during 1997 and from the end of 1997 at the University of Nice.

  I would like to express my gratitude to _Hans J. Boehm_ for his
Garbage Collector [BoehmWeiser88, Boehm91], _Jean-Marie Geffroy_ for his
pattern-matching compiler [QueinnecGeffroy92], _Dominique Boucher_ for
his Lalr grammar compiler, _William Clinger_ for his syntax expansion
implementation and _Dorai Sitaram_ for his contribution with the
`pregexp' package and its documentation. I also especially thank
_Christian Queinnec_ for all his useful remarks, help, suggestions and
teaching.

  Other people have helped me by providing useful remarks, bug fixes or
code improvements. I thank all of them and especially _Luc Moreau_,
_John Gerard Malecki_, _David Halls_ and _David Gurr_.

  I thank _Barrie Stott_ for his help in making much of the
documentation more idiomatic. Of course, any remaining errors are still
mine.

  This release of Bigloo may still contain bugs. If you notice any,
please forgive me and send a mail message to the following address:
<bigloo@sophia.inria.fr>.

  This is Bigloo documentation version {No value for `bigloovers'},
{No value for `bigloodate'}.


File: bigloo.info,  Node: Overview,  Next: Modules,  Prev: Acknowledgements,  Up: Top

Overview of Bigloo
******************

  Bigloo is an implementation of an extended version of the Scheme
programming language. Without its extensions Bigloo does not entirely
conform to Scheme as defined in the Revised(5) Report on on the
Algorithmic Language Scheme (henceforth R5RS) (see *Note Top:
(r5rs.info)Top).  The two reasons are:

   * Bigloo produces C files. C code uses the C stack, so some programs
     can't be properly tail recursive. Nevertheless all simple tail
     recursions are compiled without stack consumption.

   * Alternatively, Bigloo may produce JVM (Java Virtual Machine byte
     code) class files. These classes may use regular Java classes.

   * Bigloo is a module compiler. It compiles modules into `.o' or
     `.class' files that must be linked together to produce stand alone
     executable programs or JVM jar files.

  However, we designed Bigloo to be as close as possible to the R5RS.
Hence, when Bigloo includes a feature that is extracted from Scheme and
implemented as normal, this feature is only mentioned in this document
and not fully described.

SRFI
====

  The Bigloo version {No value for `bigloovers'} supports the following
SRFIs:

   * `srfi-0' (conditional execution).

   * `srfi-2' (AND-LET*: an AND with local bindings, a guarded LET*
     special form).

   * `srfi-6' (Basic String Ports).

   * `srfi-8' (Binding to multiple values).

   * `srfi-9' (_Records_ specification).

   * `srfi-18' (Multithreading support).

   * `srfi-22' (script interpreter invocation).

   * `srfi-28' (Basic Format Strings).

   * `srfi-30' (Multi-line comments).

Separate compilation
====================

  To allow and stimulate separate compilation, Bigloo compiles modules
instead of entire programs. A module is composed of a module
declaration and a module body, where a module body can be thought of as
an incomplete Scheme program.

  Bigloo strictly enforces variable bindings. That is, it is illegal in
a body to refer to unbound variables.

  In a module declaration, some variables can be declared to be
immutable functions. For such variables, the compiler can then check if
the number of arguments for some function calls are correct or not.
When an arity mismatch is detected, Bigloo signals an error and aborts
the compilation process.

C interface
===========

  The goal of the design of Bigloo is to allow the merging of high and
low level programming. This means that Bigloo is designed to be fully
connected to the already existing outside world of C.

  This connection has two components: a function call interface and a
data storage interface. Bigloo code is able to call C code and vice
versa; Bigloo data storage is accessible from C and vice versa. There
are no frontiers between the Bigloo and C worlds.

Java interface
==============

  Since release 2.3, Bigloo is able to produce Java Virtual Machine byte
codes in addition to C code. By producing class files, it is possible
to connect Scheme code and Java code in the same spirit as the Scheme
and C connection.

  This connection has two components: a function call interface and a
data storage interface. Bigloo code is able to call Java code and vice
versa; Bigloo data storage is accessible from Java and vice versa.
There are no frontiers between the Bigloo and Java worlds.

Object language
===============

  Since release 1.9, Bigloo has included an object system. This system
belongs to the CLOS [Bobrow et al. 88] object system family but whose
design has been mainly inspired by C. Queinnec's MEROON [Queinnec93]. It
is based on _ad-hoc_ polymorphism (generic functions and methods), uses
single inheritance and mono-dispatch, and provides the user with
introspection facilities.

Threads
=======

  Since release 2.4d, Bigloo has included a thread library. Bigloo
supports Fair threads that are cooperative threads run by a fair
scheduler which gives them equal access to the processor. Fair threads
can communicate using broadcast events and their semantics does not
depends on the executing platform. Fine control over fair threads
execution is possible allowing the programming of specific user-defined
scheduling strategies.

Type annotations
================

  Type information, related to variable or function definitions, can be
added to the source code. If no type information is provided, runtime
checks will be introduced by the compiler to ensure normal execution,
provided that the user has not used compilation flags to prevents this.
If type information is added, the compiler statically type checks the
program and refuses ones that prove to be incorrect.

Unicode support
===============

  Bigloo supports UCS-2 Character encoding and also provides conversion
functions between UTF-8 and UCS-2. It still maintains traditional
ISO-LATIN1 characters and strings.

DSSSL
=====

  Bigloo helps the DSSSL programmer by supporting keywords, named
constants and keyword functions.


File: bigloo.info,  Node: Modules,  Next: Core Language,  Prev: Overview,  Up: Top

Modules
*******

  A modules is a compiler entity. That is, the Bigloo compiler compiles
modules and then, link them against libraries in order to produce
executables. A module may be split into several files but a file cannot
contain more than _one_ module. A module is made of a module clause
that is a list for which the `car' is the symbol `module' and followed
by any Bigloo expression (that is definitions or expressions). The
module clause names the module and define the scope of the definitions.
At last, the module clause is also the place where foreign bindings are
defined and where classes are defined.

* Menu:

* Program Structure::
* Module Declaration::
* Module Initialization::
* Qualified Notation::
* Inline Procedures::
* Module Access File::
* Reading Path::


File: bigloo.info,  Node: Program Structure,  Next: Module Declaration,  Prev: Modules,  Up: Modules

Program Structure
=================

  A Bigloo program is composed of one or more Bigloo modules where a
module is defined by the following grammar:

     <module>             ==> <module-declaration> <module-body>
     <module-declaration> ==> the module declaration
     <module-body>        ==> the module body

  A module is not related to a specific file and can be spread over
several files if that is convenient. In particular, there is no
relationship between module names and file names. The module declaration
(see *Note Module Declaration::) must be the first expression in the
first of the files containing the module; other expressions form the
body of the module. The module body (see *Note Core Language::)
contains global variables and functions definition and _top level_
expressions (see *Note Expressions::).


File: bigloo.info,  Node: Module Declaration,  Next: Module Initialization,  Prev: Program Structure,  Up: Modules

Module declaration
==================

  The module declaration form is

 - bigloo syntax: module name clause ...
     This form defines a module and must be the first in the file.  The
     argument NAME is a symbol naming the module and, if the same
     module name is used more than once, Bigloo signals an error. The
     runtime library is composed of modules that are read when a user
     module is compiled so, if a user module has the same name as one
     of the library modules, an error is signaled.

     A simple module can be:

          (module foo)
          
          (display "this is a module")

     The first line here is the complete module definition, the last
     line is the complete module body and together they form a complete
     Bigloo program. If these lines were stored in file `zz.scm',
     invoking `bigloo zz.scm' would create the executable `a.out'
     which, when obeyed, would display `this is a module' on the
     terminal.

     _Note:_ Some special identifiers are reserved and can't be used to
     name modules.  If such an identifier is used, the compiler will
     produce the message:

          #(module t
          #^
          # *** ERROR:bigloo:TOP-LEVEL:Parse error
          # Illegal module name -- (MODULE eval ...

     The list of reserved identifiers may be enlarged for next release.
     For the current release that list is made of: `eval', `foreign' and
     `t'.

  Module CLAUSEs can be:

 - bigloo module clause: main name
     This clause defines the entry point for a stand alone application
     to be procedure NAME of arity one. Bigloo invokes this procedure
     at the beginning of execution providing the list, composed of the
     shell command line arguments, as its single argument.

          (module foo
             (main start))
          
          (define (start argv)
             (display argv)
             (newline))

     Then if this program is compiled into `foo' and invoked using the
     command `foo -t bar', the list which is the argument for the main
     procedure `start' would be `("foo" "-t" "bar")'.

     The special form `args-parse' helps main function argument parsing
     (*note Command Line Parsing::).

 - bigloo module clause: include file-name ...
     This is a list of FILE-NAME to be included in the source file.
     Include files are not modules and may have a special syntax. Thus,
     besides containing Bigloo expressions, they can contain import and
     include clauses, which must be written in a single list whose
     first element is the keyword `directives'. Includes files can be
     used to include implementation-neutral Scheme expressions and
     definitions in a Bigloo module. Here is an example of an include
     file.

          ;; `foo.sch'
          (define-struct point x y)

     and the module that includes the `foo.sch' file:

          ;; `foo.scm'
          (module foo
             (include "foo.sch"))
          
          (print (point 1 2))

     Include files, may contain module information. This is the role of
     the include `directives' clause here illustrated with the `bar.sch'
     example:

          ;; `bar.sch'
          ;; the directives
          (directives (include "foobar.sch")
                      (import  hux))
          
          ;; expressions
          (define (gee x) (print x))

 - bigloo module clause: import import ...
     An IMPORT is a list of the form:

          <import>      ==> <iclause> ...
          <iclause>     ==> (<bind-name> ... <bind-name> <module-name> <file-name> ...)
                          | (<bind-name> ... <bind-name> <module-name>)
                          | (<module-name>
                          | (<module-name> <file-name> ...)
          <bind-name>   ==> <r5rs-ident>
          <module-name> ==> <r5rs-ident>
          <file-name>   ==> <string>

     The first alternative in ICLAUSE imports the variable named
     BIND-NAME which is defined in the module MODULE-NAME, located in
     the files FILE-NAME .... The second does the same but without
     specifying the name of the file where the module is located.  The
     third and the fourth form import all the exported variables of the
     module MODULE-NAME.

     Note: The need for specifying in which files modules are located
     comes from the fact that there is no automatic mapping between
     module names and files names. Such a mapping can be defined in a
     "module access file" (*note Module Access File::) or in the import
     clause itself, as in the first and fourth alternatives in ICLAUSE
     above.

     Here is an example of an import clause:

          (module foo
             (import
                ;; import all `bar' exported bindings:
                bar
                ;; import the `hux' binding exported by
                ;; the module `hux':
                (hux hux)
                ;; import the `fun1', `fun2' and `fun3' bindings exported by
                ;; the module `mod':
                (fun1 fun2 fun3 mod)
                ;; import all `gee' bindings. the `gee' module
                ;; is located in a file called `gee.scm':
                (gee "gee.scm")))


 - bigloo module clause: use use ...
     `use' has the same meaning as `import' except that modules which
     are _used_ are not initialized (*note Module Initialization::).
     Used modules are read before imported modules.

 - bigloo module clause: with with ...
     This clause specifies a list of modules which have to be
     initialized at runtime and is used to force the initialization of
     modules which are never imported but which are required by an
     application (*note Embedded Bigloo applications::).

 - bigloo module clause: export export ...
     In order to make a module's global bindings available to other
     modules, they have to be _exported_. Export clauses are in charge
     of this task and an EXPORT is a list of the form:

          <export>  ==> <eclause> ...
          <eclause> ==> <ident>
                      | (<ident> <ident> ...)
                      | (inline <ident> <ident> ...)
                      | (generic <ident> <ident> <ident> ...)
                      | <class>

     The first form of ECLAUSE allows the variable IDENT be exported,
     the second allows the function IDENT, always regarded as immutable
     when exported this way, to be exported and the third exports an
     inline-procedure (*note Inline Procedures::) whose name is
     extracted from the first IDENT after the word INLINE. The last two
     are both connected with Bigloo's object system.  The GENERIC
     clause exports generic functions (*note Generic functions::) and
     CLASS clause exports classes (*note Class declaration::).

     Note: Only bindings defined in module `m' can be _exported_ by `m'
     (i.e. bindings _imported_ by `m' cannot be _exported_ by `m').

     Type information, specified in any IDENT in an export clause, is
     used by Bigloo. Where no type information is given, a default
     generic type named `obj' is used.

     Note: The last formal argument of a multiple arity function can
     not be typed because this argument is bound to be a `pair' or
     `null'. This union cannot be denoted by any type.

     Here is an example of the module `foo' that exports bindings:

          (module foo
             (export
                ;; export the `bar' mutable variable
                bar
                ;; export the `hux' function. this
                ;; function takes exactly two arguments
                (hux x y)
                ;; export the inline function `gee'
                ;; that takes at least one argument.
                (inline gee x . z)))


 - bigloo module clause: static static ...
     A `static' clause has exactly the same syntax as an export clause.
     However, bindings declared static are local to the module. Since
     the default scope of all bindings is static, `static' module
     clauses are useful only for program documentation.


 - bigloo module clause: from from ...
     `from' clauses have the syntax as `import' clauses and allow the
     re-exportation of imported bindings. That is, any module can
     export any bindings imported via a FROM clause.

     As an example, suppose we have module `bar':

          (module bar
             (export (fun)))
          
          (define (fun) "bar")

     Now, suppose we have a module `foo' that imports `bar', by the
     means of a `from' clause. Module `foo' is able to re-export the
     `bar' binding of module `bar':

          (module foo
             (from (fun bar "bar.scm")))

     A third module, let's name it `gee', importing module `foo', can
     see the binding for function `bar':

          (module gee
             (import (foo "foo.scm")))
          
          (print (fun))

     This feature is very useful when compiling modules exporting
     functions with type annotations. In particular, one may write:

          (module foo
            (export (class c1 x)))

     Then,
          (module bar
            (import foo)
            (from foo)
            (export (fun::c1)))
          
          (define (fun)
             (instantiate::c1 (x 10)))

     And,

          (module gee
             (import bar)
             (main main))
          
          (define (main x)
             (let ((o (fun)))
                (print o)
                (print (c1? o))))


 - bigloo module clause: load load ...
     A LOAD is a list of the form:

          <load>    ==> <lclause> ...
          <lclause> ==> (<module-name> <file-name>)
                      | <module-name>

     This clause forces Bigloo to load the module specified in the
     LCLAUSE in the environment used by the macro expansion mechanism.
     This means that the user's macros can use all the bindings of all
     the `load'ed modules but the `load'ed bindings remains unknown to
     the compiler.

     If the module `foo' is defined by:

          (module foo
             (export (foo x)))
          
          (define (foo x)
             `(cons ,x ,x))

     then,

          (module gee
             (load (foo "foo.scm")))
          
          (define-macro (gee x)
             `(cons ,(-fx x 1) ,(foo x)))
          
          (gee 5)   ==> (cons 4 (cons 5 5))
                    => (4 5 . 5)

 - bigloo module clause: eval eval...
     This form allows interactions between compiled code and interpreted
     code. (See the Section *Note Eval command line options: Eval for a
     presentation of compilation flags that enable compilation tuning
     for `eval'.)  Each EVAL has the following syntax:

          <eval> ==> (export-all)
                   | (export-module)
                   | (export-exports)
                   | (export <bind-name>)
                   | (export (@ <bind-name> <module-name>))
                   | (import <bind-name>)

     The first clause, `(export-all)', exports all the variables bound
     in the module (i.e., the variables defined in the module and the
     imported variables).  The second clause, `(export-module)', exports
     all the module's variables (those declared static and exported) to
     the interpreter; the third exports all the exports (i.e. the ones
     present inside an `export' clause) variables to the interpreter;
     the fourth and fifth clause each export one variable to the
     interpreter. The last clause imports a variable from the
     interpreter and all such imported variables are immutable (i.e.
     they cannot be the first argument of a `set!'  expression with the
     compiled code). Variables that are exported to the evaluators
     _must_ be exported.  If a variable is exported to the evaluators
     but not exported within an `export' clause, the compiler will
     produce an error message.

          (module foo
             (export (fib x))
             (eval (export fib)
                   (import bar)))
          
          (define (fib x) ...)
          (print bar)

 - bigloo module clause: extern extern ...
     Extern (aka foreign) clauses will be explained in the foreign
     interface (*note C Interface::).

 - bigloo module clause: java java ...
     Java clauses will be explained in the Java interface (*note Java
     Interface::).

 - bigloo module clause: option option ...
     This clause enables variables which affect compilation to be set
     from inside a module and since the expressions, OPTION ..., are
     evaluated _when compiling_, no code is compiled for them.  They
     are allowed to make side effects and to change the values of the
     global variables which describe how the compiler must compile.
     Usually they allow the control variables, which are described when
     Bigloo is invoked with the `-help2' option, to be set as in the
     following example:

          (module examplar
             (option (set! *debug* 3)
                     (set! *verbose* 2)))
          
          (print 'dummy)

     Whatever arguments are passed on the command line, Bigloo will
     compile this module in both verbose mode and debug mode.

 - bigloo module clause: library library ...
     This clause enables libraries (*note Bigloo Libraries::) when
     compiling and linking Bigloo modules. The expressions LIBRARY ...
     are symbols naming the libraries to be used.

     Here is an example of a module declaration which makes use of a
     library named `format':

          (module test
             (library format)
             (main    test-format)
             (import  (test2 "test2.scm")))


 - bigloo module clause: type type ...
     This forms is used to define builtin Bigloo types. It is not
     recommended to use it in user programs. So, it is left
     undocumented.


File: bigloo.info,  Node: Module Initialization,  Next: Qualified Notation,  Prev: Module Declaration,  Up: Modules

Module initialization
=====================

  _Initializing_ a module means evaluating, at runtime, its top level
forms (global bindings are top level forms).

  When a module, MODULE1, imports a module, MODULE2, MODULE2 is
initialized before MODULE1. Modules are initialized only once, nothing
being done if a module already met during initialization is met again.
Library modules are initialized before user modules and imported
modules are initialized in the same order as they appear in import
clauses.

  Here is a first example with two modules. First the module `foo':

     ;; module foo
     (module foo
        (main main)
        (import (bar "bar.scm")))
     
     (define (main argv)
        (print "argv: " argv))
     (print "foo")

  Then the module `bar'
     ;; module bar
     (module bar)
     
     (print "bar")

  These can be compiled into the executable A.OUT with:
     $ bigloo -c foo.scm
     $ bigloo -c bar.scm
     $ bigloo foo.o bar.o

  Execution of A.OUT produces:
     $ a.out
        -| bar
           foo
           argv: (a.out)

  The explanation is:
   * module `foo' contains the program entry point so this is where
     initialization begins.

   * because `foo' imports module `bar', `bar' must be  initialized
     _before_ `foo'. This explains why the word `bar'  is printed
     before anything else.

   * module initialization for `foo' is completed before `main'  is
     called. This explains why word `foo' is printed before `main'  is
     entered.

  Let's consider another example with 3 modules:
     ;; `module1'
     (module module1
        (main main)
        (import (module2 "module2.scm")))
     
     (define (main argv)
        (print "argv: " argv))
     
     (print "module1")

  The second module:
     ;; `module2'
     (module module2
        (import (module3 "module3.scm")))
     
     (print "module2")

  The third module:
     ;; `module3'
     (module module3
        (import (module1 "module1.scm")))
     
     (print "module3")

  Compile with:
     $ bigloo module1.scm -c
     $ bigloo module2.scm -c
     $ bigloo module3.scm -c
     $ bigloo module1.o module2.o module3.o

  Execution produces:

     $ a.out
        -| module3
           module2
           module1
           argv: (a.out)

  The order of module initialization can be explicitly specified using
`with' and `use' clauses.


File: bigloo.info,  Node: Qualified Notation,  Next: Inline Procedures,  Prev: Module Initialization,  Up: Modules

Qualified notation
==================

  Global variables can be referenced using implicit notation or using
_qualified_ notation. Implicit notation is used when variables are
referenced just by their name whereas qualified notation is used when
variables are referenced by their name and the name of the module which
defines them. Qualified notation has the following syntax:

     (@ <bind-name> <module-name>)

and is useful when several imported modules export a variable with the
same name. Using qualified notations instead of short notation only
affects compile.

  When several variables are defined under the same identifier, the
compiler uses the two following rules in order to decide which variable
is selected by an implicit reference: 1) the variable defined in a
module has a higher precedence than all imported variables, 2) imported
variables have a higher precedence than library variables.


File: bigloo.info,  Node: Inline Procedures,  Next: Module Access File,  Prev: Qualified Notation,  Up: Modules

Inline procedures
=================

  Bigloo allows procedures called _inline_ and which differ from normal
ones only in the type of code planted.  An inline procedure is a first
class object which can be manipulated in the same way as any other
procedure but when Bigloo sees a reference to one, rather than
generating a C function call to the function, the body of the inline
procedure is open-coded.  The definition of an inline is given in the
following way:

 - bigloo syntax: define-inline (name args ...) body
 - bigloo syntax: define-inline (name args ... . arg) body
     Apart from the initial word, this form has the same syntax as that
     used by `define' for procedures. Inline procedures are exportable
     which means that the compiler scans imported files to find the
     bodies of all inline procedures. Here is a small example of a
     module which exports an inline and a module which imports it.

          ;; the exporter module
          (module exporter
                  (export (inline make-list . objs)))
          
          (define-inline (make-list . objs) objs)

          ;; the importer module
          (module importer
                  (import exporter))
          
          (print (make-list 1 2 3 4 5))

     Because of the open-coding of the exporter procedure, the above
     print statement is equivalent to:

          (print (let ((objs (list 1 2 3 4 5)))
                    objs))

     Any procedure can be an inline. Also any exported procedure can be
     an inline provided all global variables and functions it uses are
     also exported.

     Note: Bigloo can decide to inline procedures declared with `define'
     but this can be achieved only with local procedures whereas
     procedures declared with the `define-inline' form are open-coded
     even through module importation.

     Note: Procedures declared _inline_ are macro expanded with the
     macro defined in the module where they are invoked. That is, if
     module `module1' declares an inline procedure `p' and module
     `module2' imports it, `p' may have two different macro-expansions:
     one for `module1' and one for `module2'.


File: bigloo.info,  Node: Module Access File,  Next: Reading Path,  Prev: Inline Procedures,  Up: Modules

Module access file
==================

  Bigloo is different from languages such as C where a module is
defined by a file. For Bigloo, the module name is not necessarily the
name of the file where the text of the module is written and modules
can even be split across several files.

  Since modules are defined independently of files, it is necessary to
make a link between a module and its files and there are two ways of
doing this.  Choosing an import clause where the file-names are
specified or creating a "module access file". Such a file must contain
only one LIST, each element of the list being of the form:

  (module-name "file-name" ... "file-name")

Use the `-afile <file>' option to specify the "module access file" when
compiling. By default Bigloo checks if a file named `.afile' exists. If
it exists it is loaded as a module access file.

  *Note The Bigloo command line: Compiler Description.

  Note: The Bigloo distribution contains a tool, `afile', that can
automatically build a "module access file". See the manpage for `afile'
for details.


File: bigloo.info,  Node: Reading Path,  Prev: Module Access File,  Up: Modules

Reading path
============

  Imported, included or loaded files are sought first in the current
directory and then in the directories, sequentially from start to end,
of the list in the `*load-path*' variable. This variable, initially set
to the empty list, can be reset by the `-I' option of the compiler.


File: bigloo.info,  Node: Core Language,  Next: Standard Library,  Prev: Modules,  Up: Top

Core Language
*************

  This chapter presents the Bigloo basics. It presents the elements
that compose the body of a module (see *Note Modules::).

* Menu:

* Syntax::                      Identifiers and typed identifiers
* Comments::                    Bigloo comments
* Expressions::                 Expressions
* Definitions::                 Global definitions


File: bigloo.info,  Node: Syntax,  Next: Comments,  Prev: Core Language,  Up: Core Language

Syntax
======

  The syntax of Bigloo is that of Scheme (a parenthesis based one) with
two exceptions: type information and multi-line comments. Type
information is supplied when identifiers are introduced (via `lambda',
`let', `define', ...) and those identifiers holding type information are
referred to as typed identifiers.

  They are defined by the following grammar:

     <ident>        ==> <r5rs-ident> | <typed-ident>
     <typed-ident>  ==> <r5rs-ident>::<r5rs-ident>
     <r5rs-ident>   ==> the standard Scheme identifiers

  For details of the standard Scheme identifiers, see *Note token:
(r5rs.info)Lexical structure.

  Multi-lines comments (see <http://srfi.schemers.org/srfi-30/>) are
defined as:

     <ident>        ==> <r5rs-ident> | <typed-ident>
     <comment>      ==> ;<all subsequent characters up to a line break>
            	       | #| <comment-text> (<comment> <comment-text>)* |#
     <comment-text> ==> <character sequence not containing #| or |#>


File: bigloo.info,  Node: Comments,  Next: Expressions,  Prev: Syntax,  Up: Core Language

Comments
--------

  Comments and whitespaces are the same as in *Note r5rs.info:
(R5RS)Whitespace and comments.

     ;;; The FACT procedure computes the factorial
     ;;; of a non-negative integer.
     (define fact
       (lambda (n)
         (if (= n 0)
             1        ;; Base case: return 1
             (* n (fact (- n 1))))))


File: bigloo.info,  Node: Expressions,  Next: Definitions,  Prev: Comments,  Up: Core Language

Expressions
-----------

  Bigloo expressions are the same as in *Note r5rs.info:
(R5RS)Expressions.  Bigloo has more syntactic keywords than Scheme. The
Bigloo syntactic keywords are:

     =>                      do                    or
     and                     else                  quasiquote
     begin                   if                    quote
     case                    lambda                set!
     cond                    let                   unquote
     unquote-splicing        define                let*
     delay                   letrec                module
     labels                  try                   define-struct
     unwind-protect          bind-exit             define-inline
     regular-grammar         lalr-grammar          regular-search
     define-expander         define-macro          match-case
     match-lambda            pragma                failure
     assert                  define-generic        define-method
     instantiate             duplicate             with-access
     widen!                  shrink!               multiple-value-bind
     let-syntax              letrec-syntax         define-syntax
     cond-expand             receive               args-parse
     define-record-type      and-let*

All other non atomic Bigloo forms are evaluated as function calls or
macro class.

 - syntax: <variable>
 - syntax: quote datum
 - syntax: `''datum
 - syntax: <constant>
          (define x 28)                          =>
          x                                      => 28
          (quote a)                              => A
          (quote #(a b c))                       => #(A B C)
          (quote (+ 1 2))                        => (+ 1 2)
          'a                                     => A
          '#(a b c)                              => #(A B C)
          '()                                    => ()
          '(+ 1 2)                               => (+ 1 2)
          '(quote a)                             => (QUOTE A)
          '"abc"                                 => "abc"
          "abc"                                  => "abc"
          '145932                                => 145932
          145932                                 => 145932
          '#t                                    => #t
          #t                                     => #t

 - syntax: operator operand ...
          (+ 3 4)                                => 7
          ((if #f + *) 3 4)                      => 12
          ((lambda (x) (+ 1 x)) 5)               => 6

 - syntax: lambda formals body
          (lambda (x) (+ x x))                   => _a procedure_
          ((lambda (x) (+ x x)) 4)               => 8
          
          (define reverse-subtract
            (lambda (x y) (- y x)))
          (reverse-subtract 7 10)                => 3
          
          (define add4
            (let ((x 4))
              (lambda (y) (+ x y))))
          (add4 6)                               => 10
          
          ((lambda x x) 3 4 5 6)                 => (3 4 5 6)
          ((lambda (x y . z) z)
           3 4 5 6)                              => (5 6)

 - syntax: if test consequent [alternate]
          (if (> 3 2) 'yes 'no)                  => yes
          (if (> 2 3) 'yes 'no)                  => no
          (if (> 3 2)
              (- 3 2)
              (+ 3 2))                           => 1

 - syntax: set! variable expression
          (define x 2)
          (+ x 1)                                => 3
          (set! x 4)                             => _unspecified_
          (+ x 1)                                => 5

 - library syntax: cond clause clause ...
          (cond ((> 3 2) 'greater)
                ((< 3 2) 'less))                 => greater
          
          (cond ((> 3 3) 'greater)
                ((< 3 3) 'less)
                (else 'equal))                   => equal
          
          (cond ((assv 'b '((a 1) (b 2))) => cadr)
                (else #f))                       => 2

 - library syntax: case key clause clause ...
          (case (* 2 3)
            ((2 3 5 7) 'prime)
            ((1 4 6 8 9) 'composite))            => composite
          (case (car '(c d))
            ((a) 'a)
            ((b) 'b))                            => _unspecified_
          (case (car '(c d))
            ((a e i o u) 'vowel)
            ((w y) 'semivowel)
            (else 'consonant))                   => consonant

 - library syntax: and test ...
          (and (= 2 2) (> 2 1))                  => #t
          (and (= 2 2) (< 2 1))                  => #f
          (and 1 2 'c '(f g))                    => (f g)
          (and)                                  => #t

 - bigloo syntax: and-let* test ...
     In case of an ordinary `and' formed of proper boolean expressions:
     `(and e1 e2 ...)'  expression E2, if it gets to be evaluated,
     knows that E1 has returned non-`#f'. Moreover, E2 knows exactly
     what the result of E1 was - `#t' - which E2 can use to its
     advantage. If E1 however is an extended boolean expression, E2 can
     no longer tell which particular non-`#f' value E1 has returned.
     Chances are it took a lot of work to evaluate E1, and the produced
     result (a number, a vector, a string, etc) may be of value to E2.
     Alas, the `and' form merely checks that the result is not an `#f',
     and throws it away. If E2 needs it, it has to compute that value
     anew. This proposed `and-let*' special form lets constituent
     expressions get hold of the results of already evaluated
     expressions, without re-doing their work.

     `and-let*' can be thought of as a combination of `let*' and `and',
     or a generalization of `cond''s send operator `=>'. An `and-let*'
     form can also be considered a sequence of guarded expressions. In
     a regular program, forms may produce results, bind them to
     variables and let other forms use these results. `and-let*'
     differs in that it checks to make sure that every produced result
     "makes sense" (that is, not an `#f'). The first "failure" triggers
     the guard and aborts the rest of the sequence (which presumably
     would not make any sense to execute anyway).

          (and-let* ((x 1) (y 2)) (cons x y))    => (1 . 2)
          (and-let* ((x 1) (z #f)) x)            => #f
          
          (and-let* ((my-list (compute-list)) ((not (null? my-list))))
                    (do-something my-list))
          
          (define (look-up key alist)
            (and-let* ((x (assq key alist))) (cdr x)))
          
          (or (and-let* ((c (read-char))
                         ((not (eof-object? c))))
                        (string-set! some-str i c)
                        (set! i (+ 1 i)))


     Note: This documentation has been written by Oleg Kiselyov under
     the following copyright:

          Copyright (C) Oleg Kiselyov (1998). All Rights Reserved.
          
          This document and translations of it may be copied and furnished to
          others, and derivative works that comment on or otherwise explain it
          or assist in its implementation may be prepared, copied, published and
          distributed, in whole or in part, without restriction of any kind,
          provided that the above copyright notice and this paragraph are
          included on all such copies and derivative works. However, this
          document itself may not be modified in any way, such as by removing
          the copyright notice or references to the Scheme Request For
          Implementation process or editors, except as needed for the purpose of
          developing SRFIs in which case the procedures for copyrights defined
          in the SRFI process must be followed, or as required to translate it
          into languages other than English.
          
          The limited permissions granted above are perpetual and will not be
          revoked by the authors or their successors or assigns.
          
          This document and the information contained herein is provided on an
          "AS IS" basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL
          WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
          WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
          RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
          PARTICULAR PURPOSE.


 - library syntax: or test ...
          (or (= 2 2) (> 2 1))                   => #t
          (or (= 2 2) (< 2 1))                   => #t
          (or #f #f #f)                          => #f
          (or (memq 'b '(a b c))
              (/ 3 0))                           => (b c)

 - library syntax: let [name] (binding ...) body
          (let ((x 2) (y 3))
            (* x y))                             => 6
          
          (let ((x 2) (y 3))
            (let ((x 7)
                  (z (+ x y)))
              (* z x)))                          => 35
          
          (let loop ((l '(1 2 3)))
             (if (null? l)
                 '()
                 (cons (+ 1 (car l))
                       (loop (cdr l)))))         => (2 3 4)

 - library syntax: let* (binding ...) body
          (let ((x 2) (y 3))
            (let* ((x 7)
                   (z (+ x y)))
              (* z x)))                          => 70

 - library syntax: letrec (binding ...) body
          (letrec ((even?
                    (lambda (n)
                      (if (zero? n)
                          #t
                          (odd? (- n 1)))))
                   (odd?
                    (lambda (n)
                      (if (zero? n)
                          #f
                          (even? (- n 1))))))
            (even? 88))
                                                 => #t

 - bigloo syntax: labels ((name (arg ...) body) ...) body
     The syntax is similar to the Common Lisp one [Steele90], where
     created bindings are immutable.

          (labels ((loop (f l acc)
                         (if (null? l)
                             (reverse! acc)
                             (loop f (cdr l) (cons (f (car l)) acc)))))
             (loop (lambda (x) (+ 1 x)) (list 1 2 3) '()))
             => (2 3 4)

 - library syntax: begin expression expression ...
          (define x 0)
          
          (begin (set! x 5)
                 (+ x 1))                        => 6
          
          (begin (display "4 plus 1 equals ")
                 (display (+ 4 1)))              => _unspecified_
                                                 -| 4 plus 1 equals 5

 - library syntax: do ((variable init step) ...) (test expression ...)
          body
          (do ((vec (make-vector 5))
               (i 0 (+ i 1)))
              ((= i 5) vec)
            (vector-set! vec i i))               => #(0 1 2 3 4)
          
          (let ((x '(1 3 5 7 9)))
            (do ((x x (cdr x))
                 (sum 0 (+ sum (car x))))
                ((null? x) sum)))                => 25

 - library syntax: delay expression

 - syntax: quasiquote template
 - syntax: ` template
          `(list ,(+ 1 2) 4)                     => (list 3 4)
          (let ((name 'a)) `(list ,name ',name))
                    => (list a (quote a))
          `(a ,(+ 1 2) ,@(map abs '(4 -5 6)) b)
                    => (a 3 4 5 6 b)
          `((`foo' ,(- 10 3)) ,@(cdr '(c)) . ,(car '(cons)))
                    => ((foo 7) . cons)
          `#(10 5 ,(sqrt 4) ,@(map sqrt '(16 9)) 8)
                    => #(10 5 2 4 3 8)
          `(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)
                    => (a `(b ,(+ 1 2) ,(foo 4 d) e) f)
          (let ((name1 'x)
                (name2 'y))
            `(a `(b ,,name1 ,',name2 d) e))
                    => (a `(b ,x ,'y d) e)
          (quasiquote (list (unquote (+ 1 2)) 4))
                    => (list 3 4)
          '(quasiquote (list (unquote (+ 1 2)) 4))
                    => `(list ,(+ 1 2) 4)
               __i.e., (quasiquote (list (unquote (+ 1 2)) 4))


File: bigloo.info,  Node: Definitions,  Prev: Expressions,  Up: Core Language

Definitions
-----------

  Global bindings are introduced by the `define' form:

 - syntax: define variable expression
 - syntax: define (variable arg ...) body
          (define add3
            (lambda (x) (+ x 3)))
          (add3 3)                               => 6
          (define first car)
          (first '(1 2))                         => 1

  *Note r5rs.info: Definitions, for more details. The Bigloo module
language (See *Note Module Declaration::) enables _exports_ and
_imports_ of global definitions.


File: bigloo.info,  Node: Standard Library,  Next: Pattern Matching,  Prev: Core Language,  Up: Top

Standard Library
****************

  This chapter presents the Bigloo standard library. Bigloo is mostly
R5RS compliant but it proposes many extensions to this standard and it
proposes many extensions. In a first section (*Note Scheme Library::)
the Bigloo R5RS support is presented. This section also contains various
function that are not standard (for instance, various functions used to
manage a file system). Then, in the following sections (*Note
Structures and Records::, *Note Serialization::, *Note Bit
Manipulation::, *Note System Programming:: and *Note Posix Regular
Expressions:: Bigloo specific extensions are presented. Bigloo input
and output facilities constitue a large superset of the standard Scheme
definition. For this reason they are presented in a separate section
(*Note Input and Output::).

* Menu:

* Scheme Library::
* Input and Output::
* Structures and Records::
* Serialization::
* Bit Manipulation::
* Hash Tables::
* System Programming::
* Date::
* Posix Regular Expressions::


File: bigloo.info,  Node: Scheme Library,  Next: Input and Output,  Up: Standard Library

Scheme Library
==============

  When the definition of a procedure or a special form is the same in
Bigloo and Scheme, we just mention its name; otherwise, we explain it
and qualify it as a "bigloo procedure".

* Menu:

* Booleans::
* Equivalence Predicates::
* Pairs And Lists::
* Symbols::
* Keywords::
* Numbers::
* Characters::
* UCS-2 Characters::
* Strings::
* Unicode (UCS-2) Strings::
* Vectors::
* Control Features::


File: bigloo.info,  Node: Booleans,  Next: Equivalence Predicates,  Up: Scheme Library

Booleans
--------

  The standard boolean objects are `#t' and `#f'.  Note: the empty list
is true.

 - library procedure: not obj
     `not' returns #t if OBJ is false, and returns `#f' otherwise.

          (not #t)                               => #f
          (not 3)                                => #f
          (not (list 3))                         => #f
          (not #f)                               => #t
          (not '())                              => #f
          (not (list))                           => #f
          (not 'nil)                             => #f

 - library procedure: boolean? obj
     `Boolean?' returns #t if OBJ is either #t or #f and returns #f
     otherwise.

          (boolean? #f)                          => #t
          (boolean? 0)                           => #f
          (boolean? '())                         => #f

