This is sizzle-ref.info, produced by makeinfo version 4.0 from
sizzle-ref.texi.

INFO-DIR-SECTION Sizzle Scheme Interpreter
START-INFO-DIR-ENTRY
* sizzle-ref: (sizzle-ref).     Sizzle reference manual.
END-INFO-DIR-ENTRY

   This file documents the Sizzle Scheme interpreter.

   Copyright (C) 1999, 2000 Martin Grabmueller

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.


File: sizzle-ref.info,  Node: Network Procedures,  Next: Module System,  Prev: System interface functions,  Up: Builtin Procedures

Network Procedures
==================

   The procedures in this section are useful for network programming.
You have to use the module `(core net)' in order to make them visible.

 - Exception: network-error
     This exception is thrown when an error occurs while using any of
     the network functions.  The exception contains an error message
     obtained with `strerror(errno)' or `herror()', whatever is
     appropriate for the specific error.

 - Primitive procedure: socket domain type protocol
     Creates a socket port using DOMAIN, TYPE and PROTOCOL.  This is a
     direct wrapper to the C library function, so refer to the libc
     documentation for details.  Normally you specify the DOMAIN as the
     constant `AF_INET' and the TYPE `SOCK_STREAM' for normal internet
     sockets.  This procedure may raise a `system-error' exception if
     an error occurs.  The following socket types are also defined:
    `SOCK_STREAM'

    `SOCK_DGRAM'

    `SOCK_RAW'

    `SOCK_SEQPACKET'

    `SOCK_RDM'
     For the defined address family constants, refer to the
     documentation for `bind'.

 - Primitive procedure: shutdown sock how
     Sockets can be closed simply by using `close-port'. The `shutdown'
     procedure allows reception or transmission on a connection to be
     shut down individually, according to the parameter HOW:
    0
          Stop receiving data for this socket.  If further data
          arrives, reject it.

    1
          Stop trying to transmit data from this socket.  Discard any
          data waiting to be sent.  Stop looking for acknowledgement of
          data already sent; don't retransmit it if it is lost.

    2
          Stop both reception and transmission.  The return value is
     unspecified.

 - Primitive procedure: listen sock backlog
     This procedure enables SOCK to accept connection requests.
     BACKLOG is an integer specifying the maximum length of the queue
     for pending connections.  If the queue fills, new clients will
     fail to connect until the server calls `accept' to accept a
     connection from the queue.  The return value is unspecified.

 - Primitive procedure: gethostbyname name
     Returns the IPv4 address of the host named NAME.  NAME may be
     either a string, which must represent a valid hostname, or an
     integer value.  If it is an integer value, it is returned
     unchanged and not validated, if it is a string, the IP address is
     looked up and returned.  This procedure may raise a
     `network-error' exception if an error occurs.

 - Primitive procedure: accept sock
     Accepts a connection on a bound, listening socket SOCK.  If there
     are no pending connections in the queue, it waits until one is
     available unless the non-blocking option has been set on the
     socket.

     The return value is a pair in which the "car" is a new socket port
     for the connection and the "cdr" is an object with address
     information about the client which initiated the connection.

     If the address is not available then the "cdr" will be an empty
     vector.  SOCK does not become part of the connection and will
     continue to accept new requests.

 - Primitive procedure: getsockname sock
     Returns the address of SOCK, in the same form as the object
     returned by `accept'.

 - Primitive procedure: getpeername sock
     Returns the address of the socket SOCK is connected to, in the
     same form as the object returned by `accept'.

 - Primitive procedure: ntohl n
     Converts the 32 bit value N from network to host byte order.

 - Primitive procedure: htonl n
     Converts the 32 bit value N from host to network byte order.

 - Primitive procedure: ntohs n
     Converts the 16 bit value N from network to host byte order.

 - Primitive procedure: htons n
     Converts the 16 bit value N from host to network byte order.

 - Primitive procedure: fileno port
     Returns the file descriptor used for operations on PORT.  PORT
     must be a file descriptor port, or an error will be signalled.

 - Primitive procedure: connect hostname port
     Establish a connection to the host identified by HOSTNAME on port
     PORT.  HOSTNAME must be either a string naming the host or an
     integer value which represents an IP address.  Currently, only IPv4
     addresses are supported.  Returns a socket port which can be
     written to and read from to communicate with the peer.  This
     procedure may raise `network-error' and `system-error' exceptions.

 - Primitive procedure: server-socket port
     Returns a socket, which listens on the local IP address on port
     PORT.  A port returned by this procedure may be used in calls to
     `accept'.

 - Primitive procedure: server-loop port proc
     This procedure can be used to implement simple network
     applications.  PORT must be a port created by `server-socket' or
     any equivalent calling sequence to `socket', `bind' and `listen'.
     `server-loop' will wait for incoming connection using `accept' and
     call PROC when a connection is available.  PROC must expect two
     parameters, the first one being an input port connected to the
     accepted socket, the second an output port connected to the socket.

 - Primitive procedure: bind scheme-port family address port
     Bind the port SCHEME-PORT, created with a call to `socket' to the
     address specified by FAMILY, ADDRESS, and the port number PORT.
     This procedure returns an unspecified value.

     The following address families are defined:
    `AF_UNIX'
          Unix sockets family.

    `AF_INET'
          Internet socket family.  If your system supports them, the
     following families are also defined:
    `AF_ISO'

    `AF_NS'

    `AF_IMPLINK'

 - Primitive procedure: select rdfd wrfd exfd sec usec
     Perform the `select' system call on the file descriptor sets RDFD,
     WRDF and EXFD.  The timeout value is calculated from the seconds
     SEC and the microseconds USEC.  The number of the highest file
     descriptor in any of the sets is returned as the result.

 - Primtitive procedure: gethostname
     Get the host name of the local host.  The returned value is a
     string.

 - Primitive procedure: sethostname name
     Set the host name of the local host to NAME.  The return value is
     not specified.

 - Primitive procedure: getdomainname
     Get the domain name of the local host.  The returned value is a
     string.

 - Primitive procedure: setdomainname
     Set the domain name of the local host to NAME.  The return value
     is not specified.

 - Primitive procedure: inet-aton addr
     Convert the internet address ADDR from dotted decimal notation to
     binary data.  The returned value is an integer.

 - Primitive procedure: inet-ntoa addr
     Convert the internet address ADDR from binary representation to a
     string.  The returned value is a string.


File: sizzle-ref.info,  Node: Module System,  Next: Dynamic Loading,  Prev: Network Procedures,  Up: Builtin Procedures

Module System
=============

   Scheme is suited for programming large programs, but it is very
inconvenient to implement modules with restricted exports using standard
techniques.  Therefore, a module system similar to Guile's has been
implemented.

   In Sizzle, a module is a data structure with a private environment in
which all definitions local to the module are stored and an export list
which defines which of the defined symbols are to be exported to other
modules.  When a module is imported using the syntactic form
`use-modules', the symbol bindings from the export list are transferred
to the environment of the importing module, thus making visible the
exports.  This works for procedures as well as for variables and
constants.

   The syntax and procedures for modules are always available.

 - Syntax: use-modules name0 name1 ...
     Import all modules listed as NAMES.  If any module is not yet
     loaded, it will be loaded using the load path.  Modules imported
     by any of the imported modules will be loaded recursively.

 - Syntax: define-module name options ...
     Define a module called NAME and switch to the context of the new
     module, that means that all definitions made until the end of the
     file will be made in the private environment of the module.
     Definitions can be made public using the syntactic form `export',
     documented below.

     Options may be one or more pair of a keyword and a value.  The
     following keywords are presently defined:
    `#:use-module'
          The value must be a module name (a list of symbols) which
          specifies a module to be loaded for defining the new module.

    `#:export'
          The value must be a list of symbols listing the defines to be
          exported.  This is an alternative notation for the `export'
          syntactic form.

 - Syntax: export symbol0 symbol1 ...
     Add all SYMBOLS to the export list of the currently active module.

 - Primitive procedure: module-list
     Return a list of currently loaded modules.

 - Primitive procedure: current-module
     Return the module in which currently definitions take place.


