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: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

   This document describes how to use the Scheme interpreter Sizzle.

   It applies to version 0.0.30 of Sizzle.

* Menu:

* Introduction::                Introduction to Sizzle
* Using Sizzle::                How to use Sizzle
* Programming Scheme::          Programming in Scheme and Sizzle
* Predefined Variables::        Variables for controlling the interpreter
* Builtin Procedures::          All predefined procedures and forms
* Sizzle vs R5RS::              Comparison of Sizzle and Standard Scheme
* Glossary::                    The glossary
* Index::                       Function and variable index


File: sizzle-ref.info,  Node: Introduction,  Next: Using Sizzle,  Prev: Top,  Up: Top

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

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

   Sizzle implements a subset of Scheme as described in the Revised 5
Report on the Algorithmic Language Scheme (referred to as R5RS in this
manual).  That means that Sizzle employs fully parenthesized prefix
notation (as known from Lisp), is statically scoped and handles builtin
and user defined procedures as first-class objects. It implements most
of Scheme as defined in R5RS, but it does not support complex numbers,
arbitrary precision numbers (bignums) or rational numbers.  In addition,
only outward continuations (a.k.a. escape procedures) are implemented.

   That means that Sizzle is a quite powerful language and will (as
least I hope so) be useful for a lot of programming tasks.

   Most of the text in the reference section of this manual is heavily
inspired by R5RS, especially the description of the standard syntactic
forms and standard procedures.  Some parts, especially documentation on
procedures compatible with Guile, have been taken from the Guile
documentation strings.

   The chapter after this introduction describes Sizzle from the user's
point of view, you will learn how to start the interpreter and how to
use it interactively as well as how to use it to execute Scheme scripts.

   After that, in the third chapter, I will show how to do basic
programming in the Scheme programming language and which data types are
available and how to make use of them.

   The fourth chapter documents the builtin variables which can be used
to monitor and manipulate the interpreter's behaviour from Scheme.

   The main reference section (chapter 5) documents all procedures as
well as the syntactic forms available in the interpreter.

   The sixth chapter lists all (known) differences between the Scheme
implementation of Sizzle and the standard defined in R5RS.

   The manual is closed by a a glossary and an index of all functions
and variables.

* Menu:

* Sizzle History::              How Sizzle became what it is now
* Sizzle Future::               Future changes planned


File: sizzle-ref.info,  Node: Sizzle History,  Next: Sizzle Future,  Prev: Introduction,  Up: Introduction

Sizzle History
==============

   I started writing Sizzle simply because I was interested in compiler
and interpreter design.  A long time ago, I had been porting a lisp
interpreter called XLISP, which was written in C to Pascal.  Ever since
I was interested in parenthesized languages, and when I learned about
Scheme, I was immediately fascinated by its clear and beautiful design.
So I started writing small Scheme scripts and finally became more
interested and decided to build an interpreter.  It started out small,
as always, but soon I noticed that I was able to implement even a bit
more complicated features, so the interpreter grew.  Now the
distribution is more than half a meg big, and still grows.


File: sizzle-ref.info,  Node: Sizzle Future,  Prev: Sizzle History,  Up: Introduction

Sizzle Future
=============

   I hope that I will be able to make a more accurate and complete
documentation someday.  Also, there are a few features I would like to
see in the interpreter, such as bignum arithmetic, rationals, hygienic
macros, etc.  Some internal architectural changes seem desirable also,
for example for speeding up the reader. Some profiling for creating a
faster evaluator will be on the wishlist also, maybe more extensive
syntax rewriting may help with this.

   I would like to see all (at least all sensible) SRFIs implemented.
Currently, only SRFI-1, SRFI-6 and SRFI-8 are implemented. SRFI-13 is
implemented partly.


File: sizzle-ref.info,  Node: Using Sizzle,  Next: Programming Scheme,  Prev: Introduction,  Up: Top

Using Sizzle
************

   Sizzle is an embedding language which can be easily integrated into
other programs written in C, but it also includes a command line program
which can be used to do calculations in an read-eval-print loop as well
as running scripts written in the Scheme language.

   This chapter will explain how to make use of Sizzle as an interactive
program as well as how to execute script files.

* Menu:

* Starting Sizzle::             How to invoke Sizzle
* Interactive Usage::           Using Sizzle's read-eval-print loop
* Automatic Interactive Variable::
* Command Line Editing::        Command lin editing and history
* Sizzle Scripts::              Using Sizzle to run scripts
* Startup Sequence::            What happens when Sizzle starts up?
* Environment Variables::       Environment variables used by Sizzle
* Building Sizzle::


File: sizzle-ref.info,  Node: Starting Sizzle,  Next: Interactive Usage,  Prev: Using Sizzle,  Up: Using Sizzle

Starting Sizzle
===============

   To start Sizzle, simply type `sizzle' at the command line.  Sizzle
will then initialize and start reading expression from the terminal. It
will read and evaluate expressions and print them to the screen until
you terminate it by either pressing `^D' at the prompt or entering the
expression `(exit)'.

   The command line interpreter understands the command line options
shown in the table below.

`-s, --script=FILE'
     Execute the Scheme source file `file', and exit.

`-c, --command=EXPR'
     Evaluate the Scheme expression EXPR, and exit.

