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

INFO-DIR-SECTION Sizzle Scheme Interpreter
START-INFO-DIR-ENTRY
* sizzle-embed: (sizzle-embed).     Embedding Sizzle
END-INFO-DIR-ENTRY

   This file documents embedding of 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-embed.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

   This document describes how to embed Sizzle into C programs.

   It applies to version 0.0.30 of Sizzle.

* Menu:

* Introduction::                Introduction to Sizzle
* Embedding Sizzle::            How to embed Sizzle into your C programs
* Embedding API::               API functions provided for embedding
* Memory Management::           How memory is managed in Sizzle
* Creating Data Types::         How to create new Scheme data types
* Creating Port Types::         How to create new Scheme port types
* Adding Primitives::           How to add procedures written in C
* sizzle-gen-if::               Description of the interface generator
* Index::                       Function and variable index


File: sizzle-embed.info,  Node: Introduction,  Next: Embedding Sizzle,  Prev: Top,  Up: Top

Introduction
************

   Sizzle is an interpreter for a programming language. It is designed
to be used as an embedded extension language and as a scripting language
for a wide variety of purposes.

   This manual documents how to master the embedding process needed to
make use of Sizzle's features in a C application.  For more information
on Sizzle, on Scheme programming and a reference of the variables and
procedures available in Sizzle see *Note Introduction: (sizzle-ref)Top.

   Chapter 2 deals with embedding, containing a tutorial which shows
how to use Sizzle to parse the initialization file for a little example
program.

   In Chapter 3, the C API for embedding is documented.

   The following Chapter 4 deals with mechanisms and concepts for
extending the Sizzle interpreter for special purposes by adding data
types and primitive procedures.


File: sizzle-embed.info,  Node: Embedding Sizzle,  Next: Embedding API,  Prev: Introduction,  Up: Top

Embedding Sizzle
****************

   The Sizzle interpreter is implemented in the library `libsizzle'.
This library is installed when Sizzle is installed and actually is used
by the Sizzle interpreter `sizzle' for all its work.  `libsizzle' can
be embedded in other programs very easily, and this chapter will show
how to do it.

* Menu:

* Compiling and Linking::         How to compile against libsizzle
* Parsing initialization files::  Using Sizzle for parsing init files


File: sizzle-embed.info,  Node: Compiling and Linking,  Next: Parsing initialization files,  Prev: Embedding Sizzle,  Up: Embedding Sizzle

Compiling and Linking
=====================

   When compiling against the Sizzle library, you have to tell the