File: sizzle-ref.info,  Node: Dynamic Loading,  Next: Macro functions,  Prev: Module System,  Up: Builtin Procedures

Dynamic Loading
===============

   Sizzle support dynamic loading of shared libraries under Unix using
the dl interface.  The following procedures are not available if no
usable dynamic loading support was found for the underlying platform or
when disabled with the `--disable-dl' configuration option.

 - Exception: dl-error
     This exception is thrown when an error occurs while using the `dl'
     library.  The exception contains an error message obtained with
     `dlerror()'.

 - Primitive procedure: load-library name [filename]
     Load and initialize the shared object name.  If FILENAME is
     specified, the file named FILENAME is `dlopen()''ed, otherwise the
     file name `libNAME.so' is opened via `dlopen()'.  When the loaded
     object exports a symbol called `zzz_init_NAME()', this function is
     called without arguments and should initialize the library.

     This function may throw a `dl-error' exception if the file could
     not be loaded or if the initialization function returned a value
     other than `RESULT_SUCCESS'.

   Besides the high-level procedure `load-library', some low-level
procedures are provided which implement a wrapper around the `dl'
library.

 - Primitive procedure: %dlopen filename [flags]
     `dlopen()' the file FILENAME and return a dynamic library object
     for that file.  FLAGS may be the bitwise or of the following
     constants:
    `RTLD_GLOBAL'
          Make the symbols in the loaded file available to other
          processes.

    `RTLD_LAZY'
          Relocate symbols when they are used.

    `RTLD_NOW'
          Relocate all symbols when the library is loaded.

 - Primitive procedure: %dlclose lib
     Take a dynamic library object LIB and close it.  After that, calls
     to `%dlsym' with the library LIB will fail.

 - Primitive procedure: %dlsym lib string
     Return the address of the symbol STRING in the library specified
     by the dynamic library object LIB.  Throw a `dl-error' exception
     if the dymbol could not be resolved.

 - Primitive procedure: %dlcall address
     Call the function specified by ADDRESS (which must have been found
     with a call to `%dlsym') without arguments.  A `dl-error'
     exception is thrown if the function returns a value other than
     `RESULT_SUCCESS'.


File: sizzle-ref.info,  Node: Macro functions,  Next: Runtime system,  Prev: Dynamic Loading,  Up: Builtin Procedures

Macro functions
===============

   Sizzle can handle macros defined using the primitive `define-macro'.
