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: Hash table operations,  Next: Symbol operations,  Prev: Pair and list operations,  Up: Builtin Procedures

Hash tables
===========

   These procedures are always available.

 - Primitive procedure: hashq obj n
 - Primitive procedure: hashv obj n
 - Primitive procedure: hash obj n
     Determine a hash value for OBJ that is suitable for lookups in a
     hash table of size N, where `eq?', `eqv?' or `equal?' (for
     `hashq', `hashv', `hash', respectively) is used as the equality
     predicate.  The function returns an integer in the range 0 to N -
     1.  Note that these functions may use internal addresses.  Thus
     two calls to the same function where the keys are equal according
     to the sameness predicate used are not guaranteed to deliver the
     same value if the key object OBJ gets garbage collected in between.

 - Primitive procedure: make-hash [capacity] pair ...
     Creates a hash table, initialized with values taken from the
     PAIRS.  The car of each pair is taken as a hash key and the
     corresponding cdr as the value.  If the first argument is not a
     pair, it must be an integer and will give the number of buckets to
     use for the hash table.

 - Primitive procedure: hashq-get-handle tab key
 - Primitive procedure: hashv-get-handle tab key
 - Primitive procedure: hash-get-handle tab key
     These procedures are similar to their `-ref' cousins, but return
     "handles" from the hash table rather than the value associated with
     KEY.  By convention, a handle in a hash table is the pair which
     associates a key with a value.  Where `hashq-ref tab key' returns
     only a `value', `hashq-get-handle table key' returns the pair
     `(key . value)'.

 - Primitive procedure: hashq-ref tab key [default]
 - Primitive procedure: hashv-ref tab key [default]
 - Primitive procedure: hash-ref tab key [default]
     Look up KEY in the hash table TAB, and return the value (if any)
     associated with it.  If KEY is not found, return DEFAULT (or `#f'
     if no DEFAULT argument is supplied).  `hashq-ref' uses `eq?' for
     equality testing, the other functions use `eqv?' and `equal?'.

 - Primitive procedure: hashq-create-handle! tab key value
 - Primitive procedure: hashv-create-handle! tab key value
 - Primitive procedure: hash-create-handle! tab key value
     These functions look up KEY in TAB and return its handle.  If KEY
     is not already present, a new handle is created which associates
     KEY with INIT.

 - Primitive procedure: hashq-set! tab key value
 - Primitive procedure: hashv-set! tab key value
 - Primitive procedure: hash-set! tab key value
     Find the entry in TAB associated with KEY, and store VALUE there.
     `hashq-set!' uses `eq?' for equality testing, the other functions
     use `eqv?' and `equal?'.  All these procedures return the VALUE.

 - Primitive procedure: hashq-remove! tab key
 - Primitive procedure: hashv-remove! tab key
 - Primitive procedure: hash-remove! tab key
     Remove KEY (and any value associated with it) from TAB.
     `hashq-remove!' uses `eq?' for equality testing, the other
     functions use `eqv?' and `equal?'.  The procedures return the
     handle (that is, the key-value pair) that was removed or `#f' if
     the key was not found.

 - Primitive procedure: hash-fold proc seed table
     Iterate over the elements of the hash table TABLE.  PROC is
     applied to every hash table element with the arguments `(proc key
     value init)', where on the first call INIT is the given SEED, and
     on subsequent calls INIT is the result of the previous call.


File: sizzle-ref.info,  Node: Symbol operations,  Next: Character operations,  Prev: Hash table operations,  Up: Builtin Procedures

