1439 lines
50 KiB
TeX
1439 lines
50 KiB
TeX
|
|
% Still to do:
|
|
% list utilities
|
|
% rest of big-util
|
|
% destructure
|
|
% format (?)
|
|
|
|
\chapter{Libraries}
|
|
|
|
Use the
|
|
\link*{\code{,open} command}
|
|
[\code{,open} command (section~\Ref{})]{module-command-guide}
|
|
or
|
|
\link*{the module language}
|
|
[the module language (chapter~\Ref)]{module-guide}
|
|
to open the structures described below.
|
|
|
|
\section{ASCII character encoding}
|
|
\label{ascii-procedures}
|
|
|
|
These are in the structure \code{ascii}.
|
|
|
|
\begin{protos}
|
|
\proto{char->ascii}{ char}{integer}
|
|
\proto{ascii->char}{ integer}{char}
|
|
\end{protos}
|
|
\noindent
|
|
These are identical to \code{char->integer} and \code{integer->char} except that
|
|
they use the
|
|
\link{ASCII encoding}[ASCII encoding (appendix~\Ref)]{ascii-chart}.
|
|
|
|
\begin{protos}
|
|
\constproto{ascii-limit}{integer}
|
|
\constproto{ascii-whitespaces}{list of integers}
|
|
\end{protos}
|
|
\code{Ascii-limit} is one more than the largest value that \code{char->ascii}
|
|
may return.
|
|
\code{Ascii-whitespaces} is a list of the ASCII values of whitespace characters
|
|
(space, horizontal tab, line feed (= newline), vertical tab, form feed, and
|
|
carriage return).
|
|
|
|
\section{Bitwise integer operations}
|
|
|
|
These functions use the two's-complement representation for integers.
|
|
There is no limit to the number of bits in an integer.
|
|
They are in the structures \code{bitwise} and \code{big-scheme}.
|
|
|
|
\begin{protos}
|
|
\proto{bitwise-and}{ integer integer}{integer}
|
|
\proto{bitwise-ior}{ integer integer}{integer}
|
|
\proto{bitwise-xor}{ integer integer}{integer}
|
|
\proto{bitwise-not}{ integer} {integer}
|
|
\end{protos}
|
|
\noindent
|
|
These perform various logical operations on integers on a bit-by-bit
|
|
basis. `\code{ior}' is inclusive OR and `\code{xor}' is exclusive OR.
|
|
|
|
\begin{protos}
|
|
\proto{arithmetic-shift}{ integer bit-count}{integer}
|
|
\end{protos}
|
|
\noindent Shifts the integer by the given bit count, which must be an integer,
|
|
shifting left for positive counts and right for negative ones.
|
|
Shifting preserves the integer's sign.
|
|
|
|
\begin{protos}
|
|
\proto{bit-count}{ integer}{integer}
|
|
\end{protos}
|
|
\noindent Counts the number of bits set in the integer.
|
|
If the argument is negative a bitwise NOT operation is performed
|
|
before counting.
|
|
|
|
\section{Byte vectors}
|
|
|
|
These are homogeneous vectors of small integers ($0 \le i \le 255$).
|
|
The functions that operate on them are analogous to those for vectors.
|
|
They are in the structure \code{byte-vectors}.
|
|
|
|
\begin{protos}
|
|
\proto{byte-vector?}{ value}{boolean}
|
|
\proto{make-byte-vector}{ k fill}{byte-vector}
|
|
\proto{byte-vector}{ i \ldots}{byte-vector}
|
|
\proto{byte-vector-length}{ byte-vector}{integer}
|
|
\proto{byte-vector-ref}{ byte-vector k}{integer}
|
|
\protonoresult{byte-vector-set!}{ byte-vector k i}
|
|
\end{protos}
|
|
|
|
\section{Cells}
|
|
|
|
These hold a single value and are useful when a simple indirection is
|
|
required.
|
|
The system uses these to hold the values of lexical variables that
|
|
may be \code{set!}.
|
|
|
|
\begin{protos}
|
|
\proto{cell?}{ value}{boolean}
|
|
\proto{make-cell}{ value}{cell}
|
|
\proto{cell-ref}{ cell}{value}
|
|
\protonoresult{cell-set!}{ cell value}
|
|
\end{protos}
|
|
|
|
\section{Queues}
|
|
|
|
These are ordinary first-in, first-out queues.
|
|
The procedures are in structure \code{queues}.
|
|
|
|
\begin{protos}
|
|
\proto{make-queue}{}{queue}
|
|
\proto{queue?}{ value}{boolean}
|
|
\proto{queue-empty?}{ queue}{boolean}
|
|
\protonoresult{enqueue!}{ queue value}
|
|
\proto{dequeue!}{ queue}{value}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Make-queue} creates an empty queue, \code{queue?} is a predicate for
|
|
identifying queues, \code{queue-empty?} tells you if a queue is empty,
|
|
\code{enqueue!} and \code{dequeue!} add and remove values.
|
|
|
|
\begin{protos}
|
|
\proto{queue-length}{ queue}{integer}
|
|
\proto{queue->list}{ queue}{values}
|
|
\proto{list->queue}{ values}{queue}
|
|
\proto{delete-from-queue!}{ queue value}{boolean}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Queue-length} returns the number of values in \var{queue}.
|
|
\code{Queue->list} returns the values in \var{queue} as a list, in the
|
|
order in which the values were added.
|
|
\code{List->queue} returns a queue containing \var{values}, preserving
|
|
their order.
|
|
\code{Delete-from-queue} removes the first instance of \var{value} from
|
|
\code{queue}, using \code{eq?} for comparisons.
|
|
\code{Delete-from-queue} returns \code{\#t} if \var{value} is found and
|
|
\code{\#f} if it is not.
|
|
|
|
\section{Arrays}
|
|
|
|
These provide N-dimensional, zero-based arrays and
|
|
are in the structure \code{arrays}.
|
|
The array interface is derived from one invented by Alan Bawden.
|
|
|
|
\begin{protos}
|
|
\proto{make-array}{ value dimension$_0$ \ldots}{array}
|
|
\proto{array}{ dimensions element$_0$ \ldots}{array}
|
|
\proto{copy-array}{ array}{array}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Make-array} makes a new array with the given dimensions, each of which
|
|
must be a non-negative integer.
|
|
Every element is initially set to \cvar{value}.
|
|
\code{Array} Returns a new array with the given dimensions and elements.
|
|
\cvar{Dimensions} must be a list of non-negative integers,
|
|
The number of elements should be the equal to the product of the
|
|
dimensions.
|
|
The elements are stored in row-major order.
|
|
\begin{example}
|
|
(make-array 'a 2 3) \evalsto \{Array 2 3\}
|
|
|
|
(array '(2 3) 'a 'b 'c 'd 'e 'f)
|
|
\evalsto \{Array 2 3\}
|
|
\end{example}
|
|
|
|
\code{Copy-array} returns a copy of \cvar{array}.
|
|
The copy is identical to the \cvar{array} but does not share storage with it.
|
|
|
|
\begin{protos}
|
|
\proto{array?}{ value}{boolean}
|
|
\end{protos}
|
|
\noindent
|
|
Returns \code{\#t} if \cvar{value} is an array.
|
|
|
|
\begin{protos}
|
|
\proto{array-ref}{ array index$_0$ \ldots}{value}
|
|
\protonoresult{array-set!}{ array value index$_0$ \ldots}
|
|
\proto{array->vector}{ array}{vector}
|
|
\proto{array-dimensions}{ array}{list}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Array-ref} returns the specified array element and \code{array-set!}
|
|
replaces the element with \cvar{value}.
|
|
\begin{example}
|
|
(let ((a (array '(2 3) 'a 'b 'c 'd 'e 'f)))
|
|
(let ((x (array-ref a 0 1)))
|
|
(array-set! a 'g 0 1)
|
|
(list x (array-ref a 0 1))))
|
|
\evalsto '(b g)
|
|
\end{example}
|
|
|
|
\code{Array->vector} returns a vector containing the elements of \cvar{array}
|
|
in row-major order.
|
|
\code{Array-dimensions} returns the dimensions of
|
|
the array as a list.
|
|
|
|
\begin{protos}
|
|
\proto{make-shared-array}{ array linear-map dimension$_0$ \ldots}{array}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Make-shared-array} makes a new array that shares storage with \cvar{array}
|
|
and uses \cvar{linear-map} to map indexes to elements.
|
|
\cvar{Linear-map} must accept as many arguments as the number of
|
|
\cvar{dimension}s given and must return a list of non-negative integers
|
|
that are valid indexes into \cvar{array}.
|
|
<\begin{example}
|
|
(array-ref (make-shared-array a f i0 i1 ...)
|
|
j0 j1 ...)
|
|
\end{example}
|
|
is equivalent to
|
|
\begin{example}
|
|
(apply array-ref a (f j0 j1 ...))
|
|
\end{example}
|
|
|
|
As an example, the following function makes the transpose of a two-dimensional
|
|
array:
|
|
\begin{example}
|
|
(define (transpose array)
|
|
(let ((dimensions (array-dimensions array)))
|
|
(make-shared-array array
|
|
(lambda (x y)
|
|
(list y x))
|
|
(cadr dimensions)
|
|
(car dimensions))))
|
|
|
|
(array->vector
|
|
(transpose
|
|
(array '(2 3) 'a 'b 'c 'd 'e 'f)))
|
|
\evalsto '(a d b e c f)
|
|
\end{example}
|
|
|
|
\section{Records}
|
|
\label{records}
|
|
|
|
New types can be constructed using the \code{define-record-type} macro
|
|
from the \code{define-record-types} structure
|
|
The general syntax is:
|
|
\begin{example}
|
|
(define-record-type \cvar{tag} \cvar{type-name}
|
|
(\cvar{constructor-name} \cvar{field-tag} \ldots)
|
|
\cvar{predicate-name}
|
|
(\cvar{field-tag} \cvar{accessor-name} [\cvar{modifier-name}])
|
|
\ldots)
|
|
\end{example}
|
|
This makes the following definitions:
|
|
\begin{protos}
|
|
\constprotonoindex{\cvar{type-name}}{type}
|
|
\protonoindex{\cvar{constructor-name}}{ field-init \ldots}{type-name}
|
|
\protonoindex{\cvar{predicate-name}}{ value}{boolean}
|
|
\protonoindex{\cvar{accessor-name}}{ type-name}{value}
|
|
\protonoresultnoindex{\cvar{modifier-name}}{ type-name value}
|
|
\end{protos}
|
|
\noindent
|
|
\cvar{Type-name} is the record type itself, and can be used to
|
|
specify a print method (see below).
|
|
\cvar{Constructor-name} is a constructor that accepts values
|
|
for the fields whose tags are specified.
|
|
\cvar{Predicate-name} is a predicate that returns \code{\#t} for
|
|
elements of the type and \code{\#f} for everything else.
|
|
The \cvar{accessor-name}s retrieve the values of fields,
|
|
and the \cvar{modifier-name}'s update them.
|
|
\cvar{Tag} is used in printing instances of the record type and
|
|
the \cvar{field-tag}s are used in the inspector and to match
|
|
constructor arguments with fields.
|
|
|
|
\begin{protos}
|
|
\protonoresult{define-record-discloser}{ type discloser}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Define-record-discloser} determines how
|
|
records of type \cvar{type} are printed.
|
|
\cvar{Discloser} should be procedure which takes a single
|
|
record of type \cvar{type} and returns a list whose car is
|
|
a symbol.
|
|
The record will be printed as the value returned by \cvar{discloser}
|
|
with curly braces used instead of the usual parenthesis.
|
|
|
|
For example
|
|
\begin{example}
|
|
(define-record-type pare :pare
|
|
(kons x y)
|
|
pare?
|
|
(x kar set-kar!)
|
|
(y kdr))
|
|
\end{example}
|
|
defines \code{kons} to be a constructor, \code{kar} and \code{kdr} to be
|
|
accessors, \code{set-kar!} to be a modifier, and \code{pare?} to be a predicate
|
|
for a new type of object.
|
|
The type itself is named \code{:pare}.
|
|
\code{Pare} is a tag used in printing the new objects.
|
|
|
|
By default, the new objects print as \code{\#\{Pare\}}.
|
|
The print method can be modified using \code{define-record-discloser}:
|
|
\begin{example}
|
|
(define-record-discloser :pare
|
|
(lambda (p) `(pare ,(kar p) ,(kdr p))))
|
|
\end{example}
|
|
will cause the result of \code{(kons 1 2)} to print as
|
|
\code{\#\{Pare 1 2\}}.
|
|
|
|
\link*{\code{Define-record-resumer}}
|
|
[\code{Define-record-resumer} (section~\Ref{})]
|
|
{sec:hibernation}
|
|
can be used to control how records are stored in heap images.
|
|
|
|
\subsection{Low-level access to records}
|
|
|
|
Records are implemented using primitive objects exactly analogous
|
|
to vectors.
|
|
Every record has a record type (which is another record) in the first slot.
|
|
Note that use of these procedures, especially \code{record-set!}, breaks
|
|
the record abstraction described above; caution is advised.
|
|
|
|
These procedures are in the structure \code{records}.
|
|
|
|
\begin{protos}
|
|
\proto{make-record}{ n value}{record}
|
|
\proto{record}{ value \ldots}{record-vector}
|
|
\proto{record?}{ value}{boolean}
|
|
\proto{record-length}{ record}{integer}
|
|
\proto{record-type}{ record}{value}
|
|
\proto{record-ref}{ record i}{value}
|
|
\protonoresult{record-set!}{ record i value}
|
|
\end{protos}
|
|
\noindent
|
|
These the same as the standard \code{vector-} procedures except that they
|
|
operate on records.
|
|
The value returned by \code{record-length} includes the slot holding the
|
|
record's type.
|
|
\code{(record-type \cvar{x})} is equivalent to \code{(record-ref \cvar{x} 0)}.
|
|
|
|
\subsection{Record types}
|
|
|
|
Record types are themselves records of a particular type (the first slot
|
|
of \code{:record-type} points to itself).
|
|
A record type contains four values: the name of the record type, a list of
|
|
the names its fields, and procedures for disclosing and resuming records
|
|
of that type.
|
|
Procedures for manipulating them are in the structure \code{record-types}.
|
|
|
|
\begin{protos}
|
|
\proto{make-record-type}{ name field-names}{record-type}
|
|
\proto{record-type?}{ value}{boolean}
|
|
\proto{record-type-name}{ record-type}{symbol}
|
|
\proto{record-type-field-names}{ record-type}{symbols}
|
|
\end{protos}
|
|
\noindent
|
|
|
|
\begin{protos}
|
|
\proto{record-constructor}{ record-type field-names}{procedure}
|
|
\proto{record-predicate}{ record-type}{procedure}
|
|
\proto{record-accessor}{ record-type field-name}{procedure}
|
|
\proto{record-modifier}{ record-type field-name}{procedure}
|
|
\end{protos}
|
|
\noindent
|
|
These procedures construct the usual record-manipulating procedures.
|
|
\code{Record-constructor} returns a constructor that is passed the initial
|
|
values for the fields specified and returns a new record.
|
|
\code{Record-predicate} returns a predicate that return true when passed
|
|
a record of type \cvar{record-type} and false otherwise.
|
|
\code{Record-accessor} and \code{record-modifier} return procedures that
|
|
reference and set the given field in records of the approriate type.
|
|
|
|
\begin{protos}
|
|
\protonoresult{define-record-discloser}{ record-type discloser}
|
|
\protonoresult{define-record-resumer}{ record-type resumer}
|
|
\end{protos}
|
|
\noindent
|
|
\noindent \code{Record-types} is the initial exporter of
|
|
\code{define-record-discloser}
|
|
(re-exported by \code{define-record-types} described above)
|
|
and
|
|
\code{define-record-resumer}
|
|
(re-exported by
|
|
\link*{\code{external-calls}}
|
|
[\code{external-calls} (section~\Ref{})]
|
|
{sec:hibernation}).
|
|
|
|
The procedures described in this section can be used to define new
|
|
record-type-defining macros.
|
|
\begin{example}
|
|
(define-record-type pare :pare
|
|
(kons x y)
|
|
pare?
|
|
(x kar set-kar!)
|
|
(y kdr))
|
|
\end{example}
|
|
is (sematically) equivalent to
|
|
\begin{example}
|
|
(define :pare (make-record-type 'pare '(x y)))
|
|
(define kons (record-constructor :pare '(x y)))
|
|
(define kar (record-accessor :pare 'x))
|
|
(define set-kar! (record-modifier :pare 'x))
|
|
(define kdr (record-accessor :pare 'y))
|
|
\end{example}
|
|
|
|
The ``(semantically)'' above is because \code{define-record-type} adds
|
|
declarations, which allows the type checker to detect some misuses of records,
|
|
and uses more efficient definitions for the constructor, accessors, and
|
|
modifiers.
|
|
Ignoring the declarations, which will have to wait for another edition of
|
|
the manual, what the above example actually expands into is:
|
|
\begin{example}
|
|
(define :pare (make-record-type 'pare '(x y)))
|
|
(define (kons x y) (record :pare x y))
|
|
(define (kar r) (checked-record-ref r :pare 1))
|
|
(define (set-kar! r new)
|
|
(checked-record-set! r :pare 1 new))
|
|
(define (kdr r) (checked-record-ref r :pare 2))
|
|
\end{example}
|
|
\code{Checked-record-ref} and \code{Checked-record-set!} are
|
|
low-level procedures that check the type of the
|
|
record and access or modify it using a single VM instruction.
|
|
|
|
\section{Finite record types}
|
|
|
|
The structure \code{finite-types} has
|
|
two macros for defining `finite' record types.
|
|
These are record types for which there are a fixed number of instances,
|
|
all of which are created at the same time as the record type itself.
|
|
The syntax for defining an enumerated type is:
|
|
\begin{example}
|
|
(define-enumerated-type \cvar{tag} \cvar{type-name}
|
|
\cvar{predicate-name}
|
|
\cvar{vector-of-instances-name}
|
|
\cvar{name-accessor}
|
|
\cvar{index-accessor}
|
|
(\cvar{instance-name} \ldots))
|
|
\end{example}
|
|
This defines a new record type, bound to \cvar{type-name}, with as many
|
|
instances as there are \cvar{instance-name}'s.
|
|
\cvar{Vector-of-instances-name} is bound to a vector containing the instances
|
|
of the type in the same order as the \cvar{instance-name} list.
|
|
\cvar{Tag} is bound to a macro that when given an \cvar{instance-name} expands
|
|
into an expression that returns corresponding instance.
|
|
The name lookup is done at macro expansion time.
|
|
\cvar{Predicate-name} is a predicate for the new type.
|
|
\cvar{Name-accessor} and \cvar{index-accessor} are accessors for the
|
|
name and index (in \cvar{vector-of-instances}) of instances of the type.
|
|
|
|
\begin{example}
|
|
(define-enumerated-type color :color
|
|
color?
|
|
colors
|
|
color-name
|
|
color-index
|
|
(black white purple maroon))
|
|
|
|
(color-name (vector-ref colors 0)) \evalsto black
|
|
(color-name (color white)) \evalsto white
|
|
(color-index (color purple)) \evalsto 2
|
|
\end{example}
|
|
|
|
Finite types are enumerations that allow the user to add additional
|
|
fields in the type.
|
|
The syntax for defining a finite type is:
|
|
\begin{example}
|
|
(define-finite-type \cvar{tag} \cvar{type-name}
|
|
(\cvar{field-tag} \ldots)
|
|
\cvar{predicate-name}
|
|
\cvar{vector-of-instances-name}
|
|
\cvar{name-accessor}
|
|
\cvar{index-accessor}
|
|
(\cvar{field-tag} \cvar{accessor-name} [\cvar{modifier-name}])
|
|
\ldots
|
|
((\cvar{instance-name} \cvar{field-value} \ldots)
|
|
\ldots))
|
|
\end{example}
|
|
The additional fields are specified exactly as with \code{define-record-type}.
|
|
The field arguments to the constructor are listed after the \cvar{type-name};
|
|
these do not include the name and index fields.
|
|
The form ends with the names and the initial field values for
|
|
the instances of the type.
|
|
The instances are constructed by applying the (unnamed) constructor to
|
|
these initial field values.
|
|
The name must be first and
|
|
the remaining values must match the \cvar{field-tag}s in the constructor's
|
|
argument list.
|
|
|
|
%This differs from \code{define-record-type} in the following ways:
|
|
%\begin{itemize}
|
|
%\item No name is specified for the constructor, but the field arguments
|
|
% to the constructor are listed.
|
|
%\item The \cvar{vector-of-instances-name} is added; it will be bound
|
|
% to a vector containing all of the instances of the type.
|
|
%These are constructed by applying the (unnamed) constructor to the
|
|
% initial field values at the end of the form.
|
|
%\item There are names for accessors for two required fields, name
|
|
% and index.
|
|
%These fields are not settable, and are not to be included
|
|
% in the argument list for the constructor.
|
|
%\item The form ends with the names and the initial field values for
|
|
% the instances of the type.
|
|
%The name must be first.
|
|
%The remaining values must match the \cvar{field-tag}s in the constructor's
|
|
% argument list.
|
|
%\item \cvar{Tag} is bound to a macro that maps \cvar{instance-name}s to the
|
|
% the corresponding instance of the vector.
|
|
%The name lookup is done at macro-expansion time.
|
|
%\end{itemize}
|
|
|
|
\begin{example}
|
|
(define-finite-type color :color
|
|
(red green blue)
|
|
color?
|
|
colors
|
|
color-name
|
|
color-index
|
|
(red color-red)
|
|
(green color-green)
|
|
(blue color-blue)
|
|
((black 0 0 0)
|
|
(white 255 255 255)
|
|
(purple 160 32 240)
|
|
(maroon 176 48 96)))
|
|
|
|
(color-name (color black)) \evalsto black
|
|
(color-name (vector-ref colors 1)) \evalsto white
|
|
(color-index (color purple)) \evalsto 2
|
|
(color-red (color maroon)) \evalsto 176
|
|
\end{example}
|
|
|
|
\section{Hash tables}
|
|
|
|
These are generic hash tables, and are in the structure \code{tables}.
|
|
Strictly speaking they are more maps than tables, as every table has a
|
|
value for every possible key (for that type of table).
|
|
All but a finite number of those values are \code{\#f}.
|
|
|
|
\begin{protos}
|
|
\proto{make-table}{}{table}
|
|
\proto{make-symbol-table}{}{symbol-table}
|
|
\proto{make-string-table}{}{string-table}
|
|
\proto{make-integer-table}{}{integer-table}
|
|
\proto{make-table-maker}{ compare-proc hash-proc}{procedure}
|
|
\protonoresult{make-table-immutable!}{ table}
|
|
\end{protos}
|
|
\noindent
|
|
The first four functions listed make various kinds of tables.
|
|
\code{Make-table} returns a table whose keys may be symbols, integer,
|
|
characters, booleans, or the empty list (these are also the values
|
|
that may be used in \code{case} expressions).
|
|
As with \code{case}, comparison is done using \code{eqv?}.
|
|
The comparison procedures used in symbol, string, and integer tables are
|
|
\code{eq?}, \code{string=?}, and \code{=}.
|
|
|
|
\code{Make-table-maker} takes two procedures as arguments and returns
|
|
a nullary table-making procedure.
|
|
\cvar{Compare-proc} should be a two-argument equality predicate.
|
|
\cvar{Hash-proc} should be a one argument procedure that takes a key
|
|
and returns a non-negative integer hash value.
|
|
If \code{(\cvar{compare-proc} \cvar{x} \cvar{y})} returns true,
|
|
then \code{(= (\cvar{hash-proc} \cvar{x}) (\cvar{hash-proc} \cvar{y}))}
|
|
must also return true.
|
|
For example, \code{make-integer-table} could be defined
|
|
as \code{(make-table-maker = abs)}.
|
|
|
|
\code{Make-table-immutable!} prohibits future modification to its argument.
|
|
|
|
\begin{protos}
|
|
\proto{table?}{ value}{boolean}
|
|
\proto{table-ref}{ table key}{value or {\tt \#f}}
|
|
\protonoresult{table-set!}{ table key value}
|
|
\protonoresult{table-walk}{ procedure table}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Table?} is the predicate for tables.
|
|
\code{Table-ref} and \code{table-set!} access and modify the value of \cvar{key}
|
|
in \cvar{table}.
|
|
\code{Table-walk} applies \cvar{procedure}, which must accept two arguments,
|
|
to every associated key and non-\code{\#f} value in \code{table}.
|
|
|
|
\begin{protos}
|
|
\proto{default-hash-function}{ value}{integer}
|
|
\proto{string-hash}{ string}{integer}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Default-hash-function} is the hash function used in the tables
|
|
returned by \code{make-table}, and \code{string-hash} it the one used
|
|
by \code{make-string-table}.
|
|
|
|
\section{Port extensions}
|
|
|
|
These procedures are in structure \code{extended-ports}.
|
|
|
|
\begin{protos}
|
|
\proto{make-string-input-port}{ string}{input-port}
|
|
\proto{make-string-output-port}{}{output-port}
|
|
\proto{string-output-port-output}{ string-output-port}{string}
|
|
\end{protos}
|
|
\noindent \code{Make-string-input-port} returns an input port that
|
|
that reads characters from the supplied string. An end-of-file
|
|
object is returned if the user reads past the end of the string.
|
|
\code{Make-string-output-port} returns an output port that saves
|
|
the characters written to it.
|
|
These are then returned as a string by \code{string-output-port-output}.
|
|
|
|
\begin{example}
|
|
(read (make-string-input-port "(a b)"))
|
|
\evalsto '(a b)
|
|
|
|
(let ((p (make-string-output-port)))
|
|
(write '(a b) p)
|
|
(let ((s (string-output-port-output p)))
|
|
(display "c" p)
|
|
(list s (string-output-port-output p))))
|
|
\evalsto '("(a b)" "(a b)c")
|
|
\end{example}
|
|
|
|
\begin{protos}
|
|
\protonoresult{limit-output}{ output-port n procedure}
|
|
\end{protos}
|
|
\noindent
|
|
\var{Procedure} is called on an output port.
|
|
Output written to that port is copied to \var{output-port} until \var{n}
|
|
characters have been written, at which point \code{limit-output} returns.
|
|
If \var{procedure} returns before writing \var{n} characters, then
|
|
\code{limit-output} also returns at that time, regardless of how many
|
|
characters have been written.
|
|
|
|
\begin{protos}
|
|
\proto{make-tracking-input-port}{ input-port}{input-port}
|
|
\proto{make-tracking-output-port}{ output-port}{output-port}
|
|
\proto{current-row}{ port}{integer or {\tt \#f}}
|
|
\proto{current-column}{ port}{integer or {\tt \#f}}
|
|
\protonoresult{fresh-line}{ output-port}
|
|
\end{protos}
|
|
\noindent \code{Make-tracking-input-port} and \code{make-tracking-output-port}
|
|
return ports that keep track of the current row and column and
|
|
are otherwise identical to their arguments.
|
|
Closing a tracking port does not close the underlying port.
|
|
\code{Current-row} and \code{current-column} return
|
|
\var{port}'s current read or write location.
|
|
They return \code{\#f} if \var{port} does not keep track of its location.
|
|
\code{Fresh-line} writes a newline character to \var{output-port} if
|
|
\code{(current-row \cvar{port})} is not 0.
|
|
|
|
\begin{example}
|
|
(define p (open-output-port "/tmp/temp"))
|
|
(list (current-row p) (current-column p))
|
|
\evalsto '(0 0)
|
|
(display "012" p)
|
|
(list (current-row p) (current-column p))
|
|
\evalsto '(0 3)
|
|
(fresh-line p)
|
|
(list (current-row p) (current-column p))
|
|
\evalsto '(1 0)
|
|
(fresh-line p)
|
|
(list (current-row p) (current-column p))
|
|
\evalsto '(1 0)
|
|
\end{example}
|
|
|
|
\section{Fluid bindings}
|
|
|
|
These procedures implement dynamic binding and are in structure \code{fluids}.
|
|
A \cvar{fluid} is a cell whose value can be bound dynamically.
|
|
Each fluid has a top-level value that is used when the fluid
|
|
is unbound in the current dynamic environment.
|
|
|
|
\begin{protos}
|
|
\proto{make-fluid}{ value}{fluid}
|
|
\proto{fluid}{ fluid}{value}
|
|
\proto{let-fluid}{ fluid value thunk}{value(s)}
|
|
\proto{let-fluids}{ fluid$_0$ value$_0$ fluid$_1$ value$_1$ \ldots thunk}{value(s)}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Make-fluid} returns a new fluid with \cvar{value} as its initial
|
|
top-level value.
|
|
\code{Fluid} returns \code{fluid}'s current value.
|
|
\code{Let-fluid} calls \code{thunk}, with \cvar{fluid} bound to \cvar{value}
|
|
until \code{thunk} returns.
|
|
Using a continuation to throw out of the call to \code{thunk} causes
|
|
\cvar{fluid} to revert to its original value, while throwing back
|
|
in causes \cvar{fluid} to be rebound to \cvar{value}.
|
|
\code{Let-fluid} returns the value(s) returned by \cvar{thunk}.
|
|
\code{Let-fluids} is identical to \code{let-fluid} except that it binds
|
|
an arbitrary number of fluids to new values.
|
|
|
|
\begin{example}
|
|
(let* ((f (make-fluid 'a))
|
|
(v0 (fluid f))
|
|
(v1 (let-fluid f 'b
|
|
(lambda ()
|
|
(fluid f))))
|
|
(v2 (fluid f)))
|
|
(list v0 v1 v2))
|
|
\evalsto '(a b a)
|
|
\end{example}
|
|
|
|
\begin{example}
|
|
(let ((f (make-fluid 'a))
|
|
(path '())
|
|
(c \#f))
|
|
(let ((add (lambda ()
|
|
(set! path (cons (fluid f) path)))))
|
|
(add)
|
|
(let-fluid f 'b
|
|
(lambda ()
|
|
(call-with-current-continuation
|
|
(lambda (c0)
|
|
(set! c c0)))
|
|
(add)))
|
|
(add)
|
|
(if (< (length path) 5)
|
|
(c)
|
|
(reverse path))))
|
|
\evalsto '(a b a b a)
|
|
\end{example}
|
|
|
|
\section{Shell commands}
|
|
|
|
Structure \code{c-system-function} provides access to the C \code{system()}
|
|
function.
|
|
|
|
\begin{protos}
|
|
\proto{have-system?}{}{boolean}
|
|
\proto{system}{ string}{integer}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Have-system?} returns true if the underlying C implementation
|
|
has a command processor.
|
|
\code{(System \cvar{string})} passes \cvar{string} to the C
|
|
\code{system()} function and returns the result.
|
|
|
|
\begin{example}
|
|
(begin
|
|
(system "echo foo > test-file")
|
|
(call-with-input-file "test-file" read))
|
|
\evalsto 'foo
|
|
\end{example}
|
|
|
|
\section{Sockets}
|
|
% Richard says: add UDP documentation.
|
|
|
|
Structure \code{sockets} provides access to TCP/IP sockets for interprocess
|
|
and network communication.
|
|
|
|
\begin{protos}
|
|
\proto{open-socket}{}{socket}
|
|
\proto{open-socket}{ port-number}{socket}
|
|
\proto{socket-port-number}{ socket}{integer}
|
|
\protonoresult{close-socket}{ socket}
|
|
\proto{socket-accept}{ socket}{input-port output-port}
|
|
\proto{get-host-name}{}{string}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Open-socket} creates a new socket.
|
|
If no \cvar{port-number} is supplied the system picks one at random.
|
|
\code{Socket-port-number} returns a socket's port number.
|
|
\code{Close-socket} closes a socket, preventing any further connections.
|
|
\code{Socket-accept} accepts a single connection on \cvar{socket}, returning
|
|
an input port and an output port for communicating with the client.
|
|
If no client is waiting \code{socket-accept} blocks until one appears.
|
|
\code{Get-host-name} returns the network name of the machine.
|
|
|
|
\begin{protos}
|
|
\proto{socket-client}{ host-name port-number}{input-port output-port}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Socket-client} connects to the server at \cvar{port-number} on
|
|
the machine named \cvar{host-name}.
|
|
\code{Socket-client} blocks until the server accepts the connection.
|
|
|
|
The following simple example shows a server and client for a centralized UID
|
|
service.
|
|
\begin{example}
|
|
(define (id-server)
|
|
(let ((socket (open-socket)))
|
|
(display "Waiting on port ")
|
|
(display (socket-port-number socket))
|
|
(newline)
|
|
(let loop ((next-id 0))
|
|
(call-with-values
|
|
(lambda ()
|
|
(socket-accept socket))
|
|
(lambda (in out)
|
|
(display next-id out)
|
|
(close-input-port in)
|
|
(close-output-port out)
|
|
(loop (+ next-id 1)))))))
|
|
|
|
(define (get-id machine port-number)
|
|
(call-with-values
|
|
(lambda ()
|
|
(socket-client machine port-number))
|
|
(lambda (in out)
|
|
(let ((id (read in)))
|
|
(close-input-port in)
|
|
(close-output-port out)
|
|
id))))
|
|
\end{example}
|
|
|
|
\section{Macros for writing loops}
|
|
% JAR says: origin? history?
|
|
|
|
\code{Iterate} and \code{reduce} are extensions of named-\code{let} for
|
|
writing loops that walk down one or more sequences,
|
|
such as the elements of a list or vector, the
|
|
characters read from a port, or an arithmetic series.
|
|
Additional sequences can be defined by the user.
|
|
\code{Iterate} and \code{reduce} are in structure \code{reduce}.
|
|
|
|
\subsection{{\tt Iterate}}
|
|
|
|
The syntax of \code{iterate} is:
|
|
\begin{example}
|
|
(iterate \cvar{loop-name}
|
|
((\cvar{sequence-type} \cvar{element-variable} \cvar{sequence-data} \ldots)
|
|
\ldots)
|
|
((\cvar{state-variable} \cvar{initial-value})
|
|
\ldots)
|
|
\cvar{body-expression}
|
|
[\cvar{final-expression}])
|
|
\end{example}
|
|
|
|
\code{Iterate} steps the \cvar{element-variable}s in parallel through the
|
|
sequences, while each \cvar{state-variable} has the corresponding
|
|
\cvar{initial-value} for the first iteration and have later values
|
|
supplied by \cvar{body-expression}.
|
|
If any sequence has reached its limit the value of the \code{iterate}
|
|
expression is
|
|
the value of \cvar{final-expression}, if present, or the current values of
|
|
the \cvar{state-variable}s, returned as multiple values.
|
|
If no sequence has reached
|
|
its limit, \cvar{body-expression} is evaluated and either calls \cvar{loop-name} with
|
|
new values for the \cvar{state-variable}s, or returns some other value(s).
|
|
|
|
The \cvar{loop-name} and the \cvar{state-variable}s and \cvar{initial-value}s behave
|
|
exactly as in named-\code{let}. The named-\code{let} expression
|
|
\begin{example}
|
|
(let loop-name ((state-variable initial-value) ...)
|
|
body ...)
|
|
\end{example}
|
|
is equivalent to an \code{iterate} expression with no sequences
|
|
(and with an explicit
|
|
\code{let} wrapped around the body expressions to take care of any
|
|
internal \code{define}s):
|
|
\begin{example}
|
|
(iterate loop-name
|
|
()
|
|
((state-variable initial-value) ...)
|
|
(let () body ...))
|
|
\end{example}
|
|
|
|
The \cvar{sequence-type}s are keywords (they are actually macros of a particular
|
|
form; it is easy to add additional types of sequences).
|
|
Examples are \code{list*} which walks down the elements of a list and
|
|
\code{vector*} which does the same for vectors.
|
|
For each iteration, each \cvar{element-variable} is bound to the next
|
|
element of the sequence.
|
|
The \cvar{sequence-data} gives the actual list or vector or whatever.
|
|
|
|
If there is a \cvar{final-expression}, it is evaluated when the end of one or more
|
|
sequences is reached.
|
|
If the \cvar{body-expression} does not call \cvar{loop-name} the
|
|
\cvar{final-expression} is not evaluated.
|
|
The \cvar{state-variable}s are visible in
|
|
\cvar{final-expression} but the \cvar{sequence-variable}s are not.
|
|
|
|
The \cvar{body-expression} and the \cvar{final-expression} are in tail-position within
|
|
the \code{iterate}.
|
|
Unlike named-\code{let}, the behavior of a non-tail-recursive call to
|
|
\cvar{loop-name} is unspecified (because iterating down a sequence may involve side
|
|
effects, such as reading characters from a port).
|
|
|
|
\subsection{{\tt Reduce}}
|
|
|
|
If an \code{iterate} expression is not meant to terminate before a sequence
|
|
has reached its end,
|
|
\cvar{body-expression} will always end with a tail call to \cvar{loop-name}.
|
|
\code{Reduce} is a macro that makes this common case explicit.
|
|
The syntax of \code{reduce} is
|
|
the same as that of \code{iterate}, except that there is no \cvar{loop-name}.
|
|
The \cvar{body-expression} returns new values of the \cvar{state-variable}s
|
|
instead of passing them to \cvar{loop-name}.
|
|
Thus \cvar{body-expression} must return as many values as there are state
|
|
variables.
|
|
By special dispensation, if there are
|
|
no state variables then \cvar{body-expression} may return any number of values,
|
|
all of which are ignored.
|
|
|
|
The syntax of \code{reduce} is:
|
|
\begin{example}
|
|
(reduce ((\cvar{sequence-type} \cvar{element-variable} \cvar{sequence-data} \ldots)
|
|
\ldots)
|
|
((\cvar{state-variable} \cvar{initial-value})
|
|
\ldots)
|
|
\cvar{body-expression}
|
|
[\cvar{final-expression}])
|
|
\end{example}
|
|
|
|
The value(s) returned by an instance of \code{reduce} is the value(s) returned
|
|
by the \cvar{final-expression}, if present, or the current value(s) of the state
|
|
variables when the end of one or more sequences is reached.
|
|
|
|
A \code{reduce} expression can be rewritten as an equivalent \code{iterate}
|
|
expression by adding a \cvar{loop-var} and a wrapper for the
|
|
\cvar{body-expression} that calls the \cvar{loop-var}.
|
|
\begin{example}
|
|
(iterate loop
|
|
((\cvar{sequence-type} \cvar{element-variable} \cvar{sequence-data} \ldots)
|
|
\ldots)
|
|
((\cvar{state-variable} \cvar{initial-value})
|
|
\ldots)
|
|
(call-with-values (lambda ()
|
|
\cvar{body-expression})
|
|
loop)
|
|
[\cvar{final-expression}])
|
|
\end{example}
|
|
|
|
\subsection{Sequence types}
|
|
|
|
The predefined sequence types are:
|
|
\begin{protos}
|
|
\syntaxprotonoresultnoindex{list*}{ \cvar{elt-var} \cvar{list}}
|
|
\syntaxprotonoresultnoindex{vector*}{ \cvar{elt-var} \cvar{vector}}
|
|
\syntaxprotonoresultnoindex{string*}{ \cvar{elt-var} \cvar{string}}
|
|
\syntaxprotonoresultnoindex{count*}
|
|
{ \cvar{elt-var} \cvar{start} [\cvar{end} [\cvar{step}]]}
|
|
\syntaxprotonoresultnoindex{input*}
|
|
{ \cvar{elt-var} \cvar{input-port} \cvar{read-procedure}}
|
|
\syntaxprotonoresultnoindex{stream*}
|
|
{ \cvar{elt-var} \cvar{procedure} \cvar{initial-data}}
|
|
\end{protos}
|
|
|
|
For lists, vectors, and strings the element variable is bound to the
|
|
successive elements of the list or vector, or the characters in the
|
|
string.
|
|
|
|
For \code{count*} the element variable is bound to the elements of the sequence
|
|
\begin{example}
|
|
\cvar{start}, \cvar{start} + \cvar{step}, \cvar{start} + 2\cvar{step}, \ldots, \cvar{end}
|
|
\end{example}
|
|
inclusive of \cvar{start} and exclusive of \cvar{end}.
|
|
The default \cvar{step} is 1.
|
|
The sequence does not terminate if no \cvar{end} is given or if there
|
|
is no $N > 0$ such that \cvar{end} = \cvar{start} + N\cvar{step}
|
|
(\code{=} is used to test for termination).
|
|
For example, \code{(count* i 0 -1)} doesn't terminate
|
|
because it begins past the \cvar{end} value and \code{(count* i 0 1 2)} doesn't
|
|
terminate because it skips over the \cvar{end} value.
|
|
|
|
For \code{input*} the elements are the results of successive applications
|
|
of \cvar{read-procedure} to \cvar{input-port}.
|
|
The sequence ends when \cvar{read-procedure} returns an end-of-file object.
|
|
|
|
For a stream, the \cvar{procedure} takes the current data value as an argument
|
|
and returns two values, the next value of the sequence and a new data value.
|
|
If the new data is \code{\#f} then the previous element was the last
|
|
one. For example,
|
|
\begin{example}
|
|
(list* elt my-list)
|
|
\end{example}
|
|
is the same as
|
|
\begin{example}
|
|
(stream* elt list->stream my-list)
|
|
\end{example}
|
|
where \code{list->stream} is
|
|
\begin{example}
|
|
(lambda (list)
|
|
(if (null? list)
|
|
(values 'ignored \#f)
|
|
(values (car list) (cdr list))))
|
|
\end{example}
|
|
|
|
\subsection{Synchronous sequences}
|
|
|
|
When using the sequence types described above, a loop terminates when any of
|
|
its sequences reaches its end. To help detect bugs it is useful to have
|
|
sequence types that check to see if two or more sequences end on the same
|
|
iteration. For this purpose there is second set of sequence types called
|
|
synchronous sequences. These are identical to the ones listed above except
|
|
that they cause an error to be signalled if a loop is terminated by a
|
|
synchronous sequence and some other synchronous sequence did not reach its
|
|
end on the same iteration.
|
|
|
|
Sequences are checked for termination in order, from left to right, and
|
|
if a loop is terminated by a non-synchronous sequence no further checking
|
|
is done.
|
|
|
|
The synchronous sequences are:
|
|
|
|
\begin{protos}
|
|
\syntaxprotonoresultnoindex{list\%}{ \cvar{elt-var} \cvar{list}}
|
|
\syntaxprotonoresultnoindex{vector\%}{ \cvar{elt-var} \cvar{vector}}
|
|
\syntaxprotonoresultnoindex{string\%}{ \cvar{elt-var} \cvar{string}}
|
|
\syntaxprotonoresultnoindex{count\%}
|
|
{ \cvar{elt-var} \cvar{start} \cvar{end} [\cvar{step}]}
|
|
\syntaxprotonoresultnoindex{input\%}
|
|
{ \cvar{elt-var} \cvar{input-port} \cvar{read-procedure}}
|
|
\syntaxprotonoresultnoindex{stream\%}
|
|
{ \cvar{elt-var} \cvar{procedure} \cvar{initial-data}}
|
|
\end{protos}
|
|
|
|
Note that the synchronous \code{count\%} must have an \cvar{end}, unlike the
|
|
nonsynchronous \code{count\%}.
|
|
|
|
\subsection{Examples}
|
|
|
|
\noindent
|
|
Gathering the indexes of list elements that answer true to some
|
|
predicate.
|
|
\begin{example}
|
|
(lambda (my-list predicate)
|
|
(reduce ((list* elt my-list)
|
|
(count* i 0))
|
|
((hits '()))
|
|
(if (predicate elt)
|
|
(cons i hits)
|
|
hits)
|
|
(reverse hits))
|
|
\end{example}
|
|
|
|
\noindent
|
|
Looking for the index of an element of a list.
|
|
\begin{example}
|
|
(lambda (my-list predicate)
|
|
(iterate loop
|
|
((list* elt my-list)
|
|
(count* i 0))
|
|
() ; no state
|
|
(if (predicate elt)
|
|
i
|
|
(loop))))
|
|
\end{example}
|
|
|
|
\noindent
|
|
Reading one line.
|
|
\begin{example}
|
|
(define (read-line port)
|
|
(iterate loop
|
|
((input* c port read-char))
|
|
((chars '()))
|
|
(if (char=? c \#\verb2\2newline)
|
|
(list->string (reverse chars))
|
|
(loop (cons c chars)))
|
|
(if (null? chars)
|
|
(eof-object)
|
|
; no newline at end of file
|
|
(list->string (reverse chars)))))
|
|
\end{example}
|
|
|
|
\noindent
|
|
Counting the lines in a file. We can't use \code{count*} because we
|
|
need the value of the count after the loop has finished.
|
|
\begin{example}
|
|
(define (line-count name)
|
|
(call-with-input-file name
|
|
(lambda (in)
|
|
(reduce ((input* l in read-line))
|
|
((i 0))
|
|
(+ i 1)))))
|
|
\end{example}
|
|
|
|
\subsection{Defining sequence types}
|
|
|
|
The sequence types are object-oriented macros similar to enumerations.
|
|
A non-synchronous sequence macro needs to supply three values:
|
|
\code{\#f} to indicate that it isn't synchronous, a list of state variables
|
|
and their initializers, and the code for one iteration.
|
|
The first
|
|
two methods are CPS'ed: they take another macro and argument to
|
|
which to pass their result.
|
|
The \code{synchronized?} method gets no additional arguments.
|
|
The \code{state-vars} method is passed a list of names which
|
|
will be bound to the arguments to the sequence.
|
|
The final method, for the step, is passed the list of names bound to
|
|
the arguments and the list of state variables.
|
|
In addition there is
|
|
a variable to be bound to the next element of the sequence, the
|
|
body expression for the loop, and an expression for terminating the
|
|
loop.
|
|
|
|
The definition of \code{list*} is
|
|
\begin{example}
|
|
(define-syntax list*
|
|
(syntax-rules (synchronized? state-vars step)
|
|
((list* synchronized? (next more))
|
|
(next \#f more))
|
|
((list* state-vars (start-list) (next more))
|
|
(next ((list-var start-list)) more))
|
|
((list* step (start-list) (list-var)
|
|
value-var loop-body final-exp)
|
|
(if (null? list-var)
|
|
final-exp
|
|
(let ((value-var (car list-var))
|
|
(list-var (cdr list-var)))
|
|
loop-body)))))
|
|
\end{example}
|
|
|
|
Synchronized sequences are the same, except that they need to
|
|
provide a termination test to be used when some other synchronized
|
|
method terminates the loop.
|
|
\begin{example}
|
|
(define-syntax list\%
|
|
(syntax-rules (sync done)
|
|
((list\% sync (next more))
|
|
(next \#t more))
|
|
((list\% done (start-list) (list-var))
|
|
(null? list-var))
|
|
((list\% stuff ...)
|
|
(list* stuff ...))))
|
|
\end{example}
|
|
|
|
\subsection{Expanded code}
|
|
|
|
The expansion of
|
|
\begin{example}
|
|
(reduce ((list* x '(1 2 3)))
|
|
((r '()))
|
|
(cons x r))
|
|
\end{example}
|
|
is
|
|
\begin{example}
|
|
(let ((final (lambda (r) (values r)))
|
|
(list '(1 2 3))
|
|
(r '()))
|
|
(let loop ((list list) (r r))
|
|
(if (null? list)
|
|
(final r)
|
|
(let ((x (car list))
|
|
(list (cdr list)))
|
|
(let ((continue (lambda (r)
|
|
(loop list r))))
|
|
(continue (cons x r)))))))
|
|
\end{example}
|
|
|
|
The only inefficiencies in this code are the \code{final} and \code{continue}
|
|
procedures, both of which could be substituted in-line.
|
|
The macro expander could do the substitution for \code{continue} when there
|
|
is no explicit proceed variable, as in this case, but not in general.
|
|
|
|
\section{Regular expressions}
|
|
\label{regexp-adt}
|
|
|
|
This section describes a functional interface for building regular
|
|
expressions and matching them against strings.
|
|
The matching is done using the POSIX regular expression package.
|
|
Regular expressions are in the structure \code{regexps}.
|
|
|
|
A regular expression is either a character set, which matches any character
|
|
in the set, or a composite expression containing one or more subexpressions.
|
|
A regular expression can be matched against a string to determine success
|
|
or failure, and to determine the substrings matched by particular subexpressions.
|
|
|
|
\subsection{Character sets}
|
|
|
|
Character sets may be defined using a list of characters and strings,
|
|
using a range or ranges of characters, or by using set operations on
|
|
existing character sets.
|
|
|
|
\begin{protos}
|
|
\proto{set}{ character-or-string \ldots}{char-set}
|
|
\proto{range}{ low-char high-char}{char-set}
|
|
\proto{ranges}{ low-char high-char \ldots}{char-set}
|
|
\proto{ascii-range}{ low-char high-char}{char-set}
|
|
\proto{ascii-ranges}{ low-char high-char \ldots}{char-set}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Set} returns a set that contains the character arguments and the
|
|
characters in any string arguments. \code{Range} returns a character
|
|
set that contain all characters between \cvar{low-char} and \cvar{high-char},
|
|
inclusive. \code{Ranges} returns a set that contains all characters in
|
|
the given ranges. \code{Range} and \code{ranges} use the ordering induced by
|
|
\code{char->integer}. \code{Ascii-range} and \code{ascii-ranges} use the
|
|
ASCII ordering.
|
|
It is an error for a \cvar{high-char} to be less than the preceding
|
|
\cvar{low-char} in the appropriate ordering.
|
|
|
|
\begin{protos}
|
|
\proto{negate}{ char-set}{char-set}
|
|
\proto{intersection}{ char-set char-set}{char-set}
|
|
\proto{union}{ char-set char-set}{char-set}
|
|
\proto{subtract}{ char-set char-set}{char-set}
|
|
\end{protos}
|
|
\noindent
|
|
These perform the indicated operations on character sets.
|
|
|
|
The following character sets are predefined:
|
|
\begin{center}
|
|
\W\begin{tabular}{ll}
|
|
\T\setlongtables
|
|
\T\begin{longtable}{ll}
|
|
\code{lower-case} & \code{(set "abcdefghijklmnopqrstuvwxyz")} \\
|
|
\code{upper-case} & \code{(set "ABCDEFGHIJKLMNOPQRSTUVWXYZ")} \\
|
|
\code{alphabetic} & \code{(union lower-case upper-case)} \\
|
|
\code{numeric} & \code{(set "0123456789")} \\
|
|
\code{alphanumeric} & \code{(union alphabetic numeric)} \\
|
|
\code{punctuation} &
|
|
\code{(set "}\verb2!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~2\code{")} \\
|
|
\code{graphic} & \code{(union alphanumeric punctuation)} \\
|
|
\code{printing} & \code{(union graphic (set \#}\verb2\2\code{space))} \\
|
|
\code{control} & \code{(negate printing)} \\
|
|
\code{blank} &
|
|
\code{(set \#}\verb2\2\code{space (ascii->char 9))} ; 9 is tab \\
|
|
\code{whitespace} &
|
|
\code{(union (set \#}\verb2\2\code{space) (ascii-range 9 13))} \\
|
|
\code{hexdigit} & \code{(set "0123456789abcdefABCDEF")} \\
|
|
\W\end{tabular}
|
|
\T\end{longtable}
|
|
\end{center}
|
|
\noindent The above are taken from the default locale in POSIX.
|
|
The characters in \code{whitespace} are \cvar{space}, \cvar{tab},
|
|
\cvar{newline} (= \cvar{line feed}), \cvar{vertical tab}, \cvar{form feed}, and
|
|
\cvar{carriage return}.
|
|
|
|
\subsection{Anchoring}
|
|
|
|
\begin{protos}
|
|
\proto{string-start}{}{reg-exp}
|
|
\proto{string-end}{}{reg-exp}
|
|
\end{protos}
|
|
\noindent
|
|
\code{String-start} returns a regular expression that matches the beginning
|
|
of the string being matched against; {string-end} returns one that matches
|
|
the end.
|
|
|
|
\subsection{Composite expressions}
|
|
|
|
\begin{protos}
|
|
\proto{sequence}{ reg-exp \ldots}{reg-exp}
|
|
\proto{one-of}{ reg-exp \ldots}{reg-exp}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Sequence} matches the concatenation of its arguments, \code{one-of} matches
|
|
any one of its arguments.
|
|
|
|
\begin{protos}
|
|
\proto{text}{ string}{reg-exp}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Text} returns a regular expression that matches the characters in
|
|
\cvar{string}, in order.
|
|
|
|
\begin{protos}
|
|
\proto{repeat}{ reg-exp}{reg-exp}
|
|
\proto{repeat}{ count reg-exp}{reg-exp}
|
|
\proto{repeat}{ min max reg-exp}{reg-exp}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Repeat} returns a regular expression that matches zero or more
|
|
occurences of its \cvar{reg-exp} argument. With no count the result
|
|
will match any number of times (\cvar{reg-exp}*). With a single
|
|
count the returned expression will match
|
|
\cvar{reg-exp} exactly that number of times.
|
|
The final case will match from \cvar{min} to \cvar{max}
|
|
repetitions, inclusive.
|
|
\cvar{Max} may be \code{\#f}, in which case there
|
|
is no maximum number of matches.
|
|
\cvar{Count} and \cvar{min} should be exact, non-negative integers;
|
|
\cvar{max} should either be an exact non-negative integer or \code{\#f}.
|
|
|
|
\subsection{Case sensitivity}
|
|
|
|
Regular expressions are normally case-sensitive.
|
|
\begin{protos}
|
|
\proto{ignore-case}{ reg-exp}{reg-exp}
|
|
\proto{use-case}{ reg-exp}{reg-exp}
|
|
\end{protos}
|
|
\noindent
|
|
The value returned by
|
|
\code{ignore-case} is identical its argument except that case will be
|
|
ignored when matching.
|
|
The value returned by \code{use-case} is protected
|
|
from future applications of \code{ignore-case}.
|
|
The expressions returned
|
|
by \code{use-case} and \code{ignore-case} are unaffected by later uses of the
|
|
these procedures.
|
|
By way of example, the following matches \code{"ab"} but not \code{"aB"},
|
|
\code{"Ab"}, or \code{"AB"}.
|
|
\begin{example}
|
|
\code{(text "ab")}
|
|
\end{example}
|
|
\noindent
|
|
while
|
|
\begin{example}
|
|
\code{(ignore-case (test "ab"))}
|
|
\end{example}
|
|
\noindent
|
|
matches \code{"ab"}, \code{"aB"},
|
|
\code{"Ab"}, and \code{"AB"} and
|
|
\begin{example}
|
|
(ignore-case (sequence (text "a")
|
|
(use-case (text "b"))))
|
|
\end{example}
|
|
\noindent
|
|
matches \code{"ab"} and \code{"Ab"} but not \code{"aB"} or \code{"AB"}.
|
|
|
|
\subsection{Submatches and matching}
|
|
|
|
A subexpression within a larger expression can be marked as a submatch.
|
|
When an expression is matched against a string, the success or failure
|
|
of each submatch within that expression is reported, as well as the
|
|
location of the substring matched be each successful submatch.
|
|
|
|
\begin{protos}
|
|
\proto{submatch}{ key reg-exp}{reg-exp}
|
|
\proto{no-submatches}{ reg-exp}{reg-exp}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Submatch} returns a regular expression that matches its argument and
|
|
causes the result of matching its argument to be reported by the \code{match}
|
|
procedure.
|
|
\cvar{Key} is used to indicate the result of this particular submatch
|
|
in the alist of successful submatches returned by \code{match}.
|
|
Any value may be used as a \cvar{key}.
|
|
\code{No-submatches} returns an expression identical to its
|
|
argument, except that all submatches have been elided.
|
|
|
|
\begin{protos}
|
|
\proto{any-match?}{ reg-exp string}{boolean}
|
|
\proto{exact-match?}{ reg-exp string}{boolean}
|
|
\proto{match}{ reg-exp string}{match or {\tt \#f}}
|
|
\proto{match-start}{ match}{index}
|
|
\proto{match-end}{ match}{index}
|
|
\proto{match-submatches}{ match}{alist}
|
|
\end{protos}
|
|
\noindent
|
|
\code{Any-match?} returns \code{\#t} if \cvar{string} matches \cvar{reg-exp} or
|
|
contains a substring that does, and \code{\#f} otherwise.
|
|
\code{Exact-match?} returns \code{\#t} if \cvar{string} matches
|
|
\cvar{reg-exp} and \code{\#f} otherwise.
|
|
|
|
\code{Match} returns \code{\#f} if \cvar{reg-exp} does not match \cvar{string}
|
|
and a match record if it does match.
|
|
A match record contains three values: the beginning and end of the substring
|
|
that matched
|
|
the pattern and an a-list of submatch keys and corresponding match records
|
|
for any submatches that also matched.
|
|
\code{Match-start} returns the index of
|
|
the first character in the matching substring and \code{match-end} gives index
|
|
of the first character after the matching substring.
|
|
\code{Match-submatches} returns an alist of submatch keys and match records.
|
|
Only the top match record returned by \code{match} has a submatch alist.
|
|
|
|
Matching occurs according to POSIX.
|
|
The match returned is the one with the lowest starting index in \cvar{string}.
|
|
If there is more than one such match, the longest is returned.
|
|
Within that match the longest possible submatches are returned.
|
|
|
|
All three matching procedures cache a compiled version of \cvar{reg-exp}.
|
|
Subsequent calls with the same \cvar{reg-exp} will be more efficient.
|
|
|
|
The C interface to the POSIX regular expression code uses ASCII \code{nul}
|
|
as an end-of-string marker.
|
|
The matching procedures will ignore any characters following an
|
|
embedded ASCII \code{nul}s in \cvar{string}.
|
|
|
|
\begin{example}
|
|
(define pattern (text "abc"))
|
|
(any-match? pattern "abc") \evalsto #t
|
|
(any-match? pattern "abx") \evalsto #f
|
|
(any-match? pattern "xxabcxx") \evalsto #t
|
|
|
|
(exact-match? pattern "abc") \evalsto #t
|
|
(exact-match? pattern "abx") \evalsto #f
|
|
(exact-match? pattern "xxabcxx") \evalsto #f
|
|
|
|
(match pattern "abc") \evalsto (#\{match 0 3\})
|
|
(match pattern "abx") \evalsto #f
|
|
(match pattern "xxabcxx") \evalsto (#\{match 2 5\})
|
|
|
|
(let ((x (match (sequence (text "ab")
|
|
(submatch 'foo (text "cd"))
|
|
(text "ef"))
|
|
"xxxabcdefxx")))
|
|
(list x (match-submatches x)))
|
|
\evalsto (#\{match 3 9\} ((foo . #\{match 5 7\}))
|
|
|
|
(match-submatches
|
|
(match (sequence
|
|
(set "a")
|
|
(one-of (submatch 'foo (text "bc"))
|
|
(submatch 'bar (text "BC"))))
|
|
"xxxaBCd"))
|
|
\evalsto ((bar . #\{match 4 6\}))
|
|
\end{example}
|
|
|
|
\section{SRFIs}
|
|
|
|
`SRFI' stands for `Scheme Request For Implementation'.
|
|
An SRFI is a description of an extension to standard Scheme.
|
|
Draft and final SRFI documents, a FAQ, and other information about SRFIs
|
|
can be found at the
|
|
\xlink{SRFI web site}[ at \code{http://srfi.schemers.org}]
|
|
{http://srfi.schemers.org}.
|
|
|
|
Scheme~48 includes implementations of the following (final) SRFIs:
|
|
\begin{itemize}
|
|
\item SRFI 1 -- List Library
|
|
\item SRFI 2 -- \code{and-let*}
|
|
\item SRFI 5 -- \code{let} with signatures and rest arguments
|
|
\item SRFI 6 -- Basic string ports
|
|
\item SRFI 7 -- Program configuration
|
|
\item SRFI 8 -- \code{receive}
|
|
\item SRFI 9 -- Defining record types
|
|
\item SRFI 11 -- Syntax for receiving multiple values
|
|
\item SRFI 13 -- String Library
|
|
\item SRFI 14 -- Character-Set Library (see note below)
|
|
\item SRFI 16 -- Syntax for procedures of variable arity
|
|
\item SRFI 17 -- Generalized \code{set!}
|
|
\item SRFI 23 -- Error reporting mechanism
|
|
\end{itemize}
|
|
Documentation on these can be found at the web site mentioned above.
|
|
|
|
SRFI~14 includes the procedure \code{->char-set} which is not a standard
|
|
Scheme identifier (in R$^5$RS the only required identifier starting
|
|
with \code{-} is \code{-} itself).
|
|
In the Scheme~48 version of SRFI~14 we have renamed \code{->char-set}
|
|
as \code{x->char-set}.
|
|
|
|
The SRFI bindings can be accessed either by opening the appropriate structure
|
|
(the structure \code{srfi-}\cvar{n} contains SRFI \cvar{n})
|
|
or by loading structure \code{srfi-7} and then using
|
|
the \code{,load-srfi-7-program} command to load an SRFI 7-style program.
|
|
The syntax for the command is
|
|
\begin{example}
|
|
\code{,load-srfi-7-program \cvar{name} \cvar{filename}}
|
|
\end{example}
|
|
This creates a new structure and associated package, binds the structure
|
|
to \cvar{name} in the configuration package, and then loads the program
|
|
found in \cvar{filename} into the package.
|
|
|
|
As an example, if the file \code{test.scm} contains
|
|
\begin{example}
|
|
(program (code (define x 10)))
|
|
\end{example}
|
|
this program can be loaded as follows:
|
|
\begin{example}
|
|
> ,load-package srfi-7
|
|
> ,load-srfi-7-program test test.scm
|
|
[test]
|
|
> ,in test
|
|
test> x
|
|
10
|
|
test>
|
|
\end{example}
|
|
|
|
%\W \chapter*{Index}
|
|
%\W \htmlprintindex
|
|
%\T \input{doc.ind}
|
|
|