The macro interface should be compatible to Guile's, but I have not
yet verified that completely.  The macro syntax and procedures are
always available.

 - Syntax: define-macro (name arg ...) body
     Define a macro NAME which as many arguments as ARGS are given.
     When the macro is expanded, the symbols in ARGS are bound to the
     actual parameters of the macro call and BODY is evaluated.  The
     result of evaluating the macro body expression is then substituted
     for the macro call.  The return value is unspecified.

     This is an example of a macro `writeln', which prints all its
     arguments using `display' and then advances to the next line using
     `newline'.
          (define-macro (writeln . --x)
            `(begin (for-each display (list ,@--x)) (newline)))

     You have to be careful about the formal parameter names given with
     ARGS, because they may shadow variables visible when the macro is
     called.

 - Primitive procedure: expand-macro list
     Expand the macro call represented by LIST and return the expanded
     expression.  The `car' of the list must be a macro object.
          zzz: (define-macro (unless cond . body)
                 `(if (not ,cond) (begin ,@body)))
          zzz: (expand-macro (list unless '(> x 0) '(display x)))
          (if (not (> x 0)) (begin (display x)))

 - Primitive procedure: apply-macro macro list
     Apply the macro MACRO, which must have been created with
     `define-macro' to the argument list LIST.  This will cause the
     transformer procedure for MACRO to be applied to the arguments in
     LIST.  The value returned by the macro transformer is returned.


File: sizzle-ref.info,  Node: Runtime system,  Next: Self-Documentation,  Prev: Macro functions,  Up: Builtin Procedures

Runtime system
==============

   It is often necessary to access the runtime system for writing
efficient programs, but also for debugging purposes.  The procedures in
this section are provided for that task.  They are always available in
the interpreter.

 - Primitive procedure: garbage-collect
     Triggers immediate garbage collection.  The return value is
     unspecified.


File: sizzle-ref.info,  Node: Self-Documentation,  Next: Box Operations,  Prev: Runtime system,  Up: Builtin Procedures

Self-Documentation
==================

   Sizzle provides a mechanism to make using it more comfortable.  This
is some kind of self-documentation as known from programs like Emacs.
The principle of this feature is that every procedure object, both
primitive and user-defined can have a documentation object attached.
Normally, these objects are simply strings which tell how to use the
procedure, which parameters are expected and what value(s) is/are
returned, as well as a short description of the functionality.

   The following procedures help to make use of the self-documentation
system.  They are always available in the interpreter.

 - Primitive procedure: documentation obj
     Returns the documentation object attached to OBJ.  Returns `#f' if
     no wuch object is available.  For procedure objects,
     `documentation' tries to load a documentation string from the file
     `docstrings.txt', which was installed with Sizzle.  Not all
     primitives are documented in this file yet, so `#f' may be returned
     for them, too.

 - Primitive procedure: set-documentation! obj doc
     Attach the documentation object DOC to the Scheme object OBJ.  DOC
     will be returned when applying `documentation' to OBJ after
     calling this procedure.  The return value is unspecied.

 - Primitive procedure: describe obj
     Print a description of OBJ to the current output port.  This
     description includes the type of OBJ and the documentation object
     or documentation string attached to OBJ.  The return value is
     unspecified.

 - Primitive procedure: apropos string
     Print a one-line description of all procedures with STRING their
     names.  This can be used to get a list of procedure names, so that
     `describe' can be used on the procedures to get more information
     about them.  The return value of this procedure is not specifed.


File: sizzle-ref.info,  Node: Box Operations,  Next: Pointer Operations,  Prev: Self-Documentation,  Up: Builtin Procedures

Box Operations
==============

   This section documents the procedures provided for handling boxes.
For more information about boxes, refer to *Note Boxes::.  All box
primitives are always available in the interpreter.

 - Primitive procedure: box? obj
     Return `#t' if OBJ is a box, `#f' otherwise.

 - Primitive procedure: make-box obj
     Return a newly allocated box object which contains the object OBJ.

 - Primitive procedure: box-ref b
     Return the object contained in the box object B.

 - Primitive procedure: box-set! b obj
     Store the object OBJ into the box object B.  Return an unspecified
     value.