Symbol operations
=================

   The procedures in this section do not need any modules to be loaded.

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

 - Primitive procedure: symbol->string symbol
     Converts SYMBOL to a string.

 - Primitive procedure: string->symbol string
     Converts STRING to a symbol.

 - Primitive procedure: gensym [prefix]
     Generate a new symbol, constructed from PREFIX and the value of a
     counter which is incremented after each call.  PREFIX defaults to
     `)gen', if not given.


File: sizzle-ref.info,  Node: Character operations,  Next: String operations,  Prev: Symbol operations,  Up: Builtin Procedures

Character operations
====================

   All of these procedures are available without loading additional
modules.

 - Primitive procedure: char? obj
     Returns `#t' if OBJ is a character value, `#f' otherwise.

 - Primitive procedure: char= char1 char2
     Returns `#t' if CHAR1 is the same character as CHAR2, `#f'
     otherwise.

 - Primitive procedure: char< char1 char2
     Returns `#t' if CHAR1 has a smaller character value than CHAR2,
     `#f' otherwise.

 - Primitive procedure: char<= char1 char2
     Returns `#t' if CHAR1 has a smaller or equal character value than
     CHAR2, `#f' otherwise.

 - Primitive procedure: char> char1 char2
     Returns `#t' if CHAR1 has a greater character value than CHAR2,
     `#f' otherwise.

 - Primitive procedure: char>= char1 char2
     Returns `#t' if CHAR1 has a greater or equal character value than
     CHAR2, `#f' otherwise.

 - Primitive procedure: char-ci= char1 char2
     Returns `#t' if CHAR1 is the same character as CHAR2, `#f'
     otherwise. This function ignores case when comparing.

 - Primitive procedure: char-ci< char1 char2
     Returns `#t' if CHAR1 has a smaller character value than CHAR2,
     `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: char-ci<= char1 char2
     Returns `#t' if CHAR1 has a smaller or equal character value than
     CHAR2, `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: char-ci> char1 char2
     Returns `#t' if CHAR1 has a greater character value than CHAR2,
     `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: char-ci>= char1 char2
     Returns `#t' if CHAR1 has a greater or equal character value than
     CHAR2, `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: char-alphabetic? obj
     Returns `#t' if OBJ is an alphabetic character.

 - Primitive procedure: char-numeric? obj
     Returns `#t' if OBJ is a numeric character.

 - Primitive procedure: char-whitespace? obj
     Returns `#t' if OBJ is whitespace character. The characters space,
     tab, line feed, form feed and carriage return are considered to be
     whitespace.

 - Primitive procedure: char-upper-case? obj
     Returns `#t' if OBJ is an upper case character.

 - Primitive procedure: char-lower-case? obj
     Returns `#t' if OBJ is a lower case character.

 - Primitive procedure: char->integer char
     Convert the character CHAR to its ASCII value.

 - Primitive procedure: integer->char n
     Returns a character with ASCII value I.

 - Primitive procedure: char-upcase char
     Returns the upper case version of character CHAR if CHAR is a
     lower case character and CHAR otherwise.

 - Primitive procedure: char-downcase char
     Returns the lower case version of character CHAR if CHAR is a
     upper case character and CHAR otherwise.


File: sizzle-ref.info,  Node: String operations,  Next: Vector operations,  Prev: Character operations,  Up: Builtin Procedures

String operations
=================

   For convenient string handling, a lot of string primitives have been
included into the Sizzle core.  Unless otherwise noted, these procedures
do not need the inclusion of additional modules.

* Menu:

* String Predicates::           Testing strings
* String Constructors::         Creating strings
* String Accessors::            Accessing string components
* String Comparison::           Comparing strings
* String Searching::            Searching in strings
* String Decomposition::        Decompose strings into parts
* String Case Conversion::      Converting the case of strings
* String Trimming::             Trim strings
* String Padding::              Pad strings with characters
* String Pathname Operations::  Handling of pathnames


File: sizzle-ref.info,  Node: String Predicates,  Next: String Constructors,  Prev: String operations,  Up: String operations

String Predicates
-----------------

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

 - Primitive procedure: string-null? obj
     Return `#t' if OBJ is a the empty string `""', `#f' otherwise.

 - Primitive procedure: string-every pred s [start end]
     Returns a true value, if the applications of PRED to all of the
     characters of S yield true values.  START and END may be given to
     restrict operation to the characters of S between these indices.

 - Primitive procedure: string-any pred s [start end]
     Returns a true value, if the application of PRED to any of the
     characters of S yields a true value.  START and END may be given
     to restrict operation to the characters of S between these indices.


File: sizzle-ref.info,  Node: String Constructors,  Next: String Accessors,  Prev: String Predicates,  Up: String operations

String Constructors
-------------------

 - Primitive procedure: make-string k
 - Primitive procedure: make-string k char
     Return a newly allocated string of length K. CHAR is used to
     initialize the string, if omitted, the contents of the string is
     unspecified.

 - Primitive procedure: string char ...
     Return a newly allocated string composed of its arguments, which
     all must be characters.

 - Primitive procedure: string-append string ...
     Return a string made out of the concatenation of all string
     arguments.  An empty string is returned if called without
     arguments.

 - Primitive procedure: string->list string [start end]
     Convert the string STRING to a list of all characters of STRING.
     START and END delimit the region of operation and default to 0 and
     the length of STRING.

 - Primitive procedure: list->string lst
     Convert the list LIST, which must be made up from character
     values, to a string.

 - Primitive procedure: reverse-list->string lst
     An efficient implementation of `(compose string->list reverse)':
     `(reverse-list->string '(#\a #\B #\c))' => `"cBa"'

 - Primitive procedure: string-copy string [start end]
     Returns a newly allocated string with the same contents as STRING.
     START and END delimit the string to be copied, they default to 0
     and the length of STRING.

 - Primitive procedure: string-tabulate proc len
     Create a string o length LEN, where each character is initialized
     from the value returned by applying PROC to the character index.

 - Primitive procedure: string-join string-list delimiter grammar
     STRING-LIST must be a list of strings, DELIMITER must be a string
     and GRAMMAR must be any of the symbols infix, strict-infix, prefix
     or suffix.  The strings from STRING-LIST are joined with DELIMITER
     inbetween according to GRAMMAR.

     This procedure will throw an exception if STRING-LIST is empty and
     GRAMMAR is `string-infix'.

 - Primitive procedure: string-reverse s [start end]
 - Primitive procedure: string-reverse! s [start end]
     Reverse the string argument S.  START and END are optional start
     and end indices and default to 0 and the length of S,
     respectively.  `string-reverse' returns a reversed version of S,
     whereas `string-reverse!' reverses S in place and returns an
     unspecified value.


File: sizzle-ref.info,  Node: String Accessors,  Next: String Comparison,  Prev: String Constructors,  Up: String operations

String Accessors
----------------

 - Primitive procedure: string-length string
     Return the number of characters in STRING.

 - Primitive procedure: string-ref string k
     Return the Kth character of STRING. The index is zero-based. K
     must be a valid index into STRING, or an error will be signalled.

 - Primitive procedure: string-set! string k char
     Store CHAR in element K of STRING. An error will be signalled if K
     is not a valid index into STRING. The return value of this
     function is unspecified.

 - Primitive procedure: substring string start end
     Return a string formed from the characters of STRING starting at
     START (inclusive) and ending with END (exclusive).  An error is
     signalled if the following equation is not satisfied: 0 <= START
     <= END <= `(string-length' STRING`)'

 - Primitive procedure: string-fill! string char [start end]
     Stores the character CHAR in all elements of STRING. The return
     value is not specified.  START and END delimit the region which is
     filled and default to 0 and the length of STRING.