compiler where to find the Sizzle include files, and the linker, where
to find the library itself.  When you installed Sizzle in the standard
location (with `$prefix' set to `/usr/local/lib'), the files are likely
to be found, but embedding Sizzle should be possible when installed in
another location too.  That is the reason the script `sizzle-config'
was included in the distribution.  This script gets installed in the
same location as the `sizzle' interpreter, and can be used to obtain
information about the Sizzle installation.

   `sizzle-config' understands three commands, which must be given on
the command line.  Either command causes the script to print out a line
of options, suitable for inclusion in the compiler or linker command.

`compile'
     Print the `-I' compiler option for finding the include files.

`link'
     Print the options for linking against the Sizzle library (for
     example, `-L/usr/local/lib -R/usr/local/lib -lsizzle -lm -ldl')

`static-link'
     Print the options for linking statically against the Sizzle
     library (for example, `/usr/local/lib/libsizzle.a -lm -ldl')


File: sizzle-embed.info,  Node: Parsing initialization files,  Prev: Compiling and Linking,  Up: Embedding Sizzle

Parsing Initialization files
============================

   One design goal for Sizzle was to make it easy to use the interpreter
for parsing initialization files.  Using a complete programming language
for init files has the advantage that a lot intelligence for setting up
a program can be put into these init files.  One popular example is the
Emacs editor.  This chapter will explain in tutorial style which steps
are necessary to use Sizzle for this purpose.

   The four steps in the following sub-section describe in detail what
to do if you want to include Sizzle into your application for the
purpose of parsing init files.  In the `examples' directory of the
source distribution of Sizzle are included the files `example.c' and
`startup.scm', which illustrate the following steps.

* Menu:

* Initializing the library::    How to initialize libsizzle
* Declaring variables::         Makeing C variables accessible to Scheme
* Loading the init file::       Load a file of Scheme code
* Shutting down the library::   Free all memory used by the library


File: sizzle-embed.info,  Node: Initializing the library,  Next: Declaring variables,  Prev: Parsing initialization files,  Up: Parsing initialization files

Initializing the library
------------------------

   Before you can use the `libsizzle' library, you have to initialize
it.  Two steps are necessary to do that.  First, you have to tell it the
address of the top of the C stack.  This is done by declaring a local
dummy variable and passing its address to the function
`zzz_set_top_of_stack()'.

     int
     main (int argc, char * argv[])
     {
       zzz_scm_t dummy;
     
       /* Announce top of stack to Sizzle library, so conservative marking
          works.  */
       zzz_set_top_of_stack (&dummy);

Then the library initialization is performed by a call to
`zzz_initialize()'.
       /* Initialize the library.  */
       zzz_initialize ();

The last step is not mandatory, but very useful.  You can pass the
command line options given to your program to the interpreter to make it
available to your Scheme code.
       /* Make command line options available to Scheme code.  The zero'th
          argument is handled specially to make pre-processing of the
          arguments easier (see src/sizzle.c for details).  */
       zzz_set_arguments (argc - 1, argv[0], argv + 1);


File: sizzle-embed.info,  Node: Declaring variables,  Next: Loading the init file,  Prev: Initializing the library,  Up: Parsing initialization files

Declaring variables
-------------------

   When the library is correctly initialized, you can bind variables in
your C code to Scheme variables.  Thus you can directly modify variables
in your C program from Scheme code.

   Three different data types are currently supported: integers, strings
and boolean values.  Whenever you bind the address of a C variable to a
Scheme variable you have to tell the interpreter of which data type the
variable is.  The interpreter will then type-check assignments and
signal errors whenever a value of a wrong type is stored into a
variable.  Additionaly, it is considered an error to store a string
which is too long into a string variable.

   The example program declares five variables of different types.
       /* Bind some variables of different types.  The last argument is a
          flag whether the variable is allowed to get changed by Scheme
          code.  */
       zzz_bind_int_variable ("binary-port", &binary_port, 0);
       zzz_bind_int_variable ("command-port", &command_port, 0);
       zzz_bind_bool_variable ("verbose", &verbose, 0);
       zzz_bind_string_variable ("hostname", hostname, sizeof (hostname), 0);
       zzz_bind_string_variable ("download-area", download_area,
                                 sizeof (download_area), 0);
       zzz_bind_scm_variable ("kill-lines", &kill_lines, 0);

The first argument in each of these calls is the name which will be
given to the Scheme variable, the second argument is the address of the
C variable and the last is a flag whether the variable should be
read-only on the Scheme level.  When declaring string variables, you
have to pass the maximal length of the variable also, so range-checking
can be performed.


File: sizzle-embed.info,  Node: Loading the init file,  Next: Shutting down the library,  Prev: Declaring variables,  Up: Parsing initialization files

Loading the init file
---------------------

   A call to the function `zzz_evaluate_file()' finally loads the init
file, which may contain any valid Scheme code.  The Scheme code has
access to all variables defined above.  For details about the init file,
see the file `startup.scm' in the `examples' directory.
       /* Evaluate startup file.  */
       if ((return_val = zzz_evaluate_file (zzz_toplevel_env, "startup.scm")) != 0)
         fprintf (stderr, "example: error while reading init file\n");

The return value of `zzz_evaluate_file()' is zero when all went right
and a non-zero value otherwise.

   The variable `kill-lines' was bound to a generic variable of type
`zzz_scm_t'. That means that any Scheme value can be stored in the
variable and that no type checking is performed as for the other
variables which have explicitly been bound to variable of type int,
boolean or string.  When using such variables, you must be careful when
interpreting the values stored there.  The following example shows how
to safely handle a variable which was supposed to hold a list of
strings.
       /* Interpretation of bound variables of type zzz_scm_t must be done
          before the library is finalized, otherwise dangling pointers will
          make your life hard.  */
     
       /* Iterate over list.  */
       while (cons_p (kill_lines))
         {
           /* Make sure we are dealing with strings.  */
           if (string_p (car (kill_lines)))
             {
               printf ("Kill line: %s\n", string_val (car (kill_lines)));
             }
           kill_lines = cdr (kill_lines);
         }


File: sizzle-embed.info,  Node: Shutting down the library,  Prev: Loading the init file,  Up: Parsing initialization files

Shutting down the library
-------------------------

   After parsing the init file, you will normally want to free all
memory used by the interpreter.  This is done by a call to
`zzz_finalize()'.
       /* Free all memory used by the interpreter.  */
       zzz_finalize ();

Note that all Scheme values, even those which might be stored into C
variables using `zzz_bind_scm_variable()', are no longer valid when you
have shut down the interpreter.

   That's it!  Not to hard, methinks.


File: sizzle-embed.info,  Node: Embedding API,  Next: Memory Management,  Prev: Embedding Sizzle,  Up: Top

Embedding API
*************

   This section documents the C API for embedding Sizzle into C
applications.

   The calling conventions of most API functions follow the same
concept.  The return value of those functions is an error code, values
computed by the functions are normally returned in reference
parameters.  This is a little bit unconvenient when calling these
functions, because a lot of temporary variables for holding the
intermediate results must be declared, but provides a very powerful
interface for error handling, since not only the fact that an error
occured can be signalled, but also additional information about the
error condition can be returned in the result variable.

   That is the reason why those return codes and parameters are also
used for implementing exceptions.  Whenever a call to an API function
does not return `RESULT_SUCCESS', the error is immediately propagated up
the call chain.  So not only errors are passed up, but also exceptions.
The exception objects passed up together with the exception code can be
examined and particular exceptions can be caught using this technique.

* Menu:

* Initializing and Finalization::  Functions for starting up and shutting down.
* Scheme Variable Handling::    Creating and accessing Scheme variables.
* Hash table handling::         Accessing Scheme hash tables from C.
* C Variable Handling::         Binding C variables to Scheme names.
* Evaluation Functions::        Evaluate strings and files.
* Object constructors::         How to create Scheme objects.
* Type predicates::             Macros for determining the type of an object.
* Accessor functions::          Accessing properties of objects.
* Port Functions::              Using Scheme ports from C code.
* Defining Scheme Types::       API functions for defining new types.
* Misc C API Functions::        Leftovers in the C API.


File: sizzle-embed.info,  Node: Initializing and Finalization,  Next: Scheme Variable Handling,  Prev: Embedding API,  Up: Embedding API

Initializing and Finalization
=============================

   When using the Sizzle library, you habe the choice of using one of
two methods.  *Note Parsing initialization files::, where the first is
shown in detail. It consists of calling the functions
`zzz_set_top_of_stack()', `zzz_initialize()' and `zzz_finalize()'; the
other method is used by the Sizzle interpreter `sizzle' and uses only
the call `zzz_run()'.  The former is more easily to incorporate into
existing programs whereas the latter is much simpler and less
error-prone.

 - Function: void zzz_set_top_of_stack (zzz_scm_t * CELL)
     Tell the Sizzle library that the pointer CELL points to a location
     on the C stack which marks the end of the stack as far as
     conservative garbage collection is concerned.  Use this function
     before any other call to the Sizzle library, or use the
     `zzz_run()' function.

 - Function: void zzz_initialize (void)
     Initialize the library.

 - Function: void zzz_finalize (void)
     Shut down the library and free all memory allocated by the
     interpreter.

 - Function: void zzz_set_arguments (int ARGC, char * ARGV0, char *
          ARGV[])
     Set the command line arguments which will be visible to running
     Scheme code.  ARGC is the count of elements in the vector ARGV,
     ARGV0 is the program name and ARGV is a vector of the remaining
     command line arguments.

 - Function: int zzz_run (int (* MAIN)(int argc, char * argv[]), int
          ARGC, char * ARGV[])
     Intitialize the Sizzle library and call the function MAIN, passing
     ARGC and ARGV as arguments.  This is the recommended function for
     using the Sizzle library and is used by the `sizzle' program
     itself.  Returns the exit code of MAIN.  You should not call any
     function from `libsizzle' before calling this function and you
     should not call any after calling it.  `zzz_run()' does all
     necessary initialization and finalization.


File: sizzle-embed.info,  Node: Scheme Variable Handling,  Next: Hash table handling,  Prev: Initializing and Finalization,  Up: Embedding API

Scheme Variable Handling
========================

   The function in this section all modify objects in the Scheme name
space.  They either create or modify Scheme variables, constants or
functions, but they can also be used to query those objects.

   All functions below create their bindings in the outermost scope,
even below the toplevel environments.  The bindings are thus equivalent
in scope to the builtin variables and procedures (in fact, builtin
bindings are created using these functions).

 - Function: result_t zzz_get_variable (zzz_scm_t SYM, zzz_scm_t *
          RESULT)
     Return the value of the variable SYM in the global environment.
     Returned is the value in the location pointed to by RESULT and
     `RESULT_SUCCESS' if no error occurs, otherwise an error code is
     returned and an error object is stored in the location pointed to
     by RESULT.

 - Function: result_t zzz_set_variable (zzz_scm_t SYM, zzz_scm_t value,
          zzz_scm_t * RESULT)
     Set the variable SYM in the global environment to the value VALUE.
     `RESULT_SUCCESS' is returned if no error occurs, otherwise an
     error code is returned and an error object is stored in the
     location pointed to by RESULT.

 - Function: zzz_scm_t zzz_define_variable (char * NAME, zzz_scm_t
          VALUE)
     Define the variable NAME, which will be bound in the toplevel
     environment to VALUE.  Returns the symbol created for the variable.

 - Function: zzz_scm_t zzz_define_constant (char * NAME, zzz_scm_t
          VALUE)
     Define the read-only variable NAME, which will be bound in the
     toplevel environment to VALUE.  Returns the symbol created for the
     variable.  The difference between `zzz_define_constant()' and
     `zzz_define_variable()' is that the variables defined with the
     former can not be modified by `set!' operations.  Also, variables
     defined using `zzz_define_constant()' are more efficient because
     references to these constant variables are replaced by their values
     during runtime.

 - Function: zzz_scm_t zzz_define_function (char * NAME, result_t (*
          FUNC)(), int PARAM_FORMAT)
     Define a function called NAME which refers to the builtin function
     FUNC and takes parameters as specified by PARAM_FORMAT.

 - Function: zzz_scm_t zzz_define_form (char * NAME, zzz_prim_t FUNC,
          int preprocessing)
     Define the special form NAME, which will be calling the C function
     FUNC.  Returns the symbol created for the function.  Note that
     when functions for handling special forms are called, they are
     passed the entire form, including the special form name as the
     first element of the parameter list.  If PREPROCESSING is true,
     the function FUNC will not evaluate the form, but only error check
     and replace it with an immediate form for faster execution.


File: sizzle-embed.info,  Node: Hash table handling,  Next: C Variable Handling,  Prev: Scheme Variable Handling,  Up: Embedding API

Hash table handling
===================

   Hash tables are represented as vectors which hold association lists.
When storing a key/value pair, or looking up the value for a given pair,
a hash value is calculated for the key and used as an index into the
vector.  Then the association list found at the index is scanned for the
key.

 - Function: unsigned long zzz_hash_function (zzz_scm_t OBJECT)
     Return a hash value for the Scheme object OBJECT.

 - Function: zzz_scm_t zzz_hashq_ref (zzz_scm_t TAB, zzz_scm_t KEY,
          zzz_scm_t DEF)
 - Function: zzz_scm_t zzz_hashv_ref (zzz_scm_t TAB, zzz_scm_t KEY,
          zzz_scm_t DEF)
 - Function: zzz_scm_t zzz_hash_ref (zzz_scm_t TAB, zzz_scm_t KEY,
          zzz_scm_t DEF)
     Fetch the element associated with KEY from the hash table TAB.  If
     an error occurs or the KEY is not found, DEF is returned.
     `zzz_hashq_ref' uses `eq?' as the equality predicate for searching
     for KEY, `zzz_hashv_ref' uses `eqv?' and `zzz_hash_ref' uses
     EQUAL?.

 - Function: zzz_scm_t zzz_hashq_set (zzz_scm_t TAB, zzz_scm_t KEY,
          zzz_scm_t VALUE)
 - Function: zzz_scm_t zzz_hashv_set (zzz_scm_t TAB, zzz_scm_t KEY,
          zzz_scm_t VALUE)
 - Function: zzz_scm_t zzz_hash_set (zzz_scm_t TAB, zzz_scm_t KEY,
          zzz_scm_t VALUE)
     Add the association KEY => VALUE to the hash table TAB.  If an
     association with KEY already exists, it is overwritten with VALUE.
     If an error occurs or the KEY is not found, NULL is returned, if
     everything went right, VALUE is returned.  `zzz_hashq_ref' uses
     `eq?' as the equality predicate for searching for KEY,
     `zzz_hashv_ref' uses `eqv?' and `zzz_hash_ref' uses EQUAL?.


File: sizzle-embed.info,  Node: C Variable Handling,  Next: Evaluation Functions,  Prev: Hash table handling,  Up: Embedding API

C Variable Handling
===================

   Another method for interfacing Scheme and C code is declare
variables in your C source and then bind the locations of these
variables to Scheme variable names.  The advantage is that you can then
reference the values stored into the variables by simply using the
variables like normal C variables.  Variables created with these
functions are totally transparent to the Scheme code, there is not even
a method how the Scheme code can find out whether a given variable is
bound to a C variable or not.

 - Function: result_t zzz_protect_global (zzz_scm_t * SCM)
     Protect the variable pointed to by SCM globally from being garbage
     collected.  You should call this functions whenever you create a
     variable of type `zzz_scm_t', but do not wish to bind that variable
     to a Scheme variable using `zzz_bind_scm_variable()'.  Returns
     `RESULT_SUCCESS' on success and an error code otherwise.

 - Function: void zzz_bind_int_variable (char * NAME, int * ADDRESS,
          int READ_ONLY)
     Create a toplevel Scheme variable named NAME of type integer which
     is bound to the C variable pointed to by ADDRESS.  The variable
     will be read-only if READ_ONLY is true.

 - Function: void zzz_bind_bool_variable (char * NAME, int * ADDRESS,
          int READ_ONLY)
     Create a toplevel Scheme variable named NAME of type boolean which
     is bound to the C variable pointed to by ADDRESS.  The variable
     will be read-only if READ_ONLY is true.

 - Function: void zzz_bind_string_variable (char * NAME, char *
          ADDRESS, int LEN, int READ_ONLY)
     Create a toplevel Scheme variable named NAME of type string which
     is bound to the C variable pointed to by ADDRESS.  The variable
     will be read-only if READ_ONLY is true.

 - Function: void zzz_bind_scm_variable (char * NAME, zzz_scm_t *
          ADDRESS, int READ_ONLY)
     Create a toplevel Scheme variable named NAME of type zzz_scm_t
     which is bound to the C variable pointed to by ADDRESS.  The
     variable will be read-only if READ_ONLY is true.  This functions
     automatically takes care of protecting the passed location from
     garbage collection, thus variables bound using this functions are
     safe.


File: sizzle-embed.info,  Node: Evaluation Functions,  Next: Object constructors,  Prev: C Variable Handling,  Up: Embedding API

Evaluation Functions
====================

   Use one of these functions if you like to evaluate Scheme code.  The
functions which take an "environment" as a parameter evaluate the given
expression, string or file in that environment, that means that all
bindings which may be created are effectively created in the given
environment.  You can pass the variable ZZZ_TOPLEVEL_ENV for the ENV
parameter to these functions if you do not have any special
requirements.

 - Function: int zzz_evaluate_file (zzz_scm_t ENV, const char *
          FILENAME)
     Evaluate all Scheme expressions from the file called FILENAME in
     the environment ENV.  Returns 0 if no error occurs, -1 if the file
     was not found, -2 if an error occured when evaluating the file or
     another exit code if the file contained a call to `exit'.  All
     expressions in the file are evaluated in the environment ENV.
     Evaluation is aborted as soon as an error is encountered or
     evaluation is aborted using `exit'.

 - Function: int zzz_evaluate_string (zzz_scm_t ENV, const char * STR)
     Evaluate all Scheme expressions from the string STR in the
     environment ENV.  Returns 0 if no error occurs, -2 if an
     evaluation error is encountered or another exit code if the string
     contained a call to `exit'.  All expressions in the string are
     evaluated in the environment ENV.  Evaluation is aborted as soon
     as an error is encountered or evaluation is aborted using `exit'.

 - Function: int zzz_read_eval_print (void)
     Execute Sizzle's read-eval-print loop.  Expressions will be read
     from standard input, evaluated and the results will be written to
     standard output.  Error messages will be sent to standard error.
     Returns 0 if terminated normally or another exitcode if the user
     enters the `exit' command with an exit code.

 - Function: result_t zzz_apply (zzz_scm_t ENV, zzz_scm_t PROC,
          zzz_scm_t PARAM_LIST, zzz_scm_t * RESULT)
     Apply the procedure PROC (which may be a primitive procedure or a
     closure) to the parameter list PARAM_LIST.  Evaluation takes place
     in the environment ENV.  The result is returned in the location
     pointed to by RESULT.  On success, `RESULT_SUCCESS' is returned,
     otherwise an error code and an error object is stored in RESULT.

 - Function: result_t zzz_evaluate (zzz_scm_t ENV, zzz_scm_t EXPR,
          zzz_scm_t * RESULT)
     Evaluate the Scheme expression EXPR in the environment ENV.  The
     result is returned in the location pointed to by RESULT.  On
     success, `RESULT_SUCCESS' is returned, otherwise an error code and
     an error object is stored in RESULT.


File: sizzle-embed.info,  Node: Object constructors,  Next: Type predicates,  Prev: Evaluation Functions,  Up: Embedding API

Object constructors
===================

   When creating Scheme values, the functions defined in this section
should be used.  They guarantee correct interfacing to the memory
management system and the garbage collector.

 - Function: zzz_scm_t zzz_cons (zzz_scm_t CAR, zzz_scm_t CDR)
     Creates a cons cell with car and cdr initialized to the values of
     CAR and CDR, respectively.

 - Function: zzz_scm_t zzz_make_list (zzz_scm_t FIRST, ...)
     Create a Scheme list of all parameters.  FIRST is the first element
     of the resulting list, followed by the optional parameters.  The
     parameter list must be terminated with a NULL pointer.

 - Function: zzz_scm_t zzz_make_n_list (int N, zzz_scm_t FIRST, ...)
     Create a Scheme list of exactly N parameters.  FIRST is the first
     element of the resulting list, followed by the optional parameters.

 - Function: zzz_scm_t zzz_make_fixnum (long NUMBER)
     Create a fixnum object with integer value NUMBER.  If NUMBER does
     not fit into the range of fixnums, its high bits are silently
     truncated.  The fixnum range is between -268435456 and 268435455,
     inclusive.

     You should not use this function unless you are sure that the given
     value fits into a fixnum.  Use `zzz_make_integer()' instead.

 - Function: zzz_scm_t zzz_make_integer (long VALUE)
     Create an integer object with value VALUE.  A fixnum is returned
     if VALUE fits into the range defined for fixnums, otherwise a long
     object is returned which holds all 32 bits of information from
     VALUE.

 - Function: zzz_scm_t zzz_make_string (const char * S, int LEN)
     Create a string of length LEN and initialize with the data pointed
     to by S.  If LEN is less than zero, S is considered a
     null-terminated string and the length is calculated by using
     `strlen()'.

 - Function: zzz_scm_t zzz_make_nstring (int LEN)
     Create a string of length LEN.  The contents of the returned
     string is unspecified.

 - Function: zzz_scm_t zzz_make_ro_string (const char * S, int LEN)
     Create a constant string of length LEN and initialize with the
     data pointed to by S.  If LEN is less than zero, S is considered a
     null-terminated string and the length is calculated by using
     `strlen()'.  The returned string is read-only and cannot be
     modified with Scheme primitives like `string-set!'.

 - Function: zzz_scm_t zzz_make_ro_nstring (int LEN)
     Create a constant string of length LEN.  The contents of the
     returned string is unspecified.  The returned string is read-only
     and cannot be modified with Scheme primitives like `string-set!'.

 - Function: zzz_scm_t zzz_make_bool (long B)
     Create a boolean object.  If B is zero, the false Scheme object
     `#f' is returned, otherwise the canonic true Scheme object `#t' is
     returned.

 - Function: zzz_scm_t zzz_make_char (long B)
     Create a character object with character value B.  Only the lower
     8 bits of B are actually used.

 - Function: zzz_scm_t zzz_make_float (double D)
     Create a real number object initialized with the value of D.

 - Function: zzz_scm_t zzz_make_symbol (const char * S, int LEN)
     Create a Scheme symbol with the string representation S of length
     LEN.  If LEN is less than zero, `strlen()' is used to determine
     the string length.  This function will return the same object for
     all strings with the same length and the same character contents.

 - Function: zzz_scm_t zzz_make_func (zzz_prim_t FUNC, const char *
          NAME, int FORM, int PARAM_FORMAT)
     Create a primitive function object.  FUNC is the address of the C
     function that handles the primitive function, NAME is the Scheme
     name under which the function will be available, FORM should be 0
     for primitive functions and non-zero of syntactic forms and
     PARAM_FORMAT is a description of the parameter format the function
     expects.  Use one of the `TAGGED_INFO_ARG_*_*_*' constants for this
     parameters.

 - Function: zzz_scm_t zzz_make_lambda (zzz_scm_t EXPR)
     Create a lambda object.  EXPR must be a list where the car is the
     formal parameter list and the cdr must be the procedure body.

 - Function: zzz_scm_t zzz_make_closure (zzz_scm_t PROC, zzz_scm_t ENV)
     Create a closure object which closes the procedure PROC under the
     environment ENV.

 - Function: zzz_scm_t zzz_make_error (zzz_scm_t MSG, zzz_scm_t
          REFERENCE)
     Create an error object.  MSG is the error message, REFERENCE is a
     list containing the file name, line number and column number where
     the error occurred; or NULL if that information is not available.

 - Function: zzz_scm_t zzz_make_exception (zzz_scm_t EXCEPTION,
          zzz_scm_t MSG)
     Create an exception object. EXCEPTION is the exception tag (any
     atom) and MSG is the exception message which may hold additional
     information about the exception.

 - Function: zzz_scm_t zzz_make_environment (unsigned SIZE, zzz_scm_t
          STATIC_LINK, int FINAL, int READ_ONLY)
     Create an environment object.  STATIC_LINK is the link to the
     including lexical environment in which variable binding will be
     searched.  SIZE denotes the size the hash table for the new
     environment will have; it should be a prime number.

     When FINAL is true, variable lookups will not descend the static
     chain further than to the created environment.

     When READ_ONLY is true, variables defined in environments further
     down the static link can only be read, but not modified.

 - Function: zzz_scm_t zzz_make_location (zzz_scm_t * LOCATION, int
          READ_ONLY)
     Create a location object.  A location object is an indirect object
     which refers to a Scheme object variable address.  LOCATION points
     to the location to redirect to and READ_ONLY specified whether this
     location may be written to.

 - Function: zzz_scm_t zzz_make_lloc (zzz_scm_t SYMBOL, int ENV_OFS,
          unsigned HASH_VAL)
     Create a lloc object.  A lloc object is substituted for all local
     variables which have been looked up once and which are not special
     variables.  They are used to cache the location of variables and to
     speed up references to local variables.  SYMBOL is the variable
     name this lloc stands for, ENV_OFS is the number of environments
     to traverse down the static link and HASH_VAL is the hash index
     into the environment where we have to search for SYMBOL.

 - Function: zzz_scm_t zzz_make_gloc (zzz_scm_t NAME, zzz_scm_t *
          ADDRESS)
     Create a gloc object.  A gloc is similar to a lloc, but only
     applies to global variables not in an environment, but in the
     symbol table.  NAME is the variable name this gloc stands for, and
     ADDRESS is the location where the value of the variable can be
     found.

 - Function: zzz_scm_t zzz_make_constant (zzz_scm_t VALUE)
     Create a constant object with value VALUE.  A constant object is
     special, since it value may be substituted whenever it is
     referenced, and therefore references are faster than variable
     references.  Also variables containing constant objects can not be
     modified.

 - Function: zzz_scm_t zzz_make_keyword (const char * S, int LEN)
     Create a Scheme keyword object with the string representation S of
     length LEN.  If LEN is less than zero, `strlen()' is used to
     determine the string length.  This function will return the same
     object for all strings with the same length and the same character
     contents.

 - Function: zzz_scm_t zzz_make_vector (int LEN)
     Create a vector object which holds LEN elements.  The vector
     elements are initialized to the empty list `'()'.

 - Function: zzz_scm_t zzz_make_ro_vector (int LEN)
     Create a constant vector object which holds LEN elements.  The
     vector elements are initialized to the empty list `'()'.  The
     returned vector is read-only and can not be modified using Scheme
     primitives like `vector-set!'.

 - Function: zzz_scm_t zzz_make_continuation (void)
     Make a continuation object.  Note that the returned object is not
     initialized, you have to capture the current continuation
     explicitly using `zzz_capture_continuation()'.

 - Function: zzz_scm_t zzz_create_tagged_cell (unsigned long TAG, const
          void * DATA0, const void * DATA1, const void * DATA2);
     This is the generic object creation function for tagged types.
     You have to pass a type tag (maybe combined with one or more of the
     `type_info_*' constants) in TAG, and additional information in the
     parameters DATA0, DATA1 and DATA2.  The format of the data
     parameters depends on what the internal constructor function for
     the tagged type expects.

 - Function: zzz_scm_t zzz_make_values (zzz_scm_t VALUES)
     Creates a multiple value object with the values in the list VALUES.

 - Function: zzz_scm_t zzz_make_regexp (const char * STR, int LEN, int
          FLAGS)
     Creates a regular expression object which matches the string STR
     of length LEN.  FLAGS are used for compiling the regular
     expression and may be any of the compile time flags specified for
     Posix regular expressions.

 - Function: zzz_scm_t zzz_make_promise (zzz_scm_t ENV, zzz_scm_t
          EXPRESSION)
     Creates a promise object.  The new object is closed over the
     environment ENV, that means that the promise will be evaluated in
     that environment once it is forced.  EXPR is the expression to be
     delayed.

 - Function: zzz_scm_t zzz_make_macro (zzz_scm_t CODE)
     Creates a macro object with macro code CODE.  The car of CODE must
     be the formal parameter list, the cdr must be the macro body.

 - Function: zzz_scm_t zzz_make_syntax (zzz_scm_t RULES)
     Creates a syantx object with syntax rules RULES.  The rules must
     have the same syntax as provided to a call to the Scheme form
     `syntax-rules'.  body.

 - Function: zzz_scm_t zzz_make_fport (FILE * FILE, int READ, int WRITE)
     Creates a standard IO port for the file referenced by FILE.  READ
     and WRITE tell the input-output mode of the resulting port object.

 - Function: zzz_scm_t zzz_make_fdport (int FD, int READ, int WRITE)
     Creates a file descriptor port for the file descriptor FD.  READ
     and WRITE tell the input-output mode of the resulting port object.

 - Function: zzz_scm_t zzz_make_sport (int START_LEN)
     Creates a string port with a preallocated character buffer of size
     START_LEN.

 - Function: zzz_scm_t zzz_make_sport_str (const char * STR)
     Creates a string port with the initial contents of the
     null-terminated string STR.  The file pointer is initially set to
     zero.

 - Function: zzz_scm_t zzz_make_sport_str_n (const char * STR, unsigned
          LEN)
     Creates a string port with the initial contents of the string STR
     with length LEN.  The file pointer is initially set to zero.

 - Function: zzz_scm_t zzz_make_sport_str_n_no_copy (char * STR,
          unsigned LEN)
     Creates a string port with the initial contents of the string STR
     with length LEN.  The file pointer is initially set to zero.  This
     function does not create a copy of the passed string, so you have
     to make sure that the contents remains valid as long as the string
     port does exists.  Use it for cnstant strings etc.

 - Function: zzz_scm_t zzz_make_TAGvector (int LEN)
     Create a homogenous numeric vector object which holds LEN
     elements.  The vector elements are initialized to zero.

     TAG in the constructor name may be replaced by `s8', `u8', `s16',
     `u16', `s32', `u32', `s64', `u64', `f32' or `f64', depending on
     the needed datatype.  So there are actually ten of these
     constructor functions.

 - Function: zzz_scm_t zzz_make_ro_TAGvector (int LEN)
     Create a constant homogenous numeric vector object which holds LEN
     elements.  The vector elements are initialized to zero.  The
     returned vector is read-only and can not be modified using Scheme
     primitives like `TAGvector-set!'.

     TAG in the constructor name may be replaced by `s8', `u8', `s16',
     `u16', `s32', `u32', `s64', `u64', `f32' or `f64', depending on
     the needed datatype.  So there are actually ten of these
     constructor functions.

 - Function: zzz_scm_t zzz_make_pointer (void * ADDRESS)
     Create a pointer object which referencing ADDRESS.

 - Function: zzz_scm_t zzz_make_pointer_n (void * ADDRESS, unsigned N)
     Create a pointer object which referencing a memory area starting at
     ADDRESS and being N bytes long.

 - Function: zzz_scm_t zzz_copy_list (zzz_scm_t LIST)
     Make a copy of the list LIST.  Note that LIST must be a proper
     list.  This function only copies the spine of the list, that
     means, that the list elements are shared, and only the cons cells
     construcing the list are newly allocated.  If you need to make a
     deep copy of a list, use `zzz_copy_tree()' instead.

 - Function: zzz_scm_t zzz_copy_tree (zzz_scm_t TREE)
     Make a deep copy of the object TREE.  That means, that vectors and
     pairs are cloned recursively and all other objects are simply
     copied to the returned object.

 - Function: zzz_scm_t zzz_make_not_available_exception (zzz_scm_t ARGS)
     Create an exception object with the tag `not-available', and the
     additional exception data ARGS.  This exception is thrown whenever
     a primitive is called which is not supported under the currently
     running version of Sizzle.

 - Function: zzz_scm_t zzz_make_port (unsigned PORT_TYPE, void * INFO)
     Create a port of the specified port type and install INFO as the
     port's info field.


File: sizzle-embed.info,  Node: Type predicates,  Next: Accessor functions,  Prev: Object constructors,  Up: Embedding API

Type predicates
===============

   These type predicates are safe in the sense that you do not risk a
segmentation fault when applying any of them to an arbitraty value of
type `zzz_scm_t'.  They simply return 0 if the condition they test for
is not satisfied.  Use them before using any of the accessor functions
(*note Accessor functions::).

   Note that the return values of these predicates are boolean values in
the C sense: zero means false and any other value means true.

 - Macro: null_p (C)
     `null_p(c)' returns a true value if C is the empty list.

 - Macro: fixnum_p (C)
     `fixnum_p(c)' returns a true value if C is a fixnum object.

 - Macro: imm_p (C)
     `imm_p(c)' returns a true value if C is an immediate value,
     Immediate values are all values which are encoded into a pointer
     of type `zzz_scm_t', and which do not occupy any cells on the
     heap.  The empty list, all fixnum values and immediate form
     objects are immediate values.

 - Macro: immediate_p (C)
     `immediate_p(c)' returns a true value if C is an immediate form.
     Immediate forms are substituted for form applications to speed up
     the evaluation of expressions.

 - Macro: cons_p (C)
     `cons_p(c)' returns a true value if C is a cons pair.

 - Macro: list_p (C)
     Returns a true value if C is a list.  A list is either a cons pair
     or the empty list.

 - Macro: integer_p (C)
     `integer_p(c)' returns a true value if C is an integer object.
     Both fixnum and long objects are integer objects.

 - Macro: procedure_p (C)
     `procedure_p(c)' returns a true value if C is a procedure object.
     Procedure objects are primitive procedures, syntax forms and
     lambda expressions.

 - Macro: number_p (C)
     `number_p(c)' returns a true value if C is a number object.
     Fixnum, long and real objects are numbers.

 - Macro: tagged_p (C)
     `tagged_p(c)' returns a true value if C is a tagged object. This
     macro is true for all values which are neither immediate in the
     sense of `immediate_p()' nor cons cells in the sense of `cons_p()'.

 - Macro: string_p (C)
     `string_p(c)' returns returns a true value if C is a string object.

 - Macro: rostring_p (C)
     `rostring_p' returns returns a true value if C is a constant string
     object.

 - Macro: bool_p (C)
     `bool_p(c)' returns a true value if C is a boolean object.

 - Macro: char_p (C)
     `char_p(c)' returns a true value if C is a character object.

 - Macro: float_p (C)
     `float_p(c)' returns a true value if C is a real number object.

 - Macro: symbol_p (C)
     `symbol_p(c)' returns a true value if C is a symbol.

 - Macro: func_p (C)
     `func_p(c)' returns a true value if C is a primitive procedure.

 - Macro: form_p (C)
     `form_p(c)' returns a true value if C is a syntactic form.

 - Macro: lambda_p (C)
     `lambda_p(c)' returns a true value if C is a lambda closure.

 - Macro: error_p (C)
     `error_p(c)' returns true if C is an error object.

 - Macro: except_p (C)
     `except_p(c)' returns true if C is an exception object.

 - Macro: long_p (C)
     `long_p(c)' returns true if C is a long integer object.

 - Macro: env_p (C)
     `env_p(c)' returns true if C is an environment.

 - Macro: location_p (C)
     `location_p(c)' returns true if C is a location object.

 - Macro: rolocation_p (C)
     `rolocation_p(c)' returns true if C is a constant location object.

 - Macro: lloc_p (C)
     `lloc_p(c)' returns true if C is an lloc object.

 - Macro: gloc_p (C)
     `gloc_p(c)' returns true if C is a gloc object.

 - Macro: constant_p (C)
     `constant_p(c)' returns true if C is a constant value object.

 - Macro: keyword_p (C)
     `keyword_p(c)' returns true if C is a keyword.

 - Macro: vector_p (C)
     `vector_p(c)' returns a true value if C is a vector object.

 - Macro: rovector_p (C)
     `rovector_p(c)' returns a true value if C is a constant vector
     object.

 - Macro: values_p (C)
     `values_p(c)' returns true if C is a multiple value object.

 - Macro: int_var_p (C)
 - Macro: ro_int_var_p (C)
     `int_var_p(c)' returns true if C is an integer variable wrapper
     object, `ro_int_var_p(c)' returns true if C is a read-only integer
     variable wrapper object.

 - Macro: bool_var_p (C)
 - Macro: ro_bool_var_p (C)
     `bool_var_p(c)' returns true if C is a boolean variable wrapper
     object, `ro_bool_var_p(c)' returns true if C is a read-only
     boolean variable wrapper object.

 - Macro: str_var_p (C)
 - Macro: ro_str_var_p (C)
     `str_var_p(c)' returns true if C is a string variable wrapper
     object, `ro_str_var_p(c)' returns true if C is a read-only string
     variable wrapper object.

 - Macro: regexp_p (C)
     `regexp_p(c)' returns true if C is a regular expression object.

 - Macro: promise_p (C)
     `promise_p(c)' returns true if C is a promise object.

 - Macro: macro_p (C)
     `macro_p(c)' returns true if C is a macro code object.

 - Macro: syntax_p (C)
     `syntax_p(c)' returns true if C is a syntax object.

 - Macro: port_p (C)
     `port_p(c)' returns true if C is a port object.

 - Macro: fport_p (C)
     `fport_p(c)' returns true if C is a standard IO port object.

 - Macro: fdport_p (C)
     `fdport_p(c)' returns true if C is a file desccriptor port object.

 - Macro: sport_p (C)
     `sport_p(c)' returns true if C is a string port object.

 - Macro: TAGvector_p (C)
     `TAGvector_p(c)' returns a true value if C is a homogenous numeric
     vector object of the type indicated by TAG.

     TAG in the predicate name may be replaced by `s8', `u8', `s16',
     `u16', `s32', `u32', `s64', `u64', `f32' or `f64', depending on
     the needed datatype.  So there are actually ten of these predicate
     macros.

 - Macro: ro_TAGvector_p (C)
     `ro_TAGvector_p(c)' returns a true value if C is a homogenous
     numeric vector object of the type indicated by TAG.

     TAG in the predicate name may be replaced by `s8', `u8', `s16',
     `u16', `s32', `u32', `s64', `u64', `f32' or `f64', depending on
     the needed datatype.  So there are actually ten of these predicate
     macros.