File: sizzle-ref.info,  Node: Pointer Operations,  Next: Misc functions,  Prev: Box Operations,  Up: Builtin Procedures

Pointer Operations
==================

   Sizzle provides pointer objects which are useful when interfacing to
C library procedures.  For more information, have a look at *Note
Pointers::.  These procedures are always available.

 - Primitive procedure: pointer? obj
     Return `#t' if OBJ is a pointer object, `#f' otherwise.

 - Primitive procedure: make-pointer n
     Create a new pointer object.  N must be a non-negative integer,
     and a memory block big enough to hold N bytes will be allocated
     and the pointer will point to it.  If N is 0, then a null-pointer
     will be returned.

 - Primitive procedure: invalidate-pointer! p
     Invalidate the pointer P by setting its invalid flag.


File: sizzle-ref.info,  Node: Misc functions,  Next: Syntactic Forms,  Prev: Pointer Operations,  Up: Builtin Procedures

Misc functions
==============

   This section is a catch-all for all primitive procedures which do not
fit into any of the other categories.  They are always available in the
interpreter except when otherwise noted.

 - Primitive procedure: gc-stats
     Return an association list containing various information about the
     state of the garbage collector.  The following elements are
     contained in the list:
    `used-cons-cells'
          Number of cons cells which are currently in use.

    `used-tagged-cells'
          Number of tagged cells which are currently in use.

    `allocated-cons-cells'
          Number of cons cells in the cons heap, both free cells and
          cells which are in use.

    `allocated-tagged-cells'
          Number of tagged cells in the tagged heap, both free cells
          and cells which are in use.

    `cons-heap-usage'
          Number of bytes currently allocated for the cons heap.

    `tagged-heap-usage'
          Number of bytes currently allocated for the tagged heap.

    `other-usage'
          Number of bytes currently allocated for other purposes, such
          as for vector and string contents etc.

    `gc-count'
          Number of garbage collections since startup.

    `gc-time'
          Time spent in the garbage collector since the interpreter
          started.

    `gc-percent'
          Amount of the total running time which was spent in the
          garbage collector since the interpreter started up.

 - Primitive procedure: profile-stats
     Return an association list containing various information about
     internal profiling statistics.  The values in the returned
     association list are only valid if profiling was enabled during
     compilation.  The following elements are contained in the list:
    `global-accesses'
          Variable accesses which required a complete variable lookup.

    `lloc-accesses'
          Variable access which went through an `lloc' object.

    `gloc-accesses'
          Variable access which went through a `gloc' object.

    `tail-calls'
          Procedure calls which were executed tail-recursively.

    `evaluate-calls'
          Calls to the function `zzz_evaluate()'.

    `closure-calls'
          Calls to closure objects (lambda applications).

    `primitive-calls'
          Calls to primitive procedures.

    `syntactic-calls'
          Executions of non-memoized syntactic forms.

    `immediate-calls'
          Executions of memoized syntactic forms.

 - Primitive procedure: random n
     Return a random number (an integer value) which is in the range
     [0..N).  `random' returns always the same sequence of random
     number, unless you have set the random seed using `srand'.

 - Primitive procedure: srand n
     Set the random seed for the procedure `random' to N.  The return
     value is not specified.

 - Library procedure: 1+ x
 - Library procedure: 1- x
 - Library procedure: add1 x
 - Library procedure: sub1 x
     Handy helper functions.  `1+' and `add1' return their argument
     plus 1, `1-' and `sub1' return their argument minus 1.  These
     functions are often used in textbooks on Scheme, so I put them in.

     These procedures are not supported when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.

 - Library procedure: pretty-print obj [port]
     Pretty-print the Scheme object OBJ to PORT, or to the standard
     output port if PORT is omitted.  Pretty-printing means that list
     and vector structures will be printed in a human-readable form and
     with proper indentation.

     You have to use the module `(core pprint)' to have access to this
     procedure.


File: sizzle-ref.info,  Node: Syntactic Forms,  Prev: Misc functions,  Up: Builtin Procedures

Syntactic Forms
===============

   There are two types of syntactic forms.  The forms labelled with
Syntax are builtin syntax, the forms labelled Defined syntax or Macro
are defined in the startup file `init.scm' and may be not present if
the embedding application does not load this init file.

   Except when otherwise stated, all of these syntactic forms and