File: sizzle-ref.info,  Node: String Comparison,  Next: String Searching,  Prev: String Accessors,  Up: String operations

String Comparison
-----------------

 - Primitive procedure: string= string1 string2
     Return `#t' if STRING1 is the same string as STRING2, `#f'
     otherwise.

 - Primitive procedure: string<? string1 string2
     Returns `#t' if STRING1 is lexicographically less than STRING2,
     `#f' otherwise.

 - Primitive procedure: string<=? string1 string2
     Returns `#t' if STRING1 is lexicographically less or equal to
     STRING2, `#f' otherwise.

 - Primitive procedure: string>? string1 string2
     Returns `#t' if STRING1 is lexicographically greater than STRING2,
     `#f' otherwise.

 - Primitive procedure: string>=? string1 string2
     Returns `#t' if STRING1 is lexicographically greater or equal to
     STRING2, `#f' otherwise.

 - Primitive procedure: string-ci=? string1 string2
     Returns `#t' if STRING1 is the same string as STRING2, `#f'
     otherwise. This function ignores case when comparing.

 - Primitive procedure: string-ci<? string1 string2
     Returns `#t' if STRING1 is lexicographically less than STRING2,
     `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: string-ci<=? string1 string2
     Returns `#t' if STRING1 is lexicographically less or equal to
     STRING2, `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: string-ci>? string1 string2
     Returns `#t' if STRING1 is lexicographically greater than STRING2,
     `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: string-ci>=? string1 string2
     Returns `#t' if STRING1 is lexicographically greater or equal to
     STRING2, `#f' otherwise. This function ignores case when comparing.

 - Primitive procedure: string-prefix-length s1 s2 [start1 end1 start2
          end2]
     Return the length of the longest common prefix of the two strings.

 - Primitive procedure: string-prefix-length-ci s1 s2 [start1 end1
          start2 end2]
     Return the length of the longest common prefix of the two strings.
     When comparing characters, case is ignored.

 - Primitive procedure: string-suffix-length s1 s2 [start1 end1 start2
          end2]
     Return the length of the longest common suffix of the two strings.

 - Primitive procedure: string-suffix-length-ci s1 s2 [start1 end1
          start2 end2]
     Return the length of the longest common suffix of the two strings.
     Case is ignored when comparing characters.

 - Primitive procedure: string-prefix? s1 s2 [start1 end1 start2 end2]
     Return `#t' if S1 is a prefix of S2.

 - Primitive procedure: string-prefix-ci? s1 s2 [start1 end1 start2
          end2]
     Return `#t' if S1 is a prefix of S2.  Case is ignored when
     comparing characters.

 - Primitive procedure: string-suffix? s1 s2 [start1 end1 start2 end2]
     Return `#t' if S1 is a suffix of S2.

 - Primitive procedure: string-suffix-ci? s1 s2 [start1 end1 start2
          end2]
     Return `#t' if S1 is a suffix of S2.  Case is ignored when
     comparing characters.


File: sizzle-ref.info,  Node: String Searching,  Next: String Decomposition,  Prev: String Comparison,  Up: String operations