`--'
     Stop processing options and treat all following arguments as
     non-options, even if they begin with a dash (`-').

`-l, --load=FILE'
     Load Scheme source code from `file'.

`-e, --eval=FUNCTION'
     After reading script given with `-s, --script=FILE', apply
     FUNCTION to command line arguments.  This option also can be used
     with `-c, --command=EXPR'.

`-h, --help'
     Show a help message about program usage and terminate.

`-v, --version'
     Show the version of the program and terminate.

`-q, --no-init-file'
     Do not load the user's init file `~/.sizzle'.

`-n, --no-system-init-file'
     Do not load the system init file.

`-d, --debug'
     Increase the debugging level.  This option can be given more than
     once, each occurence will turn on more debugging messages.

   The command line option `-s, --script=FILE' has to be used whenever
a Scheme script is to be executed by Sizzle.  The file `file' will be
read and all Scheme expression contained in it will be evaluated in
order.  After evaluation is finished, Sizzle terminates.  For more
details about Sizzle scripts see *Note Sizzle Scripts::.

   `-c, --command=EXPR' is similar, but instead of reading a file of
Scheme expressions, the Scheme expression EXPR will be evaluated.

   Note that when using `-s' or `-c', all remaining arguments on the
command line are ignored by Sizzle and are passed to the Scheme script
or the Scheme expression without interpretation and are available via
the primitive `command-line', please see *Note System interface
functions::.

   The pseudo-option `--' will be discarded from the command line, but
all remaining parameters will be treated as normal arguments and not as
options, even if they begin with a dash (`-').  This can be used when
passing options to a Sizzle script.

   All file names given with the option `-l, --load=FILE' (which can be
given more than once) are loaded into the interpreter by evaluating all
expressions read from the files, but unlike `-s', the interpreter will
not terminate after evaluating the files, but continue as normal.  That
means, that without `-s' and `-c', the interactive read-eval-print loop
will start, otherwise the appropriate action will be done, as described
above.

   `-e, --eval=FUNCTION' is intended to be used with `-s', when you are
using Scheme files which can be used both as library files and as
executable scripts.  You can do this by placing library code in the
file and a function which serves as the main function.  When you use
`-s', the file will simply be loaded, but the main function will
normally not get called.  This is exactly what `-e' is for.  Simply
pass the name of the main function to `-e' and this function will then
be applied to the remaining command line arguments after the script
file has been loaded.

   `-h, --help' will print out a short helping message and then quit.

   `-v, --version' prints out the version of the Sizzle interpreter you
have installed, and then terminate.  Use this command if you want to
complain about a bug in your version of Sizzle, in addition to as much
information about your system as possible.

   Use the option `-q, --no-init-file' if you want to inhibit automatic
loading of your user's init file `~/.sizzle'.

   Similarly the option `-n, --no-system-init-file' prevents the
system's init file from being loaded.  Note that with this option, some
common procedures will not be available in the interpreter.

   With the option `-d, --debug', Sizzle will print some debugging