procedures are always available in the interpreter.

 - Syntax: quote obj
     Returns its argument OBJ unevaluated.  This is normally used to
     type in symbols and is used so often that a shorthand form exists:
     Instead of `(quote foo)' you can write `'foo'.

 - Syntax: quasiquote obj
     Works similar to `quote', with the difference that expressions with
     `unquote' or `unquote-splicing' are evaluated in OBJ. Also has a
     shorthand form: ``foo' has the same meaning `(quasiquote foo)'.

 - Syntax: unquote obj
     When used inside of a `quasiquote' expression, evaluates its
     argument. Also has a shorthand form: `,foo' has the same meaning
     `(unquote foo)'. `unquote' may only be used inside of `quasiquote'
     expression, an error is signalled if used in another context.

 - Syntax: unquote-splicing obj
     When used inside of a `quasiquote' expression, evaluates its
     argument. The difference between `unquote' and `unsuote-splicing'
     is that the latter requires its argument to evaluate to a list
     which is then inserted at the current position with one level of
     nesting removed. Also has a shorthand form: `,@foo' has the same
     meaning `(unquote-splicing foo)'. `unquote-splicing' may only be
     used inside of `quasiquote' expression, an error is signalled if
     used in another context.

 - Syntax: set! variable expression
     Set the value of VARIABLE to the value of EXPRESSION.  The return
     value is not specified. You can only use `set!' on variables which
     have been already defined by either `define' or one of the
     `let'-constructs.

 - Syntax: define variable expression
     Define VARIABLE as a variable and set its value to the value of
     EXPRESSION.  The return value is not specified.

 - Syntax: define (variable arg1 ...) commands ...
 - Syntax: define (variable arg1 ... . argn) commands ...
 - Syntax: define (variable . arg) commands ...
     Special form of `define' which is equivalent to
          (define variable (lambda (arg1 ...) commands ...
          (define variable (lambda (arg1 ... . argn) commands ...
          (define variable (lambda arg commands ...

 - Syntax: undefine symbol
     Make the symbol SYMBOL undefined.  After calling this special
     form, any references to SYMBOL will cause an `unbound-variable'
     error.  The return value is not specified.

 - Primitive procedure: defined? symbol
     This is not a special form, but it fits best into this section
     together with `define' and `undefine'.  `defined?' returns `#t' if
     SYMBOL is a defined variable and `#f' otherwise.

 - Syntax: define-constant variable expression
     Define VARIABLE as a variable and set its value to the value of
     EXPRESSION.  The return value is not specified.  The difference
     between `define' and `define-constant' is that variables created
     using `define-constant' are read-only and cannot be modified with
     `set!'.  This enables runtime optimizations because references to
     constant variables can be replaced by the variable's value,
     eliminating symbol lookups.

 - Syntax: if condition then [else]
     Evaluates CONDITION and then checks its return value.  If the
     value is `#t', THEN is evaluated and the result of that evaluation
     is returned.  Otherwise, the behaviour depends on the presence of
     the ELSE expression.  If ELSE is not provided, the return value is
     unspecified, otherwise ELSE is evaluated and the result is
     returned.

 - Syntax: cond clause1 clause2 ...
     Each CLAUSE is of the form
          (test expression1 ...)
     Alternatively, a CLAUSE may be of the form
          (test => expression)
     and the last CLAUSE may be an else clause, which has the form
          (else expression1 expression2 ...)
     A `cond' expression is evaluated by evaluating the TEST
     expressions of successive CLAUSES in order until one of them
     evaluates to a true values. The first CLAUSE whose TEST evaluates
     to true is chosen and the EXPRESSIONS in the clause are evaluated
     in order and the value of the last expression is returned as the
     value of the `cond' expression. If the selected CLAUSE has no
     EXPRESSIONS, the value of the TEST is returned. An ELSE CLAUSE is
     chosen and the following EXPRESSIONS are evaluated if no other
     TEST evaluates to true.

     If the selected CLAUSE has the `=>' form, the EXPRESSION following
     the arrow must evaluate to a procedure to which the result of the
     TEST is applied to yield the result of the `cond' expression.

 - Syntax: case key clause1 clause2 ...
     KEY may be any expression. Each CLAUSE should have the form
          ((datum1 ...) expression1 expression2 ...)
     where each datum is an external representation of some object. The
     last CLAUSE may be of the form
          (else expression1 expression2 ...)

     A `case' expression is evaluated by first evaluating the KEY.  The
     resulting value is compared against each of the DATUMS using the
     equality predicate `eqv?', and if a match is found, the EXPRESSION
     following the matching DATUM is evaluated and the result of the
     last EXPRESSION is returned as the result of the `case' expression.

     Should no CLAUSE match and an `else' clause is present, that
     clause is chosen and the EXPRESSIONS following the `else' are
     evaluated in order to compute the result of the `case' expression.

 - Syntax: do ((variable1 init1 step1) ...) (test expression ...)
          command ...
     `do' is an iteration construct. First, all VARIABLES are bound to
     the values of their corresponding INIT values.  Then the TEST
     expression is evaluated and if the value is false, the COMMANDS
     are evaluated in order. After each iteration, the VARIABLES are
     bound to the result of evaluating the corresponding STEP
     expressions and the TEST is evaluated again. The loop terminates
     as soon as the TEST evaluates to a true value. Then the
     EXPRESSIONS after the TEST are evaluated in order and the value of
     the last EXPRESSION is returned as the value of the `do'
     expression.

 - Syntax: begin command ...
     `begin' accepts one or more expressions as its arguments. All
     expressions are evaluated in the order they appear in the argument
     list and the result of the last expression is returned. The result
     is unspecified if no COMMAND is given.

 - Syntax: let ((variable expression) ...) command ...
     `let' creates a block in which all variables named in the first
     argument list are redefined to the corresponding values.  The
     expressions in the body are executed and afterwards all variables
     are rebound to their original values. The result of the last
     evaluated expression is returned. If no body expressions are
     given, the result is unspecified. When using `let', the VARIABLES
     are not visible to EXPRESSIONS, because the variables are bound
     after all the expressions are evaluated.

 - Syntax: let variable ((variable1 expression) ...) command ...
     The named-let construct is used to implement looping constructs.
     VARIABLE is bound to a lambda expression which takes the VARIABLES
     as its formal parameters and then calls the expression with actual
     parameters set to the EXPRESSIONS. The body of the let can than
     refer to VARIABLE by calling it recursively as a function.

 - Syntax: let* ((variable expression) ...) command ...
     Works like `let', but the EXPRESSIONS are evaluated in
     left-to-right order where each VARIABLE is visible to the
     expression on its right.

 - Syntax: letrec ((variable expression) ...) command ...
     Works like `let', but the VARIABLES are visible to all
     EXPRESSIONS, thus making possible mutual recursive procedures.

 - Syntax: lambda (variable1 ...) command ...
 - Syntax: lambda (variable1 ... . variablen) command ...
 - Syntax: lambda variable command ...
     Lambda is used to define procedures. The VARIABLES are the formal
     parameters to which actual parameters will be bount. When the
     procedure is called, the actual parameters are bound and the
     COMMANDS are evaluated in order. The three syntactic forms above
     differ in the way parameters are bound.  The first lambda takes
     exactly as many actual arguments as VARIABLES are given, the
     second takes at least as many actual arguments as ARGUMENTS before
     the dot are given and binds VARIABLEN to a list of the rest of the
     arguments and the third form takes any number of arguments which
     will then be bound to VARIABLE.

 - Syntax: and expression ...
     `and' evaluates all EXPRESSIONS in order, but stops evaluation as
     soon as one of the EXPRESSIONS returns a false value. Returns `#f'
     if any of the expressions returns `#f' and returns the result of
     the last expression otherwise. When called without arguments, `#t'
     is returned.

 - Syntax: or expression ...
     `and' evaluates all EXPRESSIONS in order, but stops evaluation as
     soon as one of the EXPRESSIONS returns a non-false value. Returns
     `#f' if none of the expressions returns `#t' and returns the
     result of the first expression returning a non-false value
     otherwise.  When called without arguments, `#f' is returned.

 - Syntax: delay expression
     Delays the evaluation of expression. Returns a promise, which when
     later forced by a call to `force' will evaluate EXPRESSION and
     return the result. Evaluation is performed in the same environment
     in which the promise was created.

 - Macro: when test body ...
     Evaluates all expressions in BODY, but only if TEST evaluates to a
     true value.  If called without arguments, `#f' is returned, if
     only called with a TEST argument, the value of the TEST is
     returned, otherwise the value of the last expression in BODY is
     returned.

     This macro is not supported when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.

 - Macro: unless test body ...
     Evaluates all expressions in BODY, but only if TEST evaluates to
     `#f'.  If called without arguments, `#f' is returned, if only
     called with a TEST argument, the value of the TEST is returned,
     otherwise the value of the last expression in BODY is returned.

     This macro is not supported when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.

 - Macro: false-if-exception expr
     Evaluates EXPR and returns the result.  If an exception occurs
     while evaluating EXPR, it is caught and `#f' is returned.

     This macro is not supported when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.

 - Macro: while test body ...
     Evaluates the BODY expressions as long as TEST evaluates to a true
     value.  TEST is always evaluated before the BODY expressions.
     Returns `#f' if no call to `break' occurs inside of BODY,
     otherwise the value given to `break' is returned.

     This macro is not supported when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.

 - Library procedure: break val
     This is not a syntactic form, but is closely related to `while', so
     it was put in this section.  `break' is only defined inside of a
     `while' body.  When called, it aborts the innermost `while' loop
     and lets it return VAL.

     This macro is not supported when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.

 - Library procedure: continue
     Like `break', this is not a syntactic form, but is closely related
     to `while', so it was put in this section.  `continue' is only
     defined inside of a `while' body.  When called, it restarts the
     innermost while loop, starting with the test of the while
     condition.

     This macro is not supported when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.


File: sizzle-ref.info,  Node: Sizzle vs R5RS,  Next: Glossary,  Prev: Builtin Procedures,  Up: Top

Sizzle vs. R5RS
***************

   Sizzle is not a complete implementation of Scheme as defined in the
Revised 5 Report on the Algorithmic Language Scheme (R5RS), but most of
the standard procedures from that report and all data types except
complex and rational numbers are supported.  This chapter lists all
differences between Sizzle and standard Scheme.

   First of all, Sizzle does only support non-hygienic macros at all,
and the high-level syntax definitions from R5RS are implemented a
little bit shaky.  `call-with-current-continuation' only works in upward
direction properly, general continuations can be compiled in, but are
buggy and will segfault in the current state.  Besides of that, Sizzle
is a quite useful language for embedding and higher-order functional
programming purposes.