String Searching
----------------

 - Primitive procedure: string-index string ch/pred [start end]
     Scans the string STRING for the leftmost appearance of character
     CH and returns the index or `#f' if not found.  If the second
     argument is a procedure, it must be a predicate which will be
     applied to each character in STRING, and the index of the first
     character for which the predicate yields true is returned.  START
     is the start index and defaults to zero, END is the end index and
     defaults to the length of STRING - 1.

 - Primitive procedure: string-index-right string ch/pred [start end]
     Scans the string STRING for the rightmost appearance of character
     CH and returns the index or `#f' if not found.  If the second
     argument is a procedure, it must be a predicate which will be
     applied to each character in STRING from right to left, and the
     index of the last character for which the predicate yields true is
     returned.  START is the start index and defaults to zero, END is
     the end index and defatuls to the length of STRING - 1.  This
     function searches from right to left, whereas `string-index'
     searches from left to right.

 - Primitive procedure: string-skip string ch/pred [start end]
     Scans the string STRING for the leftmost appearance of a character
     different to CH and returns the index or `#f' if not found.  If
     the second argument is a procedure, it must be a predicate which
     will be applied to each character in STRING, and the index of the
     first character for which the predicate yields false is returned.
     START is the start index and defaults to zero, END is the end
     index and defaults to the length of STRING - 1.

 - Primitive procedure: string-skip-right string ch/pred [start end]
     Scans the string STRING for the rightmost appearance of a
     character different from CH and returns the index or `#f' if not
     found.  If the second argument is a procedure, it must be a
     predicate which will be applied to each character in STRING from
     right to left, and the index of the last character for which the
     predicate yields false is returned.  START is the start index and
     defaults to zero, END is the end index and defatuls to the length
     of STRING - 1.  This function searches from right to left, whereas
     `string-index' searches from left to right.

 - Primitive procedure: string-count string ch/pred [start end]
     Return a count of the number of characters in STRING that satisfy
     the CH/PRED argument.  If this argument is a procedure, it is
     applied to all characters as a predicate; if it is a character, it
     is used in a equality test.  START is the start index and defaults
     to zero, END is the end index and defatuls to the length of STRING
     - 1.

 - Primitive procedure: string-contains string1 string2 [start1 end1
          start2 end2]
     Return the index in STRING1 where STRING2 occurs as a substring,
     or `#f'.  The optional START/END indices restrict the operation to
     the indicated substrings.  The returned index is in the range
     [START1, END1).  A successful match must lie entirely in the
     [START1, END1) range of STRING1.

     Note: The current implementation uses the naivest possible
     algorithm and is slow when STRING1 is a long string.

 - Primitive procedure: string-contains-ci string1 string2 [start1 end1
          start2 end2]
     Return the index in STRING1 where STRING2 occurs as a substring,
     or `#f'.  The optional START/END indices restrict the operation to
     the indicated substrings.  The returned index is in the range
     [START1, END1).  A successful match must lie entirely in the
     [START1, END1) range of STRING1.  Case is ignored when comparing
     individual characters.

     Note: The current implementation uses the naivest possible
     algorithm and is slow when STRING1 is a long string.

 - Primitive procedure: string-hash s [bound start end]
     Compute a hash value for the string S.  BOUND is either the
     boolean constant `#t' or a positive integer, then the result of the
     procedure will be in the range [0, BOUND).  START and END are
     optional parameters delimiting the characters which are used to
     calculate the hash value, they default to 0 and the length of S.

 - Primitive procedure: string-hash-ci s [bound start end]
     Compute a hash value for the string S.  BOUND is either the
     boolean constant `#t' or a positive integer, then the result of the
     procedure will be in the range [0, BOUND).  START and END are
     optional parameters delimiting the characters which are used to
     calculate the hash value, they default to 0 and the length of S.
     The case of the characters in S is ignored when computing the hash
     value.


File: sizzle-ref.info,  Node: String Decomposition,  Next: String Case Conversion,  Prev: String Searching,  Up: String operations

String Decomposition
--------------------

 - Primitive procedure: string-split ch string
     Splits the string STRING into pieces, using CH as the delimiting
     character. Returns a list of strings, where the stings may be
     empty if two or more delimiting characters are in STRING without
     characters inbetween.

 - Primitive procedure: string-take s nchars
     Return the first NCHARS characters of S.

 - Primitive procedure: string-take-right s nchars
     Return the last NCHARS characters of S.

 - Primitive procedure: string-drop s nchars
     Return all but the first NCHARS characters of S.

 - Primitive procedure: string-drop-right s nchars
     Return all but the last NCHARS characters of S.


File: sizzle-ref.info,  Node: String Case Conversion,  Next: String Trimming,  Prev: String Decomposition,  Up: String operations

String Case Conversion
----------------------

 - Primitive procedure: string-upcase! string [start end]
     Convert all characters in STRING to upper case, modifying STRING
     in-place.  START and END delimit the region of operation and
     default to 0 and the length of STRING.

 - Primitive procedure: string-upcase string [start end]
     Convert all characters in STRING to upper case, returning a newly
     allocated string.  START and END delimit the region of operation
     and default to 0 and the length of STRING.

 - Primitive procedure: string-downcase! string [start end]
     Convert all characters in STRING to lower case, modifying STRING
     in-place.  START and END delimit the region of operation and
     default to 0 and the length of STRING.

 - Primitive procedure: string-downcase string [start end]
     Convert all characters in STRING to lower case, returning a newly
     allocated string.  START and END delimit the region of operation
     and default to 0 and the length of STRING.

 - Primitive procedure: string-titlecase! string [start end]
     Convert all characters in STRING which start words to upper case
     and all other characters to lower case, modifying STRING in-place.
     START and END delimit the region of operation and default to 0 and
     the length of STRING.

 - Primitive procedure: string-titlecase string [start end]
     Convert all characters in STRING which start words to upper case
     and all other characters to lower case, returning a newly allocated
     string.  START and END delimit the region of operation and default
     to 0 and the length of STRING.


File: sizzle-ref.info,  Node: String Trimming,  Next: String Padding,  Prev: String Case Conversion,  Up: String operations

