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: Input and Output,  Next: Structures and Records,  Prev: Scheme Library,  Up: Standard Library

Input and output
================

  This section describes Scheme operation for reading and writing data.
The section *Note Files:: describes functions for handling files.

 - library procedure: call-with-input-file string proc
 - library procedure: call-with-output-file string proc
     These two procedures call PROC with one argument, a port obtained
     by opening STRING.  See *Note r5rs.info: (R5RS)Ports, for more
     details.

          (call-with-input-file "/etc/passwd"
             (lambda (port)
                (let loop ((line (read-line port)))
                   (if (not (eof-object? line))
                       (begin
                          (print line)
                          (loop (read-line port)))))))

 - procedure: input-port? obj
 - procedure: input-string-port? obj
 - procedure: output-port? obj
 - procedure: output-string-port? obj
 - procedure: port? obj

 - bigloo procedure: input-port-name obj
     Returns the file name for which OBJ has been opened.

 - bigloo procedure: input-port-reopen! obj
     Re-open the input port OBJ. That is, re-start reading from the
     first character of the input port.

 - procedure: current-input-port
 - procedure: current-output-port
 - bigloo procedure: current-error-port

 - optional procedure: with-input-from-file string thunk
 - optional procedure: with-input-from-string string thunk
 - optional procedure: with-input-from-procedure procedure thunk
 - optional procedure: with-output-to-file string thunk
 - bigloo procedure: with-error-to-file string thunk
 - bigloo procedure: with-output-to-string thunk
 - bigloo procedure: with-error-to-string thunk
     A port is opened from file STRING. This port is made the current
     input port (resp. the current output port or the current error
     port) and THUNK is called.  See *Note r5rs.info: (R5RS)Ports, for
     more details.

          (with-input-from-file "/etc/passwd"
             (lambda ()
                (let loop ((line (read-line (current-input-port))))
                   (if (not (eof-object? line))
                       (begin
                          (print line)
                          (loop (read-line (current-input-port))))))))

 - bigloo procedure: with-input-from-port port thunk
 - bigloo procedure: with-output-to-port port thunk
 - bigloo procedure: with-error-to-port port thunk
     `with-input-from-port', `with-output-to-port' and
     `with-error-to-port' all suppose PORT to be a legal port. They
     call THUNK making PORT the current input (resp. output or error)
     port. None of these functions close PORT on the continuation of
     THUNK.

          (with-output-to-port (current-error-port)
             (lambda () (display "hello")))

 - procedure: open-input-file file-name
     If FILE-NAME is a regular file name, `open-input-file' behaves as
     the function defined in the Scheme report. If FILE-NAME starts with
     special prefixes it behaves differently. Here are the recognized
     prefixes:

        * `| ' (a string made of the characters `#\|' and `#\space')
          Instead of opening a regular file, Bigloo opens an input pipe.
          The same syntax is used for output file.

               (define pin (open-input-file "| cat /etc/passwd"))
               (define pout (open-output-file "| wc -l"))
               
               (display (read pin) pout)
               (close-input-port pin)
               (newline pout)
               (close-output-port pout)

        * `pipe:' Same as `| '.

        * `file:' Opens a regular file.

        * `string:' Opens a port on a string. This is equivalent to
          `open-input-string'.  Example:

               (with-input-from-file "string:foo bar Gee"
                  (lambda ()
                     (print (read))
                     (print (read))
                     (print (read))))
                  -| foo
                  -| bar
                  -| Gee

        * `http:server/path'

          Opens an _http_ connection on `server' and open an input file
          on file `path'.

        * `http:server:port-number/path'

          Opens an _http_ connection on `server', on port number `port'
          and open an input file on file `path'.

        * `ftp:server/path'

          Opens an _http_ connection on `server' and open an input file
          on file `path'.


 - bigloo procedure: open-input-string string
     Returns an `input-port' able to deliver characters from STRING.

 - bigloo procedure: open-input-c-string string
     Returns an `input-port' able to deliver characters from C string
     STRING. The buffer used by the input port is the exact same string
     as the argument. That is, no buffer is allocated.

 - bigloo procedure: open-input-procedure procedure
     Returns an `input-port' able to deliver characters from PROCEDURE.
     Each time a character has to be read, the PROCEDURE is called.
     This procedure may returns a character, a string of characters, or
     the boolean `#f'. This last value stands for the end of file.

     Example:

          (let ((p (open-input-procedure (let ((s #t))
          				  (lambda ()
          				     (if s
          					 (begin (set! s #f) "foobar")
          					 s))))))
             (read))

 - procedure: open-output-file file-name
     The same syntax as `open-input-file' for file names applies here.
     When a file name starts with `| ', Bigloo opens an output pipe
     instead of a regular file.

 - bigloo procedure: append-output-file file-name
     If `file-name' exists, this function returns an `output-port' on
     it, without removing it. New output will be appended to FILE-NAME.
     If `file-name' does not exist, it is created.

 - bigloo procedure: open-output-string
     This function returns an _output string port_. This object has
     almost the same purpose as `output-port'. It can be used with all
     the printer functions which accept `output-port'. An output on a
     _output string port_ memorizes all the characters written. An
     invocation of `flush-output-port' or `close-output-port' on an
     _output string port_ returns a new string which contains all the
     characters accumulated in the port.

 - bigloo procedure: get-output-string output-port
     Given an output port created by `open-output-string', returns a
     string consisting of the characters that have been output to the
     port so far.

 - procedure: close-input-port input-port
 - procedure: close-output-port output-port
     According to R5RS, the value returned is unspecified. However, if
     _output-port_ was created using `open-output-string', the value
     returned is the string consisting of all characters sent to the
     port.

 - bigloo procedure: input-port-name input-port
     Returns the name of the file used to open the INPUT-PORT.

 - bigloo procedure: input-port-position port
 - bigloo procedure: output-port-position port
     Returns the current position (a character number), in the PORT.

 - bigloo procedure: set-input-port-position! port pos
 - bigloo procedure: set-output-port-position! port pos
     These functions set the file position indicator for PORT. The new
     position, measured in bytes, is specified by POS. It is an error
     to seek a port that cannot be changed (for instance, a string or a
     console port). The result of these functions is unspecified. An
     error is raised if the position cannot be changed.

 - bigloo procedure: input-port-reopen! input-port
     This function re-opens the input `input-port'. That is, it reset
     the position in the INPUT-PORT to the first character.

 - procedure: read [input-port]
 - bigloo procedure: read/case case [input-port]
 - bigloo procedure: read-case-sensitive [input-port]
 - bigloo procedure: read-case-insensitive [input-port]
     Read a lisp expression. The case sensitivity of `read' is
     unspecified.  If have to to enforce a special behavior regarding
     the case, use `read/case', `read-case-sensitive' or
     `read-case-insensitive'.  Let us consider the following source
     code: The value of the `read/case''s CASE argument may either be
     `upcase', `downcase' or `sensitive'. Using any other value is an
     error.

          (define (main argv)
             (let loop ((exp (read-case-sensitive)))
                (if (not (eof-object? exp))
                    (begin
                       (display "exp: ")
                       (write exp)
                       (display " [")
                       (display exp)
                       (display "]")
                       (print " eq?: " (eq? exp 'FOO) " " (eq? exp 'foo))
                       (loop (read-case-sensitive))))))

     Thus:
          > a.out
          foo
            -| exp: foo [foo] eq?: #f #t
          FOO
            -| exp: FOO [FOO] eq?: #t #f

 - bigloo procedure: read/rp grammar port
 - bigloo procedure: read/lalrp lalrg rg port [emptyp]
     These functions are fully explained in *Note Regular Parsing::,
     and *Note Lalr Parsing::.

 - procedure: read-char [port]
 - procedure: peek-char [port]
 - procedure: eof-object? obj

 - procedure: char-ready? [port]
     As specified in the R5Rs, *Note r5rs.info: (R5RS)Ports,
     `char-ready?' returns #t if a character is ready on the input PORT
     and returns #f otherwise.  If `char-ready' returns #t then the
     next `read-char' operation on the given PORT is guaranteed not to
     hang.  If the PORT is at end of file then `char-ready?' returns
     #t.  PORT may be omitted, in which case it defaults to the value
     returned by `current-input-port'.

     When using `char-ready?' consider the latency that may exists
     before characters are available. For instance, executing the
     following source code:

          (let* ((proc (run-process "/bin/ls" "-l" "/bin" output: pipe:))
                 (port (process-output-port proc)))
             (let loop ((line (read-line port)))
                (print "char ready " (char-ready? port))
                (if (eof-object? line)
                    (close-input-port port)
                    (begin
                       (print line)
                       (loop (read-line port))))))

     Produces outputs such as:

          char ready #f
          total 7168
          char ready #f
          -rwxr-xr-x    1 root     root         2896 Sep  6  2001 arch
          char ready #f
          -rwxr-xr-x    1 root     root        66428 Aug 25  2001 ash
          char ready #t
          ...

     For a discussion of Bigloo processes, see *Note Process::.

     _Note:_ Thanks to Todd Dukes for the example and the suggestion of
     including it this documentation.

 - bigloo procedure: read-line [input-port]
     Reads characters from INPUT-PORT until a `#\Newline', a `#\Return'
     or an `end of file' condition is encountered.  `read-line' returns
     a newly allocated string composed of the characters read.

 - bigloo procedure: read-lines [input-port]
     Accumulates all the line of an INPUT-PORT into a list.

 - bigloo procedure: read-of-strings [input-port]
     Reads a sequence of non-space characters on INPUT-PORT, makes a
     string of them and returns the string.

 - bigloo procedure: read-string [input-port]
     Reads all the characters of INPUT-PORT into a string.

 - bigloo procedure: read-chars size [input-port]
     Returns a newly allocated strings made of SIZE characters read
     from INPUT-PORT (or from `(current-input-port)' if INPUT-PORT is
     not provided). If less than SIZE characters are available on the
     input port, the returned string is smaller than SIZE. Its size is
     the number of available characters.

 - bigloo procedure: send-chars input-port output-port [len]
     Transfer the characters from INPUT-PORT to OUTPUT-PORT. This
     procedure is sometimes mapped to a system call (such as `sendfile'
     under Linux) and might thus be more efficient than copying the
     ports by hand.

 - bigloo procedure: read-fill-string! s o len [input-port]
     Fills the string S starting at offset O with at most LEN
     characters read from the input port INPUT-PORT (or from
     `(current-input-port)' if INPUT-PORT is not provided).  This
     function returns the number of fill characters (which may be
     smaller than LEN if less characters are available).

     Example:
          (let ((s (make-string 10 #\-)))
             (with-input-from-string "abcdefghijlkmnops"
                (lambda ()
                   (read-fill-string! s 3 5)
                   s)))
             => ---abcde--

 - library procedure: write obj [output-port]
 - library procedure: display obj [output-port]
 - bigloo procedure: print obj ...
     This procedure allows several objects to be displayed. When all
     these objects have been printed, `print' adds a newline.

 - bigloo procedure: display* obj ...
     This function is similar to `print' but does not add a newline.

 - bigloo procedure: fprint output-port obj ...
     This function is the same as `print' except that a port is
     provided.

 - procedure: newline [output-port]
 - procedure: write-char char [output-port]
 - bigloo procedure: flush-output-port output-port
     This procedure flushes the output port OUTPUT-PORT.

 - bigloo procedure: format format-string [objs]
     _Note_: Many thanks to Scott G. Miller who is the author of
     SRFI-28. Most of the documentation of this function is copied from
     the SRFI documentation.

     Accepts a message template (a Scheme String), and processes it,
     replacing any escape sequences in order with one or more
     characters, the characters themselves dependent on the semantics
     of the escape sequence encountered.

     An escape sequence is a two character sequence in the string where
     the first character is a tilde `~'. Each escape code's meaning is
     as follows:

        * `~a' The corresponding value is inserted into the string as
          if printed with display.

        * `~s' The corresponding value is inserted into the string as
          if printed with write.

        * `~%' A newline is inserted.

        * `~~' A tilde `~' is inserted.

     `~a' and `~s', when encountered, require a corresponding Scheme
     value to be present after the format string. The values provided
     as operands are used by the escape sequences in order. It is an
     error if fewer values are provided than escape sequences that
     require them.

     `~%' and `~~' require no corresponding value.

          (format "Hello, ~a" "World!")
             -| Hello, World!
          (format "Error, list is too short: ~s~%" '(one "two" 3))
             -| Error, list is too short: (one "two" 3)

 - bigloo procedure: printf format-string [objs]
 - bigloo procedure: fprintf port format-string [objs]
     Formats OBJS to the current output port or to the specified PORT.

 - bigloo procedure: set-write-length! len
     Sets to LEN the maximum number of atoms that can be printed by
     `write' and `display'. This facility is useful in preventing the
     printer from falling into an infinite loop when printing circular
     structures.

 - bigloo procedure: get-write-length
     Gets the current length of the printer. That is, `get-write-length'
     returns the maximum number of Bigloo objects that are allowed to
     be printed when printing compound objects. This function is useful
     in preventing the system from looping when printing circular data
     structures.

 - bigloo procedure: set-printer! proc
     Set the current printer to be PROC; PROC has to be a procedure
     expecting at least one argument: an expression to print; an output
     port is an optional, second argument.

 - bigloo procedure: native-printer
     Returns the native Bigloo's printer.

 - bigloo procedure: current-printer
     Returns the current Bigloo's printer.

 - bigloo procedure: pp obj [output-port]
     Pretty print OBJ on OUTPUT-PORT.

 - bigloo variable: *pp-case*
     Sets the variable to `respect', `lower' or `upper' to change the
     case for pretty-printing.

 - bigloo variable: *pp-width*
     The width of the pretty-print.

 - bigloo procedure: write-circle obj [output-port]
     Display recursive object OBJ on OUTPUT-PORT. Each component of the
     object is displayed using the `write' library function.

 - bigloo procedure: display-circle obj [output-port]
     Display recursive object OBJ on OUTPUT-PORT. Each component of the
     object is displayed using the `display' library function.

     For instance:
          (define l (list 1 2 3))
          (set-car! (cdr l) l)
          (set-car! (cddr l) l)
          (display-circle l)  -| #0=(1 #0# #0#)


File: bigloo.info,  Node: Structures and Records,  Next: Serialization,  Prev: Input and Output,  Up: Standard Library

Structures and Records
======================

  Bigloo supports two kinds of enumerated types: the _structures_ and
the _records_. They offer similar facilities. Structures where
pre-exising to records and they are maintained mainly for backward
compatiblity. Recors are compliant with the Scheme request for
implementation 9.

* Menu:

* Structures::
* Records (SRFI-9)::


File: bigloo.info,  Node: Structures,  Next: Records (SRFI-9),  Up: Structures and Records

Structures
----------

  There is, in Bigloo, a new class of objects: structures, which are
equivalent to C `struct'.

 - bigloo syntax: define-struct name field...
     This form defines a structure with name NAME, which is a symbol,
     having fields FIELD... which are symbols or lists, each list being
     composed of a symbol and a default value. This form creates
     several functions: creator, predicate, accessor and assigner
     functions. The name of each function is built in the following way:
        * Creator: `make-NAME'

        * Predicate: `NAME?'

        * Accessor: `NAME-FIELD'

        * Assigner: `NAME-FIELD-set!'

     Function `make-NAME' accepts an optional argument. If provided,
     all the slots of the created structures are filled with it. The
     creator named `name' accepts as many arguments as the number of
     slots of the structure. This function allocates a structure and
     fills each of its slots with its corresponding argument.

     If a structure is created using `make-NAME' and no initialization
     value is provided, the slot default values (when provided) are used
     to initialize the new structure. For instance, the execution of
     the program:

          (define-struct pt1 a b)
          (define-struct pt2 (h 4) (g 6))
          
          (make-pt1)
             => #{PT1 () ()}
          (make-pt1 5)
             => #{PT1 5 5}
          (make-pt2)
             => #{PT2 4 6}
          (make-pt2 5)
             => #{PT2 5 5}

 - bigloo procedure: struct? obj
     Returns `#t' if and only if OBJ is a structure.


File: bigloo.info,  Node: Records (SRFI-9),  Prev: Structures,  Up: Structures and Records

Records (SRFI-9)
----------------

  Bigloo supports records has specified by SRFI-9. This section is a
copy of the SRFI-9 specification by Richard Kelsey. This SRFI describes
syntax for creating new data types, called record types.  A predicate,
constructor, and field accessors and modifiers are defined for each
record type.  Each new record type is distinct from all existing types,
including other record types and Scheme's predefined types.

 - syntax: define-record-type expression...
     The syntax of a record-type definition is:

          <record-type-definition> ==> (`define-record-type' <type-name>
                                                   (<constructor-name> <field-tag> ...)
                                                   <predicate-name>
                                                   <field-spec> ...)
          <field-spec>             ==> (<field-tag> <accessor-name>)
                                     | (<field-tag> <accessor-name> <modifier-name>)
          <field-tag>              ==> <identifier>
          <accessor-name>          ==> <identifier>
          <predicate-name>         ==> <identifier>
          <modifier-name>          ==> <identifier>
          <type-name>              ==> <identifier>

     `Define-record-type' is generative: each use creates a new record
     type that is distinct from all existing types, including other
     record types and Scheme's predefined types. Record-type
     definitions may only occur at top-level (there are two possible
     semantics for `internal' record-type definitions, generative and
     nongenerative, and no consensus as to which is better).

     an instance of `define-record-type' is equivalent to the following
     definitions:

        * `<type-name>' is bound to a representation of the record type
          itself. Operations on record types, such as defining print
          methods, reflection, etc. are left to other SRFIs.

        * `<constructor-name>' is bound to a procedure that takes as
          many arguments as the re are `<field-tag>'s in the
          `(<constructor-name> ...)' subform and returns a new
          `<type-name>' record. Fields whose tags are listed with
          `<constructor-name>' have the corresponding argument as their
          initial value. The initial values of all other fields are
          unspecified.

        * `<predicate-name>' is a predicate that returns `#t' when
          given a value returned by `<constructor-name>' and `#f' for
          everything else.

        * Each `<accessor-name>' is a procedure that takes a record of
          type `<type-name>' and returns the current value of the
          corresponding field. It is an error to pass an accessor a
          value which is not a record of the appropriate type.

        * Each `<modifier-name>' is a procedure that takes a record of
          type `<type-name>' and a value which becomes the new value of
          the corresponding field; an unspecified value is returned. It
          is an error to pass a modifier a first argument which is not
          a record of the appropriate type.

     Records are disjoint from the types listed in Section 4.2 of R5RS.

     Seting the value of any of these identifiers has no effect on the
     behavior of any of their original values.

     The following

          (define-record-type pare
              (kons x y)
              pare?
              (x kar set-kar!)
              (y kdr))

     defines `kons' to be a constructor, `kar' and `kdr' to be
     accessors, `set-kar!' to be a modifier, and `pare?' to be a
     predicate for `pare's.

            (pare? (kons 1 2))        => #t
            (pare? (cons 1 2))        => #f
            (kar (kons 1 2))          => 1
            (kdr (kons 1 2))          => 2
            (let ((k (kons 1 2)))
              (set-kar! k 3)
              (kar k))                => 3


File: bigloo.info,  Node: Serialization,  Next: Bit Manipulation,  Prev: Structures and Records,  Up: Standard Library

Serialization
=============

 - bigloo procedure: string->obj string
     This function converts a STRING which has been produced by
     `obj->string' into a Bigloo object.

 - bigloo procedure: obj->string object
     This function converts into a string _any_ Bigloo OBJECT which
     does not contain a procedure.

  The implementation of the last two functions ensures that for every
Bigloo  object `obj' (containing no procedure), the expression:

     (equal? obj (string->obj (obj->string obj)))
        => #t

 - bigloo procedure: binary-port? obj
 - bigloo procedure: open-output-binary-file file-name
 - bigloo procedure: append-output-binary-file file-name
 - bigloo procedure: open-input-binary-file file-name
 - bigloo procedure: close-binary-port binary-port
 - bigloo procedure: input-obj binary-port
 - bigloo procedure: output-obj binary-port obj
 - bigloo procedure: input-char binary-port
 - bigloo procedure: output-char binary-port char
     Bigloo allows Scheme objects to be dumped into, and restored from,
     files.  These operations are performed by the previous functions.
     The dump and the restore use the two functions `obj->string' and
     `string->obj'.

     It is also possible to use a binary file as a flat character file.
     This can be done by the means of `output-char' and `input-char'
     functions.

 - bigloo procedure: register-procedure-serialization serializer
          unserializer
     There is no existing portable method to dump and restore a
     procedure. Thus, if `obj->string' is passed a procedure, it will
     emit an error message.  Sometime, using strict restrictions, it
     may be convenient to use an ad-hoc framework to serialize and
     unserialize procedures. User may specify there own procedure
     serializer and unserializer. This is the role of
     `register-procedure-serialization'. The argument SERIALIZER is a
     procedure of one argument, converting a procedure into a
     characters strings. The argument UNSERIALIZER is a procedure of
     one argument, converting a characters string into a procedure. It
     belongs to the user to provide correct serializer and unserializer.

     Here is an example of procedure serializer and unserializer that
     may be correct under some Unix platform:

          (module foo
             (extern (macro %sprintf::int (::string ::string ::procedure) "sprintf")))
          
          (define (string->procedure str)
             (pragma "(obj_t)(strtoul(BSTRING_TO_STRING($1), 0, 16))" str))
          
          (define (procedure->string proc)
             (let ((item (make-string 10)))
                (%sprintf item "#p%lx" proc)
                item))
          
          (register-procedure-serialization procedure->string string->procedure)
          
          (let ((x 4))
             (let ((obj (cons "toto" (lambda (y) (+ x y)))))
                (let ((nobj (string->obj (obj->string obj))))
          	 (print ((cdr nobj) 5)))))


 - bigloo procedure: get-procedure-serialization
     Returns the a pair whose `car' is the current procedure serializer
     and the `cdr' is the current procedure unserializer.

 - bigloo procedure: register-process-serialization serializer
          unserializer
     Same as `register-procedure-serialization' for Bigloo processes.

 - bigloo procedure: get-process-serialization
     Same as `get-procedure-serialization' for Bigloo processes.


File: bigloo.info,  Node: Bit Manipulation,  Next: Hash Tables,  Prev: Serialization,  Up: Standard Library

Bit manipulation
================

  These procedures allow the manipulation of fixnums as bit-fields.

 - bigloo procedure: bit-or i1 i2
 - bigloo procedure: bit-xor i1 i2
 - bigloo procedure: bit-and i1 i2
 - bigloo procedure: bit-not i
 - bigloo procedure: bit-lsh i1 i2
 - bigloo procedure: bit-rsh i1 i2
          (bit-or 5 3)                           => 7
          (bit-xor 5 3)                          => 6
          (bit-and 5 3)                          => 1
          (bit-not 5)                            => -6
          (bit-lsh 5 3)                          => 40
          (bit-rsh 5 1)                          => 2


File: bigloo.info,  Node: Hash Tables,  Next: System Programming,  Prev: Bit Manipulation,  Up: Standard Library

Hash Tables
===========

* Menu:

* New Hash Tables::
* Deprecated Hash Tables::


File: bigloo.info,  Node: New Hash Tables,  Next: Deprecated Hash Tables,  Up: Hash Tables

Hash tables
-----------

  Bigloo offers hash tables. Here are described functions which define
and use them.

 - bigloo procedure: make-hashtable [bucket-len] [max-bucket-len]
     Defines an hash table for which the number of buckets is
     BUCKET-LEN.  The variable MAX-BUCKET-LEN specify when the table
     should be resized. If provided, these two values have to be exact
     integers greater or equal to 1. Normally you could ignore
     BUCKET-LEN and MAX-BUCKET-LEN arguments and call `make-hashtable'
     with no argument at all.

 - bigloo procedure: hashtable? obj
     Returns `#t' if OBJ is an hash table, constructed by
     `make-hashtable'.

 - bigloo procedure: hashtable-size table
     Returns the number of entries contained in TABLE.

 - bigloo procedure: hashtable-get table key
     Returns the entry whose key is KEY in TABLE. If not entry is found
     `#f' is returned.

 - bigloo procedure: hashtable-put! table key obj
     Puts OBJ in TABLE under the key KEY. This function returns the
     object bound in the table. If there was an object OBJ-OLD already
     in the table with the same key as OBJ, this function returns
     OBJ-OLD; otherwise it returns OBJ.

 - bigloo procedure: hashtable-remove! table key
     Removes the object associated to KEY from TABLE, returning `#t' if
     such object was bound in table and `#f' otherwise.

 - bigloo procedure: hashtable-update! table key update-fun init-value
     If key is already in table, the new value is calculated by
     `(update-fun current-value)'. Otherwise the TABLE is extended by
     an entry linking key and `init-value'.

 - bigloo procedure: hashtable->vector table
 - bigloo procedure: hashtable->list table
     Convert a hash table TABLE to a vector or to a list.

 - bigloo procedure: hashtable-for-each table fun
     Applies FUN to each of the keys and elements of TABLE (no order is
     specified). In consequence, FUN must be a procedure of two
     arguments. The first one is a key and the second one, an
     associated object.

  Here is an example of hash table.

     (define *table* (make-hashtable))
     
     (hashtable-put! *table* "toto" "tutu")
     (hashtable-put! *table* "tata" "titi")
     (hashtable-put! *table* "titi" 5)
     (hashtable-put! *table* "tutu" 'tutu)
     (hashtable-put! *table* 'foo 'foo)
     
     (print (hashtable-get *table* "toto"))
        -| "tutu"
     (print (hashtable-get *table* 'foo))
        -| 'foo
     (print (hashtable-get *table* 'bar))
        -| #f
     
     (hashtable-for-each *table* (lambda (key obj) (print (cons key obj))))
        -| ("toto" . "tutu")
           ("tata" . "titi")
           ("titi" . 5)
           ("tutu" . TUTU)
           (foo . foo)

 - bigloo generic: object-hashnumber object
     This generic function computes a hash number of the instance
     OBJECT.

     Example:
          (define-method (object-hashnumber pt::point)
             (with-access::point pt (x y)
                (+fx (*fx x 10) y)))


File: bigloo.info,  Node: Deprecated Hash Tables,  Prev: New Hash Tables,  Up: Hash Tables

Deprecated Hash tables
----------------------

  Bigloo offers hash tables. Here are described functions which define
and use them.

 - bigloo procedure: make-hash-table ms nb gk eq [is]
     Defines an hash table of maximum length MS. If IS is provided, it
     sets the initial table size. The formal NB is a function which, if
     applied to a KEY, has to return an integer bound in interval
     [0..MS]. The formal GK is a function which, if applied to an
     object, returns its key. For example, the identity is a good
     candidate for integers, strings, symbols, etc. The last formal EQ
     is a equivalence predicate which is used when searching for an
     entry in the table.

 - bigloo procedure: hash-table? obj
     Returns `#t' if OBJ is an hash table.

 - bigloo procedure: hash-table-nb-entry table
     Returns the number of entries contained in TABLE.

 - bigloo procedure: get-hash key table
     Returns the entry whose key is KEY in TABLE. If not entry is found
     `#f' is returned.

 - bigloo procedure: put-hash! obj table
     Puts OBJ in TABLE. This function returns the object bound in the
     table. If there was an object OBJ-OLD already in the table with
     the same key as OBJ, this function returns OBJ-OLD; o therwise it
     returns OBJ.

 - bigloo procedure: rem-obj-hash! obj table
     Removes OBJ from TABLE, returning `#t' if such object was bound in
     table and `#f' otherwise.

 - bigloo procedure: rem-key-hash! key table
     Removes an object associated with KEY in TABLE, returning `#t' if
     such an object was bound in table and `#f' otherwise.

 - bigloo procedure: for-each-hash fun table
     Applies FUN to each of the elements of TABLE (no order is
     specified).

  Some functions compute hash numbers from Scheme objects:

 - bigloo procedure: string->0..255 string
 - bigloo procedure: string->0..2^x-1 string power
     The formal POWER has to be a power of 2 between 1 and 16.

 - bigloo procedure: int->0..255 int
 - bigloo procedure: int->0..2^x-1 int power
 - bigloo procedure: obj->0..255 obj
 - bigloo procedure: obj->0..2^x-1 obj power

  Here is an example of hash table that contains pairs:

     (define *table*
        (make-hash-table 1024
     	            (lambda (o) (string->0..2^x-1 o 10))
     		    (lambda (x) (car x))
     		    string=?
     		    64))
     
     (let ((cell1 (cons "toto" "tutu"))
           (cell2 (cons "tata" "titi"))
           (cell3 (cons "titi" 5))
           (cell4 (cons "tutu" 'tutu)))
        (put-hash! cell1 *table*)
        (put-hash! cell2 *table*)
        (put-hash! cell3 *table*)
        (put-hash! cell4 *table*))
     
     (print (cdr (get-hash "toto" *table*)))
        -| "tutu"
     
     (for-each-hash print *table*)
        -| ("toto" . "tutu")
           ("tata" . "titi")
           ("titi" . 5)
           ("tutu" . TUTU)


File: bigloo.info,  Node: System Programming,  Next: Date,  Prev: Hash Tables,  Up: Standard Library

System programming
==================

* Menu:

* Operating System Interface::
* Files::
* Process::
* Socket::


File: bigloo.info,  Node: Operating System Interface,  Next: Files,  Up: System Programming

Operating System interface
--------------------------

 - bigloo procedure: register-exit-function! proc
     Register PROC as an exit functions. PROC is a procedure accepting
     of one argument. This argument is the numerical value which is the
     status of the exit call. The registered functions are called when
     the execution ends.

 - bigloo procedure: exit int
     Apply all the registered exit functions then stops an execution,
     returning the integer INT.

 - bigloo procedure: signal n proc
     Provides a signal handler for the operating system dependent signal
     N. PROC is a procedure of one argument.

 - bigloo procedure: get-signal-handler n
     Returns the current handler associated with signal N or `#f' if no
     handler is installed.

 - bigloo procedure: system . strings
     Append all the arguments STRINGS and invoke the native host
     `system' command on that new string which returns an integer.

 - bigloo procedure: system->string . strings
     Append all the arguments STRINGS and invoke the native host
     `system' command on that new string. If the command completes,
     `system->string' returns a string made of the output of the
     command.

 - bigloo procedure: getenv string
     Returns the string value of the Unix shell's STRING variable. If no
     such variable is bound, `getenv' returns `#f'.

 - bigloo procedure: putenv string val
     Adds or modifies the global environment variable STRING so that it
     is bound to VAL after the call. This facility is not supported by
     all back-end. In particular, the JVM back-end does not support it.

 - bigloo procedure: date
     Returns the current date in a `string'. See also *Note Date::.

 - bigloo procedure: sleep ms
     Sleeps for a delay during at least MS microseconds.

 - bigloo procedure: command-line
     Returns a list of strings which are the Unix command line
     arguments.

 - bigloo procedure: executable-name
     Returns the name of the running executable.

 - bigloo procedure: os-class
     Gives the OS class (e.g. `unix').

 - bigloo procedure: os-name
     Gives the OS name (e.g. `Linux').

 - bigloo procedure: os-arch
     Gives the host architecture (e.g. `i386').

 - bigloo procedure: os-version
     Gives the operating system version (e.g. `RedHat 2.0.27').

 - bigloo procedure: os-tmp
     Gives the regular temporary directory (e.g. `/tmp').

 - bigloo procedure: file-separator
     Gives the operating system file separator (e.g. `#\/').

 - bigloo procedure: path-separator
     Gives the operating system file path separator (e.g.`#\:').

  For additional functions (such as `directory->list') see *Note Input
and Output::.

 - bigloo procedure: unix-path->list
     Converts a Unix path to a Bigloo list of strings.

          (unix-path->list ".")           => (".")
          (unix-path->list ".:/usr/bin")  => ("." "/usr/bin")


 - bigloo procedure: hostname
     Returns the fully qualified name of the current host.


File: bigloo.info,  Node: Files,  Next: Process,  Prev: Operating System Interface,  Up: System Programming

Files
-----

  See *Note Input and Output:: for file and directory handling. This
section only deals with _name_ handling. Four procedures exist to
manipulate Unix filenames.

 - bigloo procedure: basename string
     Returns a copy of STRING where the longest prefix ending in `/' is
     deleted if any existed.

 - bigloo procedure: prefix string
     Returns a copy of STRING where the suffix starting by the char
     `#\.' is deleted. If no prefix is found, the result of `prefix' is
     a copy of `string'. For instance:

          (prefix "foo.scm")
             => "foo"
          (prefix "./foo.scm")
             => "./foo"
          (prefix "foo.tar.gz")
             => "foo.tar"

 - bigloo procedure: suffix string
     Returns a new string which is the suffix of STRING. If no suffix
     is found, this function returns an empty string. For instance,

          (suffix "foo.scm")
             => "scm"
          (suffix "./foo.scm")
             => "scm"
          (suffix "foo.tar.gz")
             => "gz"

 - bigloo procedure: dirname string
     Returns a new string which is the directory component of STRING.
     For instance:

          (dirname "abc/def/ghi")
             => "abc/def"
          (dirname "abc")
             =>  "."
          (dirname "abc/")
             => "abc"
          (dirname "/abc")
             => "/"

 - bigloo procedure: pwd
     Returns the current working directory.

 - bigloo procedure: chdir dir-name
     Changes the current directory to DIR-NAME. On success, `chdir'
     returns `#t'. On failure it returns `#f'.

 - bigloo procedure: make-file-name dir-name name
     Make an absolute file-name from a directory name DIR-NAME and a
     relative name NAME.

 - bigloo procedure: make-file-path dir-name name . names
     Make an absolute file-name from a directory name DIR-NAME and a
     relative name NAMEs.

 - bigloo procedure: find-file/path name path
     Search, in sequence, in the directory list PATH for the file NAME.
     If NAME is an absolute name, then PATH is not used to find the
     file. If NAME is a relative name, the function `make-file-name' is
     used to build absolute name from NAME and the directories in PATH.
     The current path is not included automatically in the list of
     PATH. In consequence, to check the current directory one may add
     `"."' to the PATH list. On success, the absolute file name is
     returned. On failure, `#f' is returned. Example:

          (find-file/path "/etc/passwd" '("/toto" "/titi"))
             => "/etc/passwd"
          (find-file/path "passwd" '("/toto" "/etc))
             => "/etc/passwd"
          (find-file/path "pass-wd" '("." "/etc"))
             => #f

 - bigloo procedure: make-static-library-name name
     Make a static library name from NAME by adding the static library
     regular suffix.

 - bigloo procedure: make-shared-library-name name
     Make a shared library name from NAME by adding the shared library
     regular suffix.

 - bigloo procedure: file-exists? string
     This procedure returns `#t' if the file STRING exists. Otherwise
     it returns `#f'.

 - bigloo procedure: delete-file string
     Deletes the file named STRING. The result of this procedure is
     `#f' is the operation succeeded. The result is `#t' otherwise.

 - bigloo procedure: rename-file string1 string2
     Renames the file STRING1 as STRING2. The two files have to be
     located on the same file system. If the renaming succeeds, the
     result is `#t', otherwise it is `#f'.

 - bigloo procedure: directory? string
     This procedure returns `#t' if the file STRING exists and is a
     directory. Otherwise it returns `#f'.

 - bigloo procedure: make-directory string
     Creates a new directory named STRING. It returns `#t' if the
     directory was created. It returns `#f' otherwise.

 - bigloo procedure: make-directories string
     Creates a new directory named STRING, including any necessary but
     nonexistent parent directories. It returns `#t' if the directory
     was created. It returns `#f' otherwise. Note that if this
     operation fails it may have succeeded in creating some of the
     necessary parent directories.

 - bigloo procedure: delete-directory string
     Deletes the directory named STRING. The directory must be empty in
     order to be deleted. The result of this procedure is unspecified.

 - bigloo procedure: directory->list string
     If file STRING exists and is a directory, this function returns the
     list of files in STRING.

 - bigloo procedure: file-modification-time string
     The date (in second) of the last modification for file STRING. The
     number of seconds is represented by a value that may be converted
     into a date by the means of `seconds->date' (see *Note Date::).

 - bigloo procedure: file-size string
     Returns the size (in bytes) for file STRING.

 - bigloo procedure: chmod string [option]
     Change the access mode of the file named STRING. The OPTION must
     be either a list of the following symbols `read', `write' and
     `execute' or an integer. If the operation succeeds, `chmod'
     returns `#t'. It returns `#f' otherwise.

     Example:

          (chmod (make-file-name (getenv "HOME") ".bigloorc") 'read 'write)
          (chmod (make-file-name (getenv "HOME") ".bigloorc") #o777)


File: bigloo.info,  Node: Process,  Next: Socket,  Prev: Files,  Up: System Programming

Process support
===============

  Bigloo provides access to Unix-like processes as first class objects.
The implementation and this documentation are to a great extent copies
of the STk [Gallesio95] process support. Basically, a process contains
four informations: the standard Unix process identification (aka PID)
and the three standard files of the process.

 - bigloo procedure: run-process command arg...
     `run-process' creates a new process and run the executable
     specified in COMMAND. The ARG correspond to the command line
     arguments.  When is process completes its execution, non pipe
     associated ports are automatically closed. Pipe associated ports
     have to be explicitly closed by the program. The following values
     of P have a special meaning:

        * `input:' permits to redirect the standard input file of the
          process.  Redirection can come from a file or from a pipe. To
          redirect the standard input from a file, the name of this
          file must be specified after `input:'.  Use the special
          keyword `pipe:' to redirect the standard input from a pipe.

        * `output:' permits to redirect the standard output file of the
          process.  Redirection can go to a file or to a pipe. To
          redirect the standard output to a file, the name of this file
          must be specified after `output:'. Use the special keyword
          `pipe:' to redirect the standard output to a pipe.

        * `error:' permits to redirect the standard error file of the
          process.  Redirection can go to a file or to a pipe. To
          redirect the standard error to a file, the name of this file
          must be specified after `error:'. Use the special keyword
          `pipe:' to redirect the standard error to a pipe.

        * `wait:' must be followed by a boolean value. This value
          specifies if the process must be ran asynchronously or not. By
          default, the process is run asynchronously (i.e. `wait:' if
          `#f').

        * `host:' must be followed by a string. This string represents
          the name of the machine on which the COMMAND must be
          executed. This option uses the external command `rsh'. The
          shell variable `PATH' must be correctly set for accessing it
          without specifying its absolute path.

        * `fork:' must be followed by a boolean value. This value
          specifies if the process must substitute the current
          execution. That is, if the value is `#t' a new process is
          spawned otherwise, the current execution is stopped and
          replaced by the execution of `command'.

        * `env:' must be followed by a string of the form `VAR=VAL'.
          This will bound an environment variable in the spawned
          process. A `run-process' command may contain several `env:'
          arguments. The current variables of the current process are
          also passed to the new process.

     The following example launches a process which execute the Unix
     command `ls' with the arguments `-l' and `/bin'. The lines printed
     by this command are stored in the file `tmp/X'.

          (run-process "ls" "-l" "/bin" output: "/tmp/X")

     The same example with a pipe for output:

          (let* ((proc (run-process "ls" "-l" "/bin" output: pipe:))
                 (port (process-output-port proc)))
             (let loop ((line (read-line port)))
                (if (eof-object? line)
                    (close-input-port port)
                    (begin
                       (print line)
                       (loop (read-line port))))))

     One should not that the same program can be written with explicit
     process handling but making use of the `|' notation for
     `open-input-file'.

          (let ((port (open-input-file "| ls -l /bin")))
             (let loop ((line (read-line port)))
                (if (eof-object? line)
                    (close-input-port port)
                    (begin
                       (print line)
                       (loop (read-line port))))))

     Both input and output ports can be piped:

          (let* ((proc (run-process "/usr/bin/dc" output: pipe: input: pipe:))
                 (inport (process-input-port proc))
                 (port (process-output-port proc)))
             (fprint inport "16 o")
             (fprint inport "16 i")
             (fprint inport "10")
             (fprint inport "10")
             (fprint inport "+ p")
             (flush-output-port inport)
             (let loop ((line (read-line port)))
                (if (eof-object? line)
          	  (close-input-port port)
          	  (begin
          	     (print line)
          	     (loop (read-line port))))))   -| 20

     _Note:_ The call to `flush-output-port' is mandatory in order to
     get the `dc' process to get its input characters.

     _Note:_ Thanks to Todd Dukes for the example and the suggestion of
     including it this documentation.

 - bigloo procedure: process? obj
     Returns `#t' if OBJ is a process, otherwise returns `#f'.

 - bigloo procedure: process-alive? process
     Returns `#t' if PROCESS is currently running, otherwise returns
     `#f'.

 - bigloo procedure: close-process-ports command arg...
     Close the three ports associated with a process. In general the
     ports should not be closed before the process is terminated.

 - bigloo procedure: process-pid process
     Returns an integer value which represents the Unix identification
     (PID) of the PROCESS.

 - bigloo procedure: process-input-port process
 - bigloo procedure: process-output-port process
 - bigloo procedure: process-error-port process
     Return the file port associated to the standard input, output and
     error of PROCESS otherwise returns `#f'.  Note that the returned
     port is opened for reading when calling `process-output-port' or
     `process-error-port'.  It is opened for writing when calling
     `process-input-port'.

 - bigloo procedure: process-wait process
     This function stops the current process until PROCESS completion.
     This function returns `#f' when PROCESS is already terminated. It
     returns `#t' otherwise.

 - bigloo procedure: process-exit-status process
     This function returns the exit status of PROCESS if it is has
     finished its execution. It returns `#f' otherwise.

 - bigloo procedure: process-send-signal process s
     Sends the signal whose integer value is S to PROCESS. Value of S
     is system dependent. The result of `process-send-signal' is
     undefined.

 - bigloo procedure: process-kill process
     This function brutally kills PROCESS. The result of `process-kill'
     is undefined.

 - bigloo procedure: process-stop process
 - bigloo procedure: process-continue process
     Those procedures are only available on systems that support job
     control.  The function `process-stop' stops the execution of
     PROCESS and `process-continue' resumes its execution.

 - bigloo procedure: process-list
     This function returns the list of processes which are currently
     running (i.e. alive).