* Menu:

* Standard Data Types::         Scheme's data types
* Standard Procedures::         Standard procedures and special forms


File: sizzle-ref.info,  Node: Standard Data Types,  Next: Standard Procedures,  Prev: Sizzle vs R5RS,  Up: Sizzle vs R5RS

Standard Data Types
===================

The following data types are implementd in Sizzle, including most
standard procedures for manipulating objects of these types.

WHOLE NUMBERS

REAL NUMBERS

LISTS

VECTORS

STRINGS

CHARACTERS

BOOLEAN VALUES
The numerical tower is not fully implemented, not available are the
number types:
RATIONAL NUMBERS

COMPLEX NUMBERS

File: sizzle-ref.info,  Node: Standard Procedures,  Prev: Standard Data Types,  Up: Sizzle vs R5RS

Standard Procedures
===================

   These are the standard procedures defined in Sizzle.

* Menu:

* Supported Syntax::            Syntactic forms implemented in Sizzle.
* Supported Procedures::        Procedures implemented in Sizzle.
* Partly implemented::          Procedure only partly supported.
* Not supported::               All standard procedures not supported.


File: sizzle-ref.info,  Node: Supported Syntax,  Next: Supported Procedures,  Prev: Standard Procedures,  Up: Standard Procedures

Supported Syntax
----------------

   quote, quasiquote, unquote, unquote-splicing, lambda, if, cond, case,