String Trimming
---------------

 - Primitive procedure: string-trim string [char/pred start end]
     Skip all characters matching the character CHAR or passing
     application of PRED at the left of the string.  START and END are
     optional parameters to restrict operation to the characters
     between these indices.

 - Primitive procedure: string-trim-right string [char/pred start end]
     Skip all characters matching character CHAR or passing application
     of PRED at the right of the string.  START and END are optional
     parameters to restrict operation to the characters between these
     indices.

 - Primitive procedure: string-trim-both string [char/pred start end]
     Skip all characters matching the character CHAR or passing
     application of PRED at both ends of the string.  START and END are
     optional parameters to restrict operation to the characters
     between these indices.

 - Primitive procedure: string-chop string
     Return a newly allocated string with the contents of STRING, but
     with all trailing newline characters removed.

 - Library procedure: trim-whitespace string
     Return STR, but with all whitespace both at the beginning and at
     the end removed.  The same characters are considered to be
     whitespace as for the `char-whitespace?' primitive.

     This procedure must be imported by using the module `core
     string-lib'.

     Note: This procedure has been deprecated.  Use `string-trim-both'
     instead.


File: sizzle-ref.info,  Node: String Padding,  Next: String Pathname Operations,  Prev: String Trimming,  Up: String operations

String Padding
--------------

 - Primitive procedure: string-pad s len [char start end]
     Build a string of length LEN comprised of S padded on the left by
     as many occurences of the character CHAR as needed.  If S has more
     than LEN characters, it is truncated on the left to length LEN.
     CHAR defaults to `#\space'.

 - Primitive procedure: string-pad-right s len [char start end]
     Build a string of length LEN comprised of S padded on the rightt
     by as many occurences of the character CHAR as needed.  If S has
     more than LEN characters, it is truncated on the right to length
     LEN.  CHAR defaults to `#\space'.


File: sizzle-ref.info,  Node: String Pathname Operations,  Prev: String Padding,  Up: String operations

String Pathname Operations
--------------------------

 - Primitive procedure: basename name [suffix]
     Removes any leading directory components from NAME; if SUFFIX is
     specified and is identical to the end of name, it is removed from
     NAME as well. The resulting string is returned.

 - Primitive procedure: dirname filename
     Returns a string of all but the final slash-delimited component of
     FILENAME.  If FILENAME is a single component, `dirname' returns
     `.' (meaning the current directory).

 - Primitive procedure: cleanup-filename filename
     Clean the given FILENAME up and convert it to a canonical form by
     removing all appearences of parent directory references
     (`/foo/..'), current directory marks (`./'), multiple slashes
     (`//') and trailing slashes. The root directory indicator `/' is
     not deleted, though it is a trailing slash.

 - Library procedure: tilde-expand string
     Expand character sequences like `~' and `~username' in FILENAME
     like bash and Emacs do.  FILENAME is unchanged if it has the form
     `~username', but the given user does not exist.

     This procedure must be imported by using the module `core
     string-lib'.


File: sizzle-ref.info,  Node: Vector operations,  Next: Homogenous Vector Operations,  Prev: String operations,  Up: Builtin Procedures

Vector operations
=================

   Vectors are heterogenous data types, similar to lists.  That means
that any Scheme data type can be stored into vectors.  The main
difference between lists and vectors is that vectors are of fixed size
and that elements can be accessed in constant time, whereas lists
require linear time to access individual elements.

* Menu:

* Vector constructors::         Procedures for creating vectors.
* Vector predicates::           Procedure for examining vector objects.
* Vector selectors::            Accessing data from vectors.
* Vector conversion::           Converting from and to other data types.
* Vector modifying::            Changing vector content.


File: sizzle-ref.info,  Node: Vector constructors,  Next: Vector predicates,  Prev: Vector operations,  Up: Vector operations

Vector constructors
-------------------

   Vectors can be created by either entering them literally in the
normal Scheme vector syntax `#(...)', or they can be created with one of
these functions.  See *Note Vector conversion:: for the procedure
`list->vector', which is also a constructor function.

   Vectors created with one of these procedures are mutable and can
therefore be passed to procedures like `vector-set!'.

 - Primitive procedure: make-vector k
 - Primitive procedure: make-vector k fill
     Return a newly allocated vector of length K. FILL is used to
     initialize the vector, if omitted the contents of the vector is
     unspecified.

 - Primitive procedure: vector obj ...
     Returns a newly allocated vector composed of its arguments.

 - Library procedure: vector-tabulate count init-proc
     Create a vector with COUNT elements.  The vector is initialized by
     setting the vector element at position I to the value returned by
     applying INIT-PROC to I.  The dynamic order in which INIT-PROC is
     applied is not specified.

     This procedure must be imported by using the module `core
     vector-lib'.

 - Library procedure: vector-copy vec
     Create a freshly allocated copy of the vector VEC.

     This procedure must be imported by using the module `core
     vector-lib'.


File: sizzle-ref.info,  Node: Vector predicates,  Next: Vector selectors,  Prev: Vector constructors,  Up: Vector operations

Vector predicates
-----------------

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

 - Library procedure: vector= elt= vec1 vec2 ...
     Returns true if all given vectors are equal.  Two vectors are
     equal if they have the same length and if the elements at the
     corresponding indices are equal according to the procedure ELT=.

     This procedure must be imported by using the module `core
     vector-lib'.


File: sizzle-ref.info,  Node: Vector selectors,  Next: Vector conversion,  Prev: Vector predicates,  Up: Vector operations

Vector selectors
----------------

   Use one of these procedures to obtain information from a vector and
to access individual elements.

 - Primitive procedure: vector-length vector
     Returns the number of elements of VECTOR.

 - Primitive procedure: vector-ref vector k
     Returns the Kth element of VECTOR. The index is zero-based. K must
     be a valid index into VECTOR, or an error will be signalled.


File: sizzle-ref.info,  Node: Vector conversion,  Next: Vector modifying,  Prev: Vector selectors,  Up: Vector operations

Vector conversion
-----------------

 - Primitive procedure: vector->list vector
     Convert the vector VECTOR to a list of all elements of VECTOR.

 - Primitive procedure: list->vector lst
     Convert the list LIST to a vector.


File: sizzle-ref.info,  Node: Vector modifying,  Prev: Vector conversion,  Up: Vector operations

Vector modifying
----------------

   The procedures in this section may only be used with mutable vectors.
Vectors literally entered may not be passed to these procedures.

 - Primitive procedure: vector-set! vector k obj
     Stores OBJ in element K of VECTOR. An error will be signalled if K
     is not a valid index into VECTOR. The return value of this
     function is unspecified.

 - Primitive procedure: vector-fill! vector obj
     Stores OBJ in all elements of VECTOR. The return value is not
     specified.


File: sizzle-ref.info,  Node: Homogenous Vector Operations,  Next: Control flow operations,  Prev: Vector operations,  Up: Builtin Procedures

Homogenous Vector Operations
============================

   Homoenous vectors are different to normal Scheme vectors, because
only numeric values can be stored into those vectors, and all elements
must have the same type.

   Please note that homogenous vectors are only available when they were
included on configuration time of the Sizzle library.  If you need these
data types and primitives, please *Note Building Sizzle:: and build the
library with enabled homogenous vectors.

   In the following procedure descriptions, the placeholder TAG can be
replaced by any of the strings `s8', `u8', `s16', `u16', `s32', `u32',
`s64', `u64', `f32' and `f64', depending on the data type the procedure
should be used for. Examples are: `s8vector?', `make-u16vector' or
`f32vector-length'.

 - Primitive procedure: TAGvector? obj
     Returns `#t' if OBJ matches the type indicated by TAG, `#f'
     otherwise.

 - Primitive procedure: make-TAGvector n [fill]
     Create a vector for holding values of the type TAG, which can hold
     exactly N elements.  FILL is used to initialize the vector and
     defaults to 0, if not present.

 - Primitive procedure: TAGvector-length vec
     Returns the length of the homogenous vector VEC, which must be of
     type TAG.

 - Primitive procedure: TAGvector obj1 ...
     Creates and returns a homogenous vector of type TAG and
     initializes it with all parameters.  The resulting vector has as
     much elements as there are OBJ parameters.

 - Primitive procedure: TAGvector-ref vec n
     Returns the element at position N in the homogenous vector VEC.

 - Primitive procedure: TAGvector-set! vec n obj
     Stores the object OBJ at position N into the homogenous vector
     VEC.  VEC must be of the vector type indicated by TAG, and OBJ
     must match TAG also.

 - Primitive procedure: TAGvector->list vec
     Converts the homogenous vector VEC, which must match the vector
     type indicated by TAG, to a list of its elements.

 - Primitive procedure: list->TAGvector list
     Creates a homogenous vector which holds all elements of the list
     LIST.  All elements must match the type TAG.

 - Primitive procedure: TAGvector-fill!! vec fill
     Stores the object FILL into all slots of the homogenous vector
     VEC.  VEC must match the vector type indicated by TAG, and FILL
     must be of a type compatible with TAG.

 - Primitive procedure: string->s8vector str
 - Primitive procedure: string->u8vector str
     Convert the string STR into a signed or unsigned 8-bit vector.

 - Primitive procedure: s8vector->string vec
 - Primitive procedure: u8vector->string vec
     Convert the signed of unsigned 8-bit vector VEC to a string.


File: sizzle-ref.info,  Node: Control flow operations,  Next: Eval function,  Prev: Homogenous Vector Operations,  Up: Builtin Procedures

Control flow operations
=======================

   The following procedures can be used to maintain the flow of control
in Scheme programs.  The basic procedure `apply', exception handling
using `catch' and `throw' and handling of multiple values with
`values', `call-with-values' and `receive' are documented in this
section.

   These procedures are always available in the Sizzle library except
when otherwise noted.

 - Primitive procedure: procedure? obj
     Returns `#t' if OBJ is a primitive or user-defined procedure, `#f'
     otherwise.

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

 - Primitive procedure: closure? obj
     Returns `#t' if OBJ is a user-defined procedure, `#f' otherwise.

 - Primitive procedure: form? obj
     Returns `#t' if OBJ is a syntactic form, `#f' otherwise.

 - Primitive procedure: apply proc arg1 ... args
     PROC must be a procedure and ARGS must be a list. Calls PROC with
     the elements of the list `(append (list arg1 ...)  args)' as the
     actual arguments.

 - Primitive procedure: force promise
     Force the evaluation of PROMISE, which must be created with a
     prior call to `delay'.  The value of the promise is cached so that
     a second force will return the cached value without evaluating it
     again.

 - Primitive procedure: values obj ...
     Delivers all its arguments to its continuation. Used with
     `call-with-values' (see below).

 - Primitive procedure: call-with-values producer consumer
     Calls its PRODUCER thunk and calls the CONSUMER with whatever
     values have been returned by PRODUCER.  CONSUMER must take as many
     arguments as PRODUCER has returned values.

 - Library syntax: receive formals expression body
     This is a more convenient way to handle multiple values.
     EXPRESSION is evaluated and the results are assigned to variables
     named in FORMALS, then BODY is evaluated.  FORMALS must be of the
     same form as allowed for specifying the formal parameters of a
     lambda expression.

     This syntax 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.

 - Primitive procedure: dynamic-wind before thunk after
     Calls THUNK without arguments, returning the result(s) of the
     call.  BEFORE is called before THUNK is called, and AFTER is
     called after THUNK.  `dynamic-wind' can be used for cleaning up,
     since AFTER is called even if THUNK causes an error or an
     exception.

 - Primitive procedure: signal no proc
     Install a signal handler.  After installing a signal handler with
     this function, PROC is called whenever the signal NO is sent to
     the Sizzle process.  The signals defined for your system are
     available as constants, on a normal GNU/Linux box the following
     signals are predefined:
    `SIGHUP'
          Hangup signal.

    `SIGINT'
          Interrupt, normally generated when the user types <C-c>.

    `SIGQUIT'
          Quit.

    `SIGILL'
          Illegal instruction.

    `SIGTRAP'
          Trap.

    `SIGABRT'
          Process abort.

    `SIGIOT'
          Input/output trap.

    `SIGBUS'
          Bus error.  Normally due to misaligned data access.

    `SIGFPE'
          Floating point exception.

    `SIGKILL'
          Kill signal. This cannot be caught.

    `SIGUSR1'
          First user-definable signal.

    `SIGUSR2'
          Second user-definable signal.

    `SIGSEGV'
          Segmentation fault.

    `SIGPIPE'
          Broken pipe. Generated when writing to a closed pipe.

    `SIGALRM'
          Alarm.

    `SIGTERM'
          Process termination.

    `SIGSTKFLT'
          Stack fault

    `SIGCLD'
          The same as `SIGCHLD'.

    `SIGCHLD'
          Child process terminated.

    `SIGCONT'
          Continue signal.

    `SIGSTOP'
          Stop signal.

    `SIGTSTP'
          Terminal stop.

    `SIGTTIN'
          Terminal input signal.

    `SIGTTOU'
          Terminal output signal.

    `SIGURG'
          Urgency signal.

    `SIGXCPU'
          CPU time exceeded.

    `SIGXFSZ'
          File limit exceeded.

    `SIGVTALRM'
          Virtual alarm.

    `SIPROF'
          Profiler signal.

    `SIGWINCH'
          Window configuration changed.

    `SIGPOLL'
          Poll signal.

    `SIGIO'
          Input/output signal.

    `SIGPWR'
          Power failure.

     Note that this procedure is only available when the Un*x signals
     work for the underlying platform.

 - Primitive procedure: error obj ...
     Signal an error.  The current computation is aborted and the list
     of the arguments which is passed to the top level together with
     the error is displayed on the current standard error output port.

 - Primitive procedure: throw symbol obj ...
     Raise an exception with the exception tag TAG which will be passed
     upward in the call chain until either a `catch' clause for the TAG
     exception tag catches the exception or the top level is reached,
     where the exception will be displayed on the current standard
     error output port.

 - Primitive procedure: catch tag thunk handler
     `catch' is used to implement exception handling. THUNK is
     evaluated but any exception which may be thrown by an expression
     evaluated inside of THUNK and is equal to the exception tag TAG
     (in the sense of `eq?') is caught. Should no exception be raised,
     the result of the last expression is returned.  Otherwise, HANDLER
     is called with the tag which was thrown to and additional
     arguments which may be passed to throw as arguments and the result
     of evaluating HANDLER is returned.

     If TAG is `#t', all exceptions are caught.

          zzz: (catch 'panic
                      (lambda () (throw 'panic "Help" "Me" "!" ))
                      (lambda (tag . rest) (display rest) (newline) #f))
          (Help Me !)
          #f
          zzz: (catch #t
                      (lambda () (throw 'burgs))
                      (lambda (tag . rest) #f))
          #f

 - Primitive procedure: toplevel
     Return to the top level read-eval-print loop of the current Sizzle
     session, or, if running non-interactively, returns to the top
     level file loading loop.

 - Primitive procedure: exit
 - Primitive procedure: exit n
     Terminate the running Sizzle process, returning to the shell which
     executed it.  N is the exit code of the process, if given,
     otherwise the exit code is zero.

 - Primitive procedure: call-with-current-continuation proc
 - Primitive procedure: call/cc proc
     Calls PROC with the current continuation as its argument.  PROC
     may then call the passed continuation with a parameter to deliver
     that value to the continuation.  The result of
     `call-with-current-continuation' is either the result of PROC (if
     the continuation was not called) or the argument passed to the
     continuation.

     When calling a continuation with more then one parameter, all
     parameters are delivered to the continuation as multiple values.

     `call/cc' is synonym to `call-with-current-continuation'.

     Note that Sizzle does not implement a full-featured `call/cc'. The
     continuation passed to PROC may only be used as an escape
     procedure.  Storing it into a variable and using it from anywhere
     not in the dynamic extent of PROC is an error and will signal an
     exception.

 - Primitive procedure: primitive-load string
     Loads and evaluates all Scheme expressions from the file named
     STRING. Evaluation takes place in the toplevel environment. The
     return value is unspecified.  Throws an `file-not-found' exception
     if STRING does not refer to an existing file.  The return value is
     unspecified.

 - Primitive procedure: primitive-load-path string
     Loads and evaluates all Scheme expressions from the file named
     STRING. Evaluation takes place in the toplevel environment. The
     return value is unspecified.  When STRING is not an absolute file
     name, `primitive-load-path' tries to locate the file in the current
     directory and then in all directories in the pathname list
     %LOAD-PATH.  Throws an `file-not-found' exception if STRING does
     not refer to an existing file.  The return value is unspecified.

 - Primitive procedure: load string
     Synonym to `primitive-load-path'.

 - Primitive procedure: transcript-on filename
 - Primitive procedure: transcript-off
     FILENAME must be a string naming an output file to be created.
     The effect of `transcript-on' is to open the named file for output,
     and to cause a transcript of subsequent interaction between the
     user and the Scheme system to be written to the file. The
     transcript is ended by a call to `transcript-off', which closes
     the transcript file.  Only one transciript may be in progress at
     any time.  The values returned by these procedures are unspecified.


File: sizzle-ref.info,  Node: Eval function,  Next: Debugging Support,  Prev: Control flow operations,  Up: Builtin Procedures

Eval function
=============

   All of the following procedures are always defined in the Sizzle
interpreter.

 - Primitive procedure: eval expression
 - Primitive procedure: eval expression environment-specifier
     Evaluate EXPRESSION in the environment given by
     ENVIRONMENT-SPECIFIER. If omitted, the current environment is
     used.  Enironment specifiers can only be obtained by using one of
     the following three procedures.

 - Primitive procedure: scheme-report-environment version
     Return an environment with all bindings defined in R5RS to be used
     with `eval'.  VERSION must be an exact integer spcifying the
     supported Scheme report version, currently this is 5.

 - Primitive procedure: null-environment version
     Return an empty environment to be used with `eval'.  VERSION must
     be an exact integer spcifying the supported Scheme report version,
     currently this is 5.

 - Primitive procedure: interaction-environment
     Return the environment of the read-eval-print loop to be used with
     `eval'.

 - Primitive procedure: current-environment
     Return the environment currently used to look up bindings to be
     used with `eval'.

 - Primitive procedure: safe-environment symbol-list
     Create and return a "safe" environment, in which only the special
     forms are defined.  Also, the current bindings for all symbols in
     SYMBOL-LIST are entered into the new environment.  This procedure
     can be used to construct environments in which untrusted code can
     be safely executed.  The executed code then only has access to the
     builtin special forms and all bindings passed explicitly to
     `safe-environment', and is not able to affect any other
     environments.


File: sizzle-ref.info,  Node: Debugging Support,  Next: Input and output,  Prev: Eval function,  Up: Builtin Procedures

Debugging Support
=================

   The following procedures are always supported.

 - Primitive procedure: backtrace
     Prints a procedure backtrace for the last error signalled.  You
     have to evaluate `(set! eval-save-backtrace #t)' prior to
     evaluating the invalid expression or the backtrace will not be
     available.

 - Primitive procedure: trace proc on/off
     Note: Tracing is currently disabled because it slows down the
     interpreter and was not too useful.  If you should need it, please
     contact the author.

     If ON/OFF is true, start tracing procedure PROC, otherwise, switch
     tracing for PROC off.

     When a procedure is traced, a message will be printed to the
     current error port whenever the procedure is called.  Given a
     procedure `foo', which receives one argument, the format of the
     message is
          + foo <- (1)
     That means that `foo' is entered (indicated by the `+') with the
     parameter list `(1)'.

     When tracing primitive procedures, a message when exiting from the
     procedure is also printed.  A call to the traced primitive `modulo'
     with the parameter list `(3 2)' looks like this:
          + modulo <- (3 2)
          - modulo -> 1
     The second line tells that the result of the function is `1'.

     Currently, no exit message is printed for non-primitive procedures
     is printed because of problems with tail calls.  With the current
     scheme, it is not possible to tell easily when a procedure exits.
     I hope to change that behaviour in the future.

 - Primitive procedure: symbol-table
     Returns the global symbol table, in which all globally existing
     symbols are stored.  The returned table is a vector of lists of
     symbols, which can be examined if you are curious.  Be careful
     when using this procedure and never modify the table or any data
     stored in it, or the interpreter may heavily crash.

 - Primitive procedure: keyword-table
     Returns the global keyword table, in which all globally existing
     keywords are stored.  The returned table is a vector of lists of
     keywords, which can be examined if you are curious.  Be careful
     when using this procedure and never modify the table or any data
     stored in it, or the interpreter may heavily crash.