messages while running.  Each occurence of `-d' increases the debugging
level and will cause more information to be printed out.  This option
will not be very interesting for normal users and is intended for being
used by the Sizzle developers.


File: sizzle-ref.info,  Node: Interactive Usage,  Next: Automatic Interactive Variable,  Prev: Starting Sizzle,  Up: Using Sizzle

Interactive Usage
=================

   When you have started the Sizzle interpreter, you can start right
away with typing in Scheme expressions and see how they evaluate.  I
will give some simple examples in this section.

   Numbers, characters and strings can be entered in their read syntax
and evaluate to themselves.
     zzz: 1
     1
     zzz: "Hello World"
     "Hello World"
     zzz: #\H
     #\H

   Lists and vectors need to be quoted, because they do not evaluate to
themselves.  Lists are considered to be function calls and therefore
evaluate in a special way (see below).  The reason why vector constants
do not evaluate is not clear to me, but R5RS requires that. Strange...

     zzz: #(1 2)
     exception: misc-error: vectors do not evaluate to themselves
     no backtrace available
     evaluate `(set! %save-backtrace% #t)' if you want backtraces
     zzz: '#(1 2)
     #(1 2)

     zzz: (1 2)
     exception: misc-error: not a procedure: 1
     zzz: '(1 2)
     (1 2)

   In the above two examples, error messages have been printed in
response to the user's input.  In an error message, the type of the
error is printed first: Here, it is an exception of type `misc-error'.
The following is a description of the error.  In addition, we can see
that the first error shown to the user includes some more information:
The fact that currently backtraces are not available is noted and a tip
how to enable procedure backtraces.

   Procedures are invoked by writing the function name as the first
member in a list.  Consider the function `+', which adds all its
arguments.
     zzz: (+ 1 2)
     3
     zzz: (+ 1 2 -4)
     -4


File: sizzle-ref.info,  Node: Automatic Interactive Variable,  Next: Command Line Editing,  Prev: Interactive Usage,  Up: Using Sizzle

Automatic Interactive Variable
==============================

   When running the standalone interpreter, Sizzle defines
automatically a special variable to ease interactive usage.  The result
of an evaluation is automatically assigned to the top-level variable
$$, which can be used in following expressions.  Note that the value of
this variable is overwritten after each successul operation, so you
have to save it yourself if you want to use it later.

     zzz: 1
     1
     zzz: $$
     1
     zzz: "foobar"
     "foobar"
     zzz: (string-length $$)
     6


File: sizzle-ref.info,  Node: Command Line Editing,  Next: Sizzle Scripts,  Prev: Automatic Interactive Variable,  Up: Using Sizzle

Command Line Editing
====================

   Note: Readline support has been removed from the Sizzle core, so you
have to install the additional package `sizzleopt' to make use of it.

   When available, Sizzle uses the `readline' library to provide
command line editing to the command line interpreter.

   The `readline' library enables command line editing with the cursor
keys and some key sequences known from Emacs. Also, a command line
history is available, you can recall previously typed in lines with the
cursor-up key.  Tab-completion, known from the shell is supported, too.
When you type the beginning of a word and then hit the <TAB> key, the
word will be completed; when there are several possible matching words,
readline will complete as much as possible and then beep.  You can then
press the <TAB> once more to get a list of the matches.

   Sizzle is a little bit context sensitive with tab-completion. When
the word you are completing comes directly (or only seperated by
whitespace) after an opening parentheses, only procedure names are
completed, in all other positions, variable names are also completed.

   The command line history which is maintained by the `readline' can
be written to the file `.sizzle_history' when Sizzle exits and read in
when it starts again.  By default, this feature is disabled to avoid
filling the home directory of users who do not wish their programs to do
so.  You have to set the boolean variable %WRITE-HISTORY-FILE% to `#t'
to enable command line history saving.  The best place to do so is in
the user initialization file `.sizzle' in the user's home directory.


File: sizzle-ref.info,  Node: Sizzle Scripts,  Next: Startup Sequence,  Prev: Command Line Editing,  Up: Using Sizzle

Sizzle Scripts
==============

   Sizzle is not only suitable for interactive usage, but also for
programming Scheme scripts.  These scripts can manipulate text, can do
numeric calculations or can even be CGI scripts.  Sizzle scripts can
include code from the Sizzle library using the `load' procedure.

   The Sizzle program runs in non-interactive mode if you invoke it with
the `-s' option, like `sizzle -s kewlt-scheme-program.scm'.

   You can run Sizzle scripts without having to type the name of the
Sizzle executable if you include the following two lines at the top of
your script and making the script executable using the `chmod' program:

     #! /usr/local/bin/sizzle -s
     !#

Another possibility is to make the following lines the first ones in
your script.  This version has the advantage that it is independent on
the location of your Sizzle executable, but it is a little bit less
efficient because the operating system has to start a shell, which in
turn starts the Sizzle interpreter.  Normally, the performance
difference will not be noticable, though.

     #! /bin/sh
     exec sizzle -s $0
     !#

   Scheme scripts can examine the arguments they were given by calling
the procedure `command-line'.  It returns a list of strings, each being
one command line argument.  The first member of the list is the name of
the interpreter, or (if you have a more sophisticated Unix flavour and
are using the `#!' notation for executing the interpreter) the name of
the script.


File: sizzle-ref.info,  Node: Startup Sequence,  Next: Environment Variables,  Prev: Sizzle Scripts,  Up: Using Sizzle

Startup Sequence
================

   On startup, the file `init.scm' which was installed together with
the binaries and libraries is loaded before evaluating expressions from
source files or the command line, and before entering the
read-eval-print loop.  `init.scm' is stored in the directory
`$prefix/share/sizzle/$version/', where `$prefix' is set during
configuration time (defaults to `/usr/local') and `$version' is the
version of your installed Sizzle package.

   In addition, the system init file loads the file `.sizzle', if it
exists, from the user's home directory.  So if you like to customize
Sizzle's behaviour, this file is the right one to put Scheme
expressions.

   Note that these startup files are loaded whenever the interpreter
starts up, no matter whether it runs interactively in the
read-eval-print loop or was started to run a Scheme script.

   Loading of the initialization files can be suppressed by using the
command line options `-q, --no-init-file' and `-n,
--no-system-init-file'.  The former inhibits the loading of the user's
initialization file `~/.sizzle', whereas the latter suppresses loading
of the system-wide initialization file.


File: sizzle-ref.info,  Node: Environment Variables,  Next: Building Sizzle,  Prev: Startup Sequence,  Up: Using Sizzle

Environment Variables
=====================

   When Sizzle starts up, it examines the contents of the environment
variable `SIZZLE_LOAD_PATH'.  If it is set, it must contain a
colon-separated list of directory names.  Each of these path names is
then prepended to the global variable %LOAD-PATH, in the order they
appear in the environment variable.  This environment variable makes it
possible to modify the locations where Sizzle searches for files which
are loaded via `load' or `primitive-load-path', or modules which are
included with `use-modules'.


File: sizzle-ref.info,  Node: Building Sizzle,  Prev: Environment Variables,  Up: Using Sizzle

Building Sizzle
===============

   Some notes on building the Sizzle library and interpreter.

   First, you have to get a Sizzle archive. You should be able to get a
recent version from <http://www.pintus.de/mgrabmue/sizzle/sizzle.html>.
Just follow the _Download_ link and download an archive like
`sizzle-0.0.30.tar.gz'.  Replace the version number with the newest
available version.  You may also want to download the _sizzleopt_
package, which includes some useful bindings, such as `readline'
support for the interpreter.

   Unpack the distribution tarball to a directory of your choice:
     $ cd src
     $ tar xzvf sizzle-0.0.30.tar.gz
     sizzle-0.0.30/
     sizzle-0.0.30/Makefile.in
     ...
   Change to the newly created directory.
     $ cd sizzle-0.0.30

   When compiling for Windoze using Micro$oft Visual C, you can use the
provided Project files.  Refer to the `README-Win32' file for further
information.

   Now you have configure the package.  Most of the times, this just
requires you to type
     ./configure
   but you may want to change the configuration to suit your needs.
Invoke `configure' with the `--help' option to get a list of the
supported options.

   Currently, the following configuration options besides the standard
options are supported:
`--enable-warnings'
     Switches on most compiler warnings.  This may be useful for the
     maintainer only or people who want to hack on the package.  This
     is off by default.

`--enable-debug'
     Switch on debugging code.  This is on by default.

`--enable-posix'
     Compile in Posix functions such as `getpid', `fork' etc.  This is
     on by default.

`--enable-regexp'
     Compile in support for Posix regular expressions.  This is on by
     default.

`--enable-maximum-functionality'
     This option controls inclusion of some code which may not be
     needed for all users, such as networking support.

`--enable-dl'
     Compile in dynamic linking code.  This will enable the library to
     load extension modules without recompilation.  This is on by
     default.

`--enable-uvector'
     Enable support for uniform vectors.  They are currently not
     compiled in by default because I do not use them now, and they
     bloat up the library unnecessarily.

`--with-mingw=DIR'
     When compiling for Windoze, you can give the location of your
     MingW32 installation here.

`--enable-shared'
     Enable the compilation of chared libraries.  On by default.

`--enable-static'
     Enable the compilation of static libraries.  On by default.

`--disable-nls'
     Switch off national language support.  You may want to use this if
     your NLS is broken or you simply don't like localized messages.
Every `--enable' option has a `--disable' pendent to switch off a
particular feature.

   After a while, the configuration is done and you can compile the
package.
     $ make

   When compiled, the package is ready for installation.  Note that only
the super-user may do this if you are installing to the default location
`/usr/local'.
     $ su
     Password:
     # make install
     # exit
     $

   When everything worked well, you can now use the Sizzle interpreter.
     $ sizzle
     zzz: (+ 1 2)
     3
     zzz:


File: sizzle-ref.info,  Node: Programming Scheme,  Next: Predefined Variables,  Prev: Using Sizzle,  Up: Top

Programming Scheme
******************

   This chapter gives a quick introduction to programming in the Scheme
language.  It will also mention Sizzle limitations and features where
appropriate.

* Menu:

* General::                     Basics about Scheme programming
* Storage Model::               Storage model used by the Sizzle interpreter
* Data Types::                  Available data types and their usage


File: sizzle-ref.info,  Node: General,  Next: Storage Model,  Prev: Programming Scheme,  Up: Programming Scheme

General
=======

   Scheme uses fully parenthesized prefix notation, that means that all
procedure calls are enclosed in parentheses.  The first element in a
procedure call is the procedure which will be invoked and the other
elements are the arguments which will be passed to the procedure.  Note
that the procedure will be evaluated in the same way as the rest
parameters.

     zzz: (+ 1 2)
     3
     zzz: ((lambda (x) x) 1)
     1

All arguments in Scheme are passed by value, e.g evaluated before the
procedure is called.  Special forms like `if', `define' etc. do not
follow that rule, they evaluate their arguments only when needed.
There is no syntactic difference between a procedure call and the
application of a special form, so you need to know the names of all
special forms in order to tell how some given code will evaluate.

   Variables are defined using the special form `define' and can be
modified lateron by using `set!', which is another special form.

     zzz: (define a 1)
     zzz: a
     1
     zzz: (set! a 2)
     zzz: a
     2

Functions are either defined by defining a variable with the value of a
lambda expression or using a special form of `define', which is
intended for defining procedures more easily.

     zzz: (define identity (lambda (x) x))
     zzz: (identity 2)
     2
     zzz: (exit)
     $ sizzle
     zzz: (define (identity x) x)
     zzz: (identity 3)
     3

When you define a variable more than once in an environment, the former
definition will be silently overwritten.


File: sizzle-ref.info,  Node: Storage Model,  Next: Data Types,  Prev: General,  Up: Programming Scheme

Storage Model
=============

   The Sizzle core contains a garbage collector, so that the programmer
is not responsible to free objects which are not needed anymore.
Internally, the garbage collector is implemented as a conservative
collector which marks all objects as being used which are reachable
through global variables (known to the collector) or are reachable by
scanning the C stack.

   At the moment, the garbage collector is a very simple, recursive
mark-and-sweep collector, without generations or incremental behaviour.
It has been sufficient for my needs, but maybe I will switch to a more
sophisticated algorithm later when a need for it apears.


File: sizzle-ref.info,  Node: Data Types,  Prev: Storage Model,  Up: Programming Scheme

Data Types
==========

   Sizzle has a lot of useful data types already built in, and provides
a lot of procedures for manipulating values of various types.  For
detailed description of the available data manipulation functions please
refer to the Programming Reference chapter in this manual.

* Menu:

* Numbers::                     Numeric data types
* Booleans::                    Boolean data type
* Characters::                  Character data type
* Strings::                     String data type
* Symbols::                     Symbol data type
* Keywords::                    Keywords data type
* Cons Cells::                  Cells of two values
* Vectors::                     Vectors of values
* Homogenous numeric vectors::  Numeric vectors with type safety
* Hash tables::
* Procedures::                  Functions and syntactic forms
* Regular Expressions::         Regular expressions for matching text
* Multiple Values::             Returning multiple values from procedures
* Special values::              Special values in the interpreter
* Constants::                   Defined constants
* Ports::                       Input and output facilities
* Errors and Exceptions::       Sizzle error and exception concept
* Continuations::               Evaluation continuations
* Boxes::                       Box data type
* Pointers::                    Pointer data type


File: sizzle-ref.info,  Node: Numbers,  Next: Booleans,  Prev: Data Types,  Up: Data Types

Numbers
-------

   The Scheme standard defines the so-called numeric tower, a hierarchy
of numeric data types where every data type includes the values of the
data types lower in the hierarchy and which is defined as follows:

`number'
     All numbers belong to the data type number.

`complex'
     Complex numbers consist of a real and an imaginary part.

`real'
     Real numbers are all rational and irrational numbers.

`rational'
     Rational numbers consist of a numerator and a denominator.

`integer'
     Integers are all numbers without a fraction component.

   Furthermore, Scheme makes a difference between exact and inexact
numbers.  Exact numbers are always precise whereas inexact numbers are
only an approximation.  The same differentiation is made for operations
on numbers.  For example, the addition of two exact numbers always
produces an exact result, but on the contrary, the division of exact
numbers may be inexact.

   The read syntax for numbers is as follows: the number may starts
with an optional number of exactness and radix , followed by a number
of digits which must fit into the radix scheme which may be given with
a radix prefix.  Then a decimal point and another sequence of numbers
may follow, in decimal or scientific notation may follow.  A list of the
valid exactness and radix prefices is given in the following table.

`#e'
     Number is exact

`#i'
     Number is inexact

`#b'
     Binary number, radix 2

`#o'
     Octal number, radix 8

`#d'
     Decimal number, radix 10

`#x'
     Hexadecimal number, radix 16

   Integers are exact numbers with the same range as the C `long' data
type.

   Examples of integer constants:
     42
     -23
     #xdead
     #o755
     #b100001010
     #d42

   Floats are floating point values, corresponding to `double' values
in C. Real number constants can start with a radix and exactness prefix,
but only the radix prefix `#d' is allowed. When using the exactness
prefix `#e' (exact number), the number must have a fraction of zero.
Read syntax examples:

     3.1459
     -10.1e2
     #i1.0
     #e1.0

   Complex and rational numbers are not supported by Sizzle.  Maybe in
the future they will.  Also bignums (arbitrary precision numbers), as
known from other Scheme systems, are not (yet) supported.


File: sizzle-ref.info,  Node: Booleans,  Next: Characters,  Prev: Numbers,  Up: Data Types

Booleans
--------

   Booleans are the truth values true and false, in Scheme written like
this: `#t' means true and `#f' means false.

   In Scheme, `#f' is the only value that is considered false in
conditionals, neither `0' nor the empty list `'()' counts as false.


File: sizzle-ref.info,  Node: Characters,  Next: Strings,  Prev: Booleans,  Up: Data Types

Characters
----------

   Characters are denotated in the following form: first, a hash mark
(`#'), then a backslash and then the literal character. Examples:
`#\j'
     The character `j'

`#\'
     The space character

   Scheme provides another notation for non-printable characters. A
space character can also be written like this `#\space' and a newline
like `#\newline'. Sizzle understands three additional symbolic names
for characters. This table shows all of them:
`#\space'
     The space character

`#\newline'
     The newline character

`#\return'
     The carriage return character

`#\tab'
     The tab character.

`#\bell'
     The bell character.


File: sizzle-ref.info,  Node: Strings,  Next: Symbols,  Prev: Characters,  Up: Data Types

Strings
-------

   Strings are sequences of characters. String constants are enclosed in
double quotes and can contain all characters from the ASCII set.  The
double quote character `"' and the backslash `\' have to be quoted with
a preceding backslash.  Some special non-printable characters can be
included in string constants by denoting special backslash-character
sequences. The following sequences are defined:
`\n'
     Newline

`\r'
     Carriage return

`\t'
     Tab character

`\v'
     Vertical tab

`\b'
     Backspace

`\a'
     Bell character

   Strings can be mutable and immutable.  Immutable are those which were
literally entered from the input source.  They can not be used with
destructive procedures like `string-set!' or `string-fill!'.  Strings
returned by functions like `string-copy' or `string' are mutable and
can be used with such strings.


File: sizzle-ref.info,  Node: Symbols,  Next: Keywords,  Prev: Strings,  Up: Data Types

Symbols
-------

   Symbols are values with some special properties. They are written by
simply writing their name, without any quotes or special markup
characters.  The main difference between symbols and strings is that
symbols which have the same textual representation are in fact the same
object.  Additionally, symbols can have values associated to them, then
they act as variables.

   When reading symbols, the Sizzle reader considers all characters
which do not explicitly end the symbol as part of the symbol. These
ending characters are `(', `)', whitespace, `;' and `"'. It is even
possible to include these characters into a symbol name by preceeding
it with a backslash.  Thus, these all are valid symbol names:
     Hello
     i-am-a-symbol
     strange\ symbol

   Of course, it is not too clever to use symbols with enclosed
whitespace or parentheses in program source code.  Their use can degrade
readability of programs considerably.


File: sizzle-ref.info,  Node: Keywords,  Next: Cons Cells,  Prev: Symbols,  Up: Data Types

Keywords
--------

   Keywords are similar to symbols in that they are represented
externally by a character sequence and that keywords with the same
external representation are indeed the same objects internally.  The
difference between keywords and symbols is that symbols are normally
bound to locations containing values and that these values are
retrieved when a symbols is evaluated, whereas keywords evaluate to
themselves.  Thus it is not necessary to quote keywords on input.

   Keywords are written like symbols, but are either prefixed with a
colon (`:') or the sequence hashmark-colon (`#:').  When comparing,
only the keyword name is significant, the prefix is ignored.

     zzz: #:keyword
     #:keyword
     zzz: :keyword
     #:keyword
     zzz: keyword
     error: unbound variable: keyword

   In the above example you can see how keywords evaluate to themselves
and that evaluating an unknown symbol signals an error.  Note also that
keywords are always printed in the `#:'-notation, regardless how they
were entered.


File: sizzle-ref.info,  Node: Cons Cells,  Next: Vectors,  Prev: Keywords,  Up: Data Types

Cons Cells
----------

   Cons cells are cells which can hold two other values.  The first of
the value is called the `car' of the cell and the second is called
`cdr' (for historic reasons). In source files and on the
read-eval-print prompt you can create cons cell by using the "dotted
pair" syntax.
     '(foo . bar)
     '(1 . 2)

Another way to create cons cells is using the constructor function
`cons':
     zzz: (cons 1 2)
     (1 . 2)

   Lists, the main data structure in Sizzle are also made out of cons
cells, but they can be typed in a more convenient way than
     (1 . (2 . (3 . '())))

by simply writing
     (1 2 3)

Both result in the same value.


File: sizzle-ref.info,  Node: Vectors,  Next: Homogenous numeric vectors,  Prev: Cons Cells,  Up: Data Types

Vectors
-------

   Vectors are similar to arrays in other programming languages. You can
store a fixed count of values in a vector and can access them in
constant time, as opposed to the time for accessing elements of a list,
which is linear to the list length.  The difference to ordinary arrays
is that the elements of a vector can have different types.

   Vectors are written like lists, but before the opening parentheses
you have to put a hash mark.
     #(1 2 3 4 5 6 7)
     #("Hello" #\  "World" \#!)
     #(#(1 2) #())

The last example shows that vectors may contain vectors and that vectors
may be empty.

   Vectors can be mutable and immutable.  Immutable are those which were
literally entered from the input source.  They can not be used with
destructive procedures like `vector-set!' or `vector-fill'.  Vectors
returned by functions like `make-vector' or `vector' are mutable and
can be used with such strings.


File: sizzle-ref.info,  Node: Homogenous numeric vectors,  Next: Hash tables,  Prev: Vectors,  Up: Data Types

Homogenous numeric vectors
--------------------------

   Note: Currently, homogenous numeric vectors are only available if
support for them has been explicitly enabled on configuration time for
the package.  See *Note Building Sizzle:: for how to enable the support
if your installed version lacks it and you need it.

   Normal Scheme vectors are heterogenous datatypes.  You can store any
value in them, just as you can with lists.  Sizzle provides another kind
of vectors, so-called homogenous numeric datatypes, as defined in
SRFI-4.  These vectors are special, because it is only possible to store
numbers of a particular data type in there.  There are 10 different
types of those vectors, each for another numeric data type: signed 8-bit
values, unsigned 8-bit values, signed 16-bit values, unsigned 16-bit
values, signed 32-bit values, unsigned 32-bit values, signed 64-bit
values, unsigned 64-bit values, 32-bit floating point values and 64-bit
floating point values.  Only values of their type can be stored into
these vectors, so they provide additional type safety.  They are also
more space-efficient, because, for example, vectors of signed 8-bit
quantities need only to reserve 8 bits for each elements, whereas normal
vectors reserve at least 32 bit for eacht element, up to 160 bits.

   Each of the data types has its own type prefix, which is used in all
procedures dealing with that type.  The following table defines the
prefixes.
s8
     signed 8-bit values

u8
     unsigned 8-bit values

s16
     signed 16-bit values

u16
     unsigned 16-bit values

s32
     signed 32-bit values

u32
     unsigned 32-bit values

s64
     signed 64-bit values

u64
     unsigned 64-bit values

f32
     32-bit floating point values

f64
     64-bit floating point values

   Homogenous numeric vectors have a read (and print) syntax similar to
vectors, but between the hash mark and the opening parentheses the
prefix for the vector type must be inserted:

     #u8(1 2 3 4 5 6 7)
     #s16(-42 23 2 0)
     #f32(1.2 3.14159265)

Similar to normal vectors, literally denoted homogenous vectors are
read-only and can not be modified using primitive procedures like
`u8vector-set!'.  Use procedures like `make-f64vector' to create
mutable vectors.


File: sizzle-ref.info,  Node: Hash tables,  Next: Procedures,  Prev: Homogenous numeric vectors,  Up: Data Types

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

   Hash tables (aka associative arrays) are very useful data structures,
when a non-trivial programming task is at hand.  Hash tables provide a
mapping from one object to another and are similar to _association
lists_, but they are significantly faster when they grow large.

   In Sizzle, hash tables can be written literally with a `#{' prefix,
followed by key/value pairs separated by the arrow symbol (`=>'), like
this, terminated by a closing brace (`}'):
     zzz: #{Joe => "cool" Jim => "lame"}
     #{Jim => "lame" Joe => "cool"}
   This is also the print syntax for hash tables.

   Another possibility is to use the procedure `make-hash' which
constructs a hash table from its arguments.  All arguments must be pairs
which will be taken as key/value pairs and inserted in the new hash
table.
     zzz: (make-hash '(Joe . "cool") '(Jim . "lame"))
     #{Jim => "lame" Joe => "cool"}

   Note that the order of the key/value pairs depends on the size of the
data structure internally used to store the values and may differ for
the same input, when this size is not the same.  The size is either
chosen internally, depending on the number of pairs, or can be provided
as an optional first argument to `make-hash':
     zzz: (make-hash '(Joe . "cool") '(Jim . "lame"))
     #{Jim => "lame" Joe => "cool"}
     zzz: (make-hash 32 '(Joe . "cool") '(Jim . "lame"))
     #{Joe => "cool" Jim => "lame"}
   The best choice for the size argument is a prime number not too near
to a power of 2 (so says Knuth).


File: sizzle-ref.info,  Node: Procedures,  Next: Regular Expressions,  Prev: Hash tables,  Up: Data Types

Procedures
----------

   There are three kinds of procedures in Sizzle: Builtin procedures,
builtin syntactic forms and user-defined procedures (lambda
expressions, or closures).

   The difference between builtin functions and syntactic forms is that
funtions evaluate their arguments before theu are called and arguments
to syntactic forms are only evaluated when needed.

   Builtin functions and syntactic forms do not have any read syntax
(that would not make sense) and they print in the following way:
     zzz: set!
     #<macro set!>
     zzz: append
     #<primitive-procedure append>

   Closures print as a pair of the lambda expression they stand for and
the address of the environment the expression is closed over.
     zzz: (define (f n) n)
     zzz: f
     #<closure #<procedure f (n)> 0x401af072>


File: sizzle-ref.info,  Node: Regular Expressions,  Next: Multiple Values,  Prev: Procedures,  Up: Data Types

Regular Expressions
-------------------

   Regular expressions are created using the primitive procedure
`make-regexp'.  The resulting regular expression object can then be
used in calls to `regexp-exec' in order to match the regular expression
against strings.  The format of the regular expression passed to
`make-regexp' is the same as for the Posix regular expressions.  For
more information, type
     man regex

Regular expressions are not part of any Scheme standard, but the
procedures implemented in Sizzle are compatible to those used by Guile.

     zzz: (define rx (make-regexp "foo|bar"))
     zzz: (regexp-exec rx "a-foo-baz")
     #("a-foo" (2 . 5))
     zzz: (regexp-exec rx "bar-o-matic")
     #("bar" (0 . 3))

   Due to limitations in the interface of Posix regular expressions,
regular expressions in Sizzle may not contain null bytes.  Pattern
strings are truncated at the first null byte on compilation.


File: sizzle-ref.info,  Node: Multiple Values,  Next: Special values,  Prev: Regular Expressions,  Up: Data Types

Multiple Values
---------------

   In Scheme, it is possible to return more than one value from a
procedure.  This is done by using the primitive procedure `values' as
the last expression in your procedure.  Handling those values when
returned from a procedure is a bit strange, since the only standard form
defined for that purpose is `call-with-values'.  The following examples
may (hopefully) clear up the whole mess.

     zzz: (values 1 2 3)
     1
     2
     3
     zzz: (call-with-values (lambda () (values 1 2)) (lambda (x y) (+ x y)))
     3

When multiple values are returned to the read-eval-print loop, they are
printed one after the other, every value on a new line.  The second
example shows the usage of `call-with-values', where the first lambda
expression is evaluated (and returns multiple values) and the values
returned from the first procedure are passed to the second procedure as
normal arguments.


File: sizzle-ref.info,  Node: Special values,  Next: Constants,  Prev: Multiple Values,  Up: Data Types

Special values
--------------

   Some values which appear in the interpreter are different from all
others and cannot be assigned to one of the data types.  These values
are referred to as "Special Values" in this manual.  Examples of these
special values are the `end-of-file' object which indicates an
end-of-file condition, or the `unspecified' object used inside of the
interpreter.


File: sizzle-ref.info,  Node: Constants,  Next: Ports,  Prev: Special values,  Up: Data Types

Constants
---------

   Sizzle supports a weird data type for constants.  They can represent
any Scheme object, but have the additional property that references to
constants are replaced by their value when they are evaluated in a
procedure body.  The result is faster execution, because the necessary
lookup step for variables is eliminated.  Constants are created with the
syntactic form `define-constant' and can be used by variable, once they
are defined.

   Notice that due to the substitution feature, it is not possible to
redefine a constant.  But would it be a constant then?


File: sizzle-ref.info,  Node: Ports,  Next: Errors and Exceptions,  Prev: Constants,  Up: Data Types

Ports
-----

   All input and output in Scheme is done using "ports", which can be
regarded as data sources and sinks.  Ports are characterized by the fact
that they provide procedures for reading and writing data, telling and
setting file pointer positions (if they are built on top of files) and
various others.  Ports are either created explicitly by calls to
procedures like `open-input-file', or implicitely when using
`with-output-to-string' and friends.  They have a print syntax, but no
read syntax.

     zzz: (current-input-port)
     #<rlport:open=1:read=1:write=0>
     zzz: (current-output-port)
     #<fdport:open=1:read=0:write=1:fd=1>
   The first port in this example is a readline port, which supports
command line editing, parentheses matching etc., the second is a normal
file descriptor port connected to the standard output file descriptor.

   Note that readline ports are only available if you have installed the
`sizzleopt' package and used the readline module with `(use-modules
(readline readlie))'.

   At the moment, Sizzle supports so-called "fdports", which use an
underlying file descriptor, "fports" which use an underlying `stdio'
file structure, string ports which use an internal character buffer for
input and output, and rlports (readline ports) which read from the
terminal via the `readline' library.  The latter provide fancy command
line editing.


File: sizzle-ref.info,  Node: Errors and Exceptions,  Next: Continuations,  Prev: Ports,  Up: Data Types

Errors and Exceptions
---------------------

   Errors and Exceptions are distinct data types in Sizzle.  Whenever an
error occurs (such as when you pass the wrong number of arguments to a
procedure), an error object is created and then propagated to the top
level, which may be either the read-eval-print loop or a procedure
evaluating a file.  There the error is displayed, using the information
in the error object.  In an error object, an error message is stored,
and if the error comes from the reader module, a file name and a line
and column number is also included.  Error objects can not explicitly
created, but they are created whenever you use the `error' procedure to
signal an error.

   Exceptions are a bit different.  When raised, they also create
objects containing an error message, but they also contain a so-called
exception tag, which may be any atom.  Exceptions can be raised from
the Scheme code by calling the procedure `throw'.  Using the exception
tag for a particular exception or the catch-all exception tag `#t', the
user can catch exceptions with the procedure `catch'.

   The rule of thumb is that exceptions are raised when an error
situation allows continued evaluation, and errors are signalled on
errors which are too serious to continue.  An examples for exceptions
is the `file-not-found' exception, which is raised when a non-existent
file is opened; a quite common situation.  Errors are signalled on
syntax errors, invalid procedure application or typing errors.

   Right now, the difference between exceptions and errors in the Sizzle
core is a bit half-baked.  Not all continuable error situations throw
exceptions, a lot of them unnecessarily signal errors.  This will be
changed in the future.  Currently, support for errors is slowly phased
out and all error-signalling places in the code are changed to throw
various types of exceptions instead.


File: sizzle-ref.info,  Node: Continuations,  Next: Boxes,  Prev: Errors and Exceptions,  Up: Data Types

Continuations
-------------

   Sizzle only supports continuations usable as escape procedures.  That
means that one cannot export a continuation from the defining context by
returning it from a procedure or storing it into a global variable, and
then try to invoke it.


File: sizzle-ref.info,  Node: Boxes,  Next: Pointers,  Prev: Continuations,  Up: Data Types

Boxes
-----

   Boxes are a data type which are used to store other Scheme objects.
A box simply contains another object and can be used to pass objects to
procedures in a style similar to call-by-reference calling semantics.

   Boxes are created with a call to the procedure `make-box', which
takes the object to store into the box.  The contained object can be
retrieved from a box with `box-ref' and set with `box-set!'.  The
predicate `box?' is used to check whether a given object is actually a
box.  For more details on these procedures, see *Note Box Operations::.


File: sizzle-ref.info,  Node: Pointers,  Prev: Boxes,  Up: Data Types

Pointers
--------

   Sizzle provides a special data type called _pointer_.  Objects of
this type wrap so-called bounded pointers, that means that they contain
a pointer into the machine's address space together with the size of the
object pointed to.  These objects are used when interfacing to C library
functions which receive character buffers.  Pointer objects created with
the primitive procedure `make-pointer' allocate memory when created and
release the allocated memory when the pointer object gets unreachable.
For more information about pointer procedures, refer to *Note Pointer
Operations::.