set!, and, or, do, let, let*, letrec, begin, define


File: sizzle-ref.info,  Node: Supported Procedures,  Next: Partly implemented,  Prev: Supported Syntax,  Up: Standard Procedures

Supported Procedures
--------------------

   eqv?, eq?, equal?, number?, complex?, real?, rational?, integer?,
exact?, inexact?, zero?, positive?, negative?, odd?, even?, max, min, +,
*, -, /, abs, quotient, remainder, modulo, floor, ceiling, truncate,
round, exp, log, sin, cos, tan, asin, acos, atan, atan, sqrt, expt,
exact->inexact, inexact->exact, number->string, number->string,
string->number, string->number, gcd, lcm, not, boolean?, pair?, cons,
car, cdr, set-car!, set-cdr!, caar, cadr, ..., cdddar, cddddr, null?,
list?, list, length, append, reverse, list-tail, list-ref, memq, memv,
member, assq, assv, assoc, symbol?, symbol->string, string->symbol,
char?, char=?, char<?, char>?, char<=?, char>=?, char-ci=?, char-ci<?,
char-ci>?, char-ci<=?, char-ci>=?, char-alphabetic?, char-numeric?,
char-whitespace?, char-upper-case?, char-lower-case?, char->integer,
integer->char, char-upcase char, char-downcase, string?, make-string,
make-string, string, string-length, string-ref, string-set!, string=?,
string<?, string>?, string<=?, string>=?, string-ci=?, string-ci<?,
string-ci>?, string-ci<=?, string-ci>=?, substring, string-append,
string->list, list->string, string-copy, string->fill!, vector?,
make-vector, make-vector, vector, vector-length, vector-ref,
vector-set!, vector->list, list->vector, vector-fill!, procedure?,
apply, map, for-each, eval, interaction-environment,
call-with-input-file, call-with-output-file, with-input-from-file,
with-output-to-file, input-port?, output-port?, current-input-port,
current-output-port, open-input-file, open-output-file,
close-input-port, close-output-port, read, read-char, peek-char,
write-char, eof-object?, write, display, newline, delay, force, values,
call-with-values, dynamic-wind, transcript-on, transcript-off,
null-environment, scheme-report-environment, char-ready?


File: sizzle-ref.info,  Node: Partly implemented,  Next: Not supported,  Prev: Supported Procedures,  Up: Standard Procedures

Partly implemented
------------------

LOAD
     Implemented in the startup file `init.scm', but Sizzle has a
     builtin primitive procedure `primitive-load', which works like
     `load' as defined in R5RS.  The Scheme procedure `load' in Sizzle
     searches all directories listed in the variable `%load-path' as
     well as the current directory if the given filename is not
     absolute.

REAL-PART IMAG-PART MAGNITUDE ANGLE
     These work for integers and reals only, because complex numbers
     are not supported.

DENOMINATOR NUMERATOR
     These work for integers only, because rational numbers are not
     supported.

CALL-WITH-CURRENT-CONTINUATION
     Only for escape procedures.


File: sizzle-ref.info,  Node: Not supported,  Prev: Partly implemented,  Up: Standard Procedures

Not supported
-------------

   let-syntax letrec-syntax syntax-rules define-syntax, rationalize,
make-rectangular, make-polar


File: sizzle-ref.info,  Node: Glossary,  Next: Index,  Prev: Sizzle vs R5RS,  Up: Top

Glossary
********

APPLICATION
     When a function gets called with actual arguments, we say that the
     function is applied to the arguments, or that it is an application
     of the function to the arguments.

BOOLEAN
     Data type. Boolean values can be either `#t' (true) or `#f'
     (false).

BOX
     Data type.  Can store another Scheme object and can be used to
     implement call-by-reference procedures.

CATCH
     Exceptions can be handled by catching them using the procedure
     `catch'.

CHARACTER
     Data type. Characters are used to construct strings and are
     written like this: `#\t'.

CONS CELL
     Heap cell with one arbitrary value in both car and cdr.

DOTTED PAIR
     A dotted pair is a pair of values, stored in the car and cdr
     fields of a cons cell.  The read syntax for dotted pairs looks
     like this: `(a . b)'.

ENVIRONMENT
     An environment is a mapping from symbols to values. A symbol that
     is evaluated in a particular environment has its value retrieved
     from the environment.

ERROR
     An error is signalled when an evaluation cannot be performed
     correctly.

EXCEPTION
     An excpeption is thrown when an evaluation cannot be performed
     correctly.  The difference between errors and exceptions is that
     exceptions can be handled using the `catch' form.

FIXNUM
     An integer value which can be stored in a tagged pointer. 29-bit
     two-complement value.

HEAP
     Memory area where all non-immediate values are allocated.

HEAP CELL
     Cell on the heap of 8 bytes size which holds either two values
     (cons cell) or a type tag and additional data (tagged cell).

INTEGER
     Data type. Numeric type which can hold exact integer values.

LIST
     Data type. A list is made out of chained cons cells.

LONG INT
     Integer that does not fix into a fixnum.  Value range is the same
     as a C int variable.

MULTIPLE VALUES
     Scheme supports returning multiple values from procedures.
     Multiple values are produced using the syntactic form VALUES.

POINTER
     Data type.  Used to wrap machine pointers.

PORT
     Object from which data can be read or to which data can be
     written. File ports or string ports for example.

REAL NUMBER
     A number with (possibly) infinite decimal places like pi or e.

REGEXP
     Short for regular expression.

STRING
     Data type. A string is a sequence of characters.

SYMBOL
     Data type. Symbols are values which can have a value attached.

SYNTACTIC FORM
     Element of the syntax which looks like a function call but acts
     differently.  The `if' or `lambda' forms are examples of syntactic
     forms.

TAGGED CELL
     16 byte heap cell with a type tag in its first word and a three
     data pointers to additional data in the other words.

THUNK
     A thunk is a procedure without arguments.

VECTOR
     Data type. Used to hold a fixed number of other values with
     constant access time.

