* Lists:: Special list functions supported by Guile.
* Records::
* Structures::
-* Arrays::
-* Association Lists and Hash Tables::
-* Vectors::
+* Arrays:: Arrays of values.
+* Association Lists and Hash Tables:: Dictionary data types.
+* Vectors:: One-dimensional arrays of Scheme objects.
* Hooks:: User-customizable event lists.
* Other Data Types:: Data types that are documented elsewhere.
@end menu
@node Characters
@section Characters
-@rnindex char?
-@rnindex char=?
-@rnindex char<?
-@rnindex char>?
-@rnindex char<=?
-@rnindex char>=?
-@rnindex char-alphabetic?
-@rnindex char-numeric?
-@rnindex char-whitespace?
-@rnindex char-upper-case?
-@rnindex char-lower-case?
-@rnindex char->integer
-@rnindex integer->char
-@rnindex char-upcase
-@rnindex char-downcase
Most of the characters in the ASCII character set may be referred to by
#\null, #\nul
@end itemize
+@rnindex char?
@deffn primitive char? x
Return @code{#t} iff @var{x} is a character, else @code{#f}.
@end deffn
+@rnindex char=?
@deffn primitive char=? x y
Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
@end deffn
+@rnindex char<?
@deffn primitive char<? x y
Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
else @code{#f}.
@end deffn
+@rnindex char<=?
@deffn primitive char<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
ASCII sequence, else @code{#f}.
@end deffn
+@rnindex char>?
@deffn primitive char>? x y
Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
sequence, else @code{#f}.
@end deffn
+@rnindex char>=?
@deffn primitive char>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
ASCII sequence, else @code{#f}.
@end deffn
+@rnindex char-ci=?
@deffn primitive char-ci=? x y
Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
case, else @code{#f}.
@end deffn
+@rnindex char-ci<?
@deffn primitive char-ci<? x y
Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
ignoring case, else @code{#f}.
@end deffn
+@rnindex char-ci<=?
@deffn primitive char-ci<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
ASCII sequence ignoring case, else @code{#f}.
@end deffn
+@rnindex char-ci>?
@deffn primitive char-ci>? x y
Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
sequence ignoring case, else @code{#f}.
@end deffn
+@rnindex char-ci>=?
@deffn primitive char-ci>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
ASCII sequence ignoring case, else @code{#f}.
@end deffn
+@rnindex char-alphabetic?
@deffn primitive char-alphabetic? chr
Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
Alphabetic means the same thing as the isalpha C library function.
@end deffn
+@rnindex char-numeric?
@deffn primitive char-numeric? chr
Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
Numeric means the same thing as the isdigit C library function.
@end deffn
+@rnindex char-whitespace?
@deffn primitive char-whitespace? chr
Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
Whitespace means the same thing as the isspace C library function.
@end deffn
+@rnindex char-upper-case?
@deffn primitive char-upper-case? chr
Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
Uppercase means the same thing as the isupper C library function.
@end deffn
+@rnindex char-lower-case?
@deffn primitive char-lower-case? chr
Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
Lowercase means the same thing as the islower C library function.
C library functions.
@end deffn
+@rnindex char->integer
@deffn primitive char->integer chr
Return the number corresponding to ordinal position of @var{chr} in the
ASCII sequence.
@end deffn
+@rnindex integer->char
@deffn primitive integer->char n
Return the character at position @var{n} in the ASCII sequence.
@end deffn
+@rnindex char-upcase
@deffn primitive char-upcase chr
Return the uppercase character version of @var{chr}.
@end deffn
+@rnindex char-downcase
@deffn primitive char-downcase chr
Return the lowercase character version of @var{chr}.
@end deffn
@node Rx Interface
@subsection Rx Interface
+@c FIXME::martin: Shouldn't this be removed or moved to the
+@c ``Guile Modules'' chapter? The functions are not available in
+@c plain Guile...
+
[FIXME: this is taken from Gary and Mark's quick summaries and should be
reviewed and expanded. Rx is pretty stable, so could already be done!]
@node Symbols and Variables
@section Symbols and Variables
+@c FIXME::martin: Review me!
-Guile symbol tables are hash tables. Each hash table, also called an
-@dfn{obarray} (for `object array'), is a vector of association lists.
-Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To
-@dfn{intern} a symbol in a symbol table means to return its
-(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
-table (with an undefined value) if none is yet present.
+Symbols are a data type with a special property. On the one hand,
+symbols are used for denoting variables in a Scheme program, on the
+other they can be used as literal data as well.
-@c FIXME::martin: According to NEWS, removed. Remove here too, or
-@c leave for compatibility?
-@c @c docstring begin (texi-doc-string "guile" "builtin-bindings")
-@c @deffn primitive builtin-bindings
-@c Create and return a copy of the global symbol table, removing all
-@c unbound symbols.
-@c @end deffn
+The association between symbols and values is maintained in special data
+structures, the symbol tables.
-@deffn primitive gensym [prefix]
-Create a new symbol with a name constructed from a prefix and
-a counter value. The string @var{prefix} can be specified as
-an optional argument. Default prefix is @code{g}. The counter
-is increased by 1 at each call. There is no provision for
-resetting the counter.
-@end deffn
+In addition, Guile offers variables as first--class objects. They can
+be used for interacting with the module system.
-@deffn primitive gentemp [prefix [obarray]]
-Create a new symbol with a name unique in an obarray.
-The name is constructed from an optional string @var{prefix}
-and a counter value. The default prefix is @code{t}. The
-@var{obarray} is specified as a second optional argument.
-Default is the system obarray where all normal symbols are
-interned. The counter is increased by 1 at each
-call. There is no provision for resetting the counter.
-@end deffn
+@menu
+* Symbols:: All about symbols as a data type.
+* Symbol Tables:: Tables for mapping symbols to values.
+* Variables:: First--class variables.
+@end menu
-@deffn primitive intern-symbol obarray string
-Add a new symbol to @var{obarray} with name @var{string}, bound to an
-unspecified initial value. The symbol table is not modified if a symbol
-with this name is already present.
-@end deffn
+@node Symbols
+@subsection Symbols
-@deffn primitive string->obarray-symbol obarray string [soft?]
-Intern a new symbol in @var{obarray}, a symbol table, with name
-@var{string}.
+@c FIXME::martin: Review me!
+
+Symbols are especially useful because two symbols which are spelled the
+same way are equivalent in the sense of @code{eq?}. That means that
+they are actually the same Scheme object. The advantage is that symbols
+can be compared extremely efficiently, although they carry more
+information for the human reader than, say, numbers.
+
+It is very common in Scheme programs to use symbols as keys in
+association lists (REFFIXME) or hash tables (REFFIXME), because this
+usage improves the readability a lot, and does not cause any performance
+loss.
-If @var{obarray} is @code{#f}, use the default system symbol table. If
-@var{obarray} is @code{#t}, the symbol should not be interned in any
-symbol table; merely return the pair (@var{symbol}
-. @var{#<undefined>}).
+The read syntax for symbols is a sequence of letters, digits, and
+@emph{extended alphabetic characters} that begins with a character that
+cannot begin a number is an identifier. In addition, @code{+},
+@code{-}, and @code{...} are identifiers.
-The @var{soft?} argument determines whether new symbol table entries
-should be created when the specified symbol is not already present in
-@var{obarray}. If @var{soft?} is specified and is a true value, then
-new entries should not be added for symbols not already present in the
-table; instead, simply return @code{#f}.
+Extended alphabetic characters may be used within identifiers as if
+they were letters. The following are extended alphabetic characters:
+
+@example
+! $ % & * + - . / : < = > ? @@ ^ _ ~
+@end example
+
+In addition to the read syntax defined above (which is taken from R5RS
+(REFFIXME)), Guile provides a method for writing symbols with unusual
+characters, such as space characters. If you (for whatever reason) need
+to write a symbol containing characters not mentioned above, you write
+symbols as follows:
+
+@itemize @bullet
+@item Begin the symbol with the two character @code{#@{},
+@item write the characters of the symbol and
+@item finish the symbol with the characters @code{@}#}.
+@end itemize
+
+Here are a few examples of this form of read syntax; the first
+containing a space character, the second containing a line break and the
+last one looks like a number.
+
+@lisp
+#@{foo bar@}#
+#@{what
+ever@}#
+#@{4242@}#
+@end lisp
+
+Usage of this form of read syntax is discouraged, because it is not
+portable at all, and is not very readable.
+
+@rnindex symbol?
+@deffn primitive symbol? obj
+Return @code{#t} if @var{obj} is a symbol, otherwise return
+@code{#f}.
@end deffn
@rnindex string->symbol
@end lisp
@end deffn
+@node Symbol Tables
+@subsection Symbol Tables
+
+@c FIXME::martin: Review me!
+
+@c FIXME::martin: Are all these procedures still relevant?
+
+Guile symbol tables are hash tables. Each hash table, also called an
+@dfn{obarray} (for `object array'), is a vector of association lists.
+Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To
+@dfn{intern} a symbol in a symbol table means to return its
+(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
+table (with an undefined value) if none is yet present.
+
+@c FIXME::martin: According to NEWS, removed. Remove here too, or
+@c leave for compatibility?
+@c @c docstring begin (texi-doc-string "guile" "builtin-bindings")
+@c @deffn primitive builtin-bindings
+@c Create and return a copy of the global symbol table, removing all
+@c unbound symbols.
+@c @end deffn
+
+@deffn primitive gensym [prefix]
+Create a new symbol with a name constructed from a prefix and
+a counter value. The string @var{prefix} can be specified as
+an optional argument. Default prefix is @code{g}. The counter
+is increased by 1 at each call. There is no provision for
+resetting the counter.
+@end deffn
+
+@deffn primitive gentemp [prefix [obarray]]
+Create a new symbol with a name unique in an obarray.
+The name is constructed from an optional string @var{prefix}
+and a counter value. The default prefix is @code{t}. The
+@var{obarray} is specified as a second optional argument.
+Default is the system obarray where all normal symbols are
+interned. The counter is increased by 1 at each
+call. There is no provision for resetting the counter.
+@end deffn
+
+@deffn primitive intern-symbol obarray string
+Add a new symbol to @var{obarray} with name @var{string}, bound to an
+unspecified initial value. The symbol table is not modified if a symbol
+with this name is already present.
+@end deffn
+
+@deffn primitive string->obarray-symbol obarray string [soft?]
+Intern a new symbol in @var{obarray}, a symbol table, with name
+@var{string}.
+@end deffn
+
@deffn primitive symbol-binding obarray string
Look up in @var{obarray} the symbol whose name is @var{string}, and
return the value to which it is bound. If @var{obarray} is @code{#f},
in @var{obarray}.
@end deffn
-@rnindex symbol?
-@deffn primitive symbol? obj
-Return @code{#t} if @var{obj} is a symbol, otherwise return
-@code{#f}.
-@end deffn
-
@deffn primitive unintern-symbol obarray string
Remove the symbol with name @var{string} from @var{obarray}. This
function returns @code{#t} if the symbol was present and @code{#f}
otherwise.
@end deffn
+@node Variables
+@subsection Variables
+
+@c FIXME::martin: Review me!
+
+Variables are objects with two fields. They contain a value and they
+can contain a symbol, which is the name of the variable. A variable is
+said to be bound if it does not contain the object denoting unbound
+variables in the value slot.
+
+Variables do not have a read syntax, they have to be created by calling
+one of the constructor procedures @code{make-variable} or
+@code{make-undefined-variable} or retrieved by @code{builtin-variable}.
+
+First--class variables are especially useful for interacting with the
+current module system (REFFIXME).
+
@deffn primitive builtin-variable name
Return the built-in variable with the name @var{name}.
@var{name} must be a symbol (not a string).
@node Lists
@section Lists
-A very important datatype in Scheme---as well as in all other Lisp
+@c FIXME::martin: Review me!
+
+A very important data type in Scheme---as well as in all other Lisp
dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
Scheme does not have a real datatype @emph{list}. Lists are made up of
-chained @emph{pairs}, and only exist by definition --- A list is a chain
+chained @emph{pairs}, and only exist by definition---a list is a chain
of pairs which looks like a list.}
This is the short definition of what a list is:
@node List Syntax
@subsection List Read Syntax
+@c FIXME::martin: Review me!
+
The syntax for lists is an opening parentheses, then all the elements of
the list (separated by whitespace) and finally a closing
parentheses.@footnote{Note that there is no separation character between
@node List Predicates
@subsection List Predicates
+@c FIXME::martin: Review me!
+
Often it is useful to test whether a given Scheme object is a list or
not. List--processing procedures could use this information to test
whether their input is valid, or they could do different things
@node List Selection
@subsection List Selection
+@c FIXME::martin: Review me!
+
These procedures are used to get some information about a list, or to
retrieve one or more elements of a list.
@node Append/Reverse
@subsection Append and Reverse
+@c FIXME::martin: Review me!
+
@code{append} and @code{append!} are used to concatenate two or more
lists in order to form a new list. @code{reverse} and @code{reverse!}
return lists with the same elements as their arguments, but in reverse
@node List Modifification
@subsection List Modification
+@c FIXME::martin: Review me!
+
The following procedures modify existing list. @code{list-set!} and
@code{list-cdr-set!} change which elements a list contains, the various
deletion procedures @code{delq}, @code{delv} etc.
@node List Searching
@subsection List Searching
+@c FIXME::martin: Review me!
+
The following procedures search lists for particular elements. They use
different comparison predicates for comparing list elements with the
object to be seached. When they fail, they return @code{#f}, otherwise
@node List Mapping
@subsection List Mapping
+@c FIXME::martin: Review me!
+
List processing is very convenient in Scheme because the process of
iterating over the elements of a list can be highly abstracted. The
procedures in this section are the most basic iterating procedures for
(display (* x y))
(newline)))
(run-hook hook 3 4)
-Bar: 12
-Foo: 7
+@print{} Bar: 12
+@print{} Foo: 7
@end lisp
Note that the procedures are called in reverse order than they were
(display "Bar: ")
(display (* x y))
(newline))
- #t) ; <- Change here!
+ #t) ; @r{<- Change here!}
(run-hook hook 3 4)
-Foo: 7
-Bar: 12
+@print{} Foo: 7
+@print{} Bar: 12
@end lisp
@node Hook Reference
@node Lambda
@section Lambda: Basic Procedure Creation
+@c FIXME::martin: Review me!
+
+A @code{lambda} expression evaluates to a procedure. The environment
+which is in effect when a @code{lambda} expression is evaluated is
+enclosed in the newly created procedure, this is referred to as a
+@dfn{closure} (@pxref{About Closure}).
+
+When a procedure created by @code{lambda} is called with some actual
+arguments, the environment enclosed in the procedure is extended by
+binding the variables named in the formal argument list to new locations
+and storing the actual arguments into these locations. Then the body of
+the @code{lambda} expression is evaluation sequentially. The result of
+the last expression in the procedure body is then the result of the
+procedure invocation.
+
+The following examples will show how procedures can be created using
+@code{lambda}, and what you can do with these procedures.
+
+@lisp
+(lambda (x) (+ x x)) @result{} @r{a procedure}
+((lambda (x) (+ x x)) 4) @result{} 8
+@end lisp
+
+The fact that the environment in effect when creating a procedure is
+enclosed in the procedure is shown with this example:
+
+@lisp
+(define add4
+ (let ((x 4))
+ (lambda (y) (+ x y))))
+(add4 6) @result{} 10
+@end lisp
+
+
+@deffn syntax lambda formals body
+@var{formals} should be a formal argument list as described in the
+following table.
+
+@table @code
+@item (@var{variable1} @dots{})
+The procedure takes a fixed number of arguments; when the procedure is
+called, the arguments will be stored into the newly created location for
+the formal variables.
+@item @var{variable}
+The procedure takes any number of arguments; when the procedure is
+called, the sequence of actual arguments will converted into a list and
+stored into the newly created location for the formal variable.
+@item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1})
+If a space--delimited period precedes the last variable, then the
+procedure takes @var{n} or more variablesm where @var{n} is the number
+of formal arguments before the period. There must be at least one
+argument before the period. The first @var{n} actual arguments will be
+stored into the newly allocated locations for the first @var{n} formal
+arguments and the sequence of the remaining actual arguments is
+converted into a list and the stored into the location for the last
+formal argument. If there are exactly @var{n} actual arguments, the
+empty list is stored into the location of the last formal argument.
+@end table
+
+@var{body} is a sequence of Scheme expressions which are evaluated in
+order when the procedure is invoked.
+@end deffn
+
@node Optional Arguments
@section Optional Arguments
@node Procedure Properties
@section Procedure Properties and Metainformation
+@c FIXME::martin: Review me!
+
+Procedures always have attached the environment in which they were
+created and information about how to apply them to actual arguments. In
+addition to that, properties and metainformation can be stored with
+procedures. The procedures in this section can be used to test whether
+a given procedure satisfies a condition; and to access and set a
+procedure's property.
+
+The first group of procedures are predicates to test whether a Scheme
+object is a procedure, or a special procedure, respectively.
+@code{procedure?} is the most general predicates, it returns @code{#t}
+for any kind of procedure. @code{closure?} does not return @code{#t}
+for primitive procedures, and @code{thunk?} only returns @code{#t} for
+procedures which do not accept any arguments.
+@c FIXME::martin: thunk? returns true for `id'. What's wrong here?
+
+@rnindex procedure?
+@deffn primitive procedure? obj
+Return @code{#t} if @var{obj} is a procedure.
+@end deffn
+
+@deffn primitive closure? obj
+Return @code{#t} if @var{obj} is a closure.
+@end deffn
+
+@deffn primitive thunk? obj
+Return @code{#t} if @var{obj} is a thunk.
+@end deffn
+
+@c FIXME::martin: Is that true?
+@cindex procedure properties
+Procedure properties are general properties to be attached to
+procedures. These can be the name of a procedure or other relevant
+information, such as debug hints.
+
@deffn primitive procedure-properties proc
Return @var{obj}'s property list.
@end deffn
@var{value}.
@end deffn
+@cindex procedure documentation
+Documentation for a procedure can be accessed with the procedure
+@code{procedure-documentation}.
+
@deffn primitive procedure-documentation proc
Return the documentation string associated with @code{proc}. By
convention, if a procedure contains more than one expression and the
documentation for that procedure.
@end deffn
-@deffn primitive closure? obj
-Return @code{#t} if @var{obj} is a closure.
-@end deffn
-
-@rnindex procedure?
-@deffn primitive procedure? obj
-Return @code{#t} if @var{obj} is a procedure.
-@end deffn
-
-@deffn primitive thunk? obj
-Return @code{#t} if @var{obj} is a thunk.
-@end deffn
+@cindex source properties
+@c FIXME::martin: Is the following true?
+Source properties are properties which are related to the source code of
+a procedure, such as the line and column numbers, the file name etc.
@deffn primitive set-source-properties! obj plist
Install the association list @var{plist} as the source property
@node Procedures with Setters
@section Procedures with Setters
+@c FIXME::martin: Review me!
+
+@c FIXME::martin: Document `operator struct'.
+
+@cindex procedure with setter
+@cindex setter
+A @dfn{procedure with setter} is a special kind of procedure which
+normally behaves like any accesor procedure, that is a procedure which
+accesses a data structure. The difference is that this kind of
+procedure has a so--called @dfn{setter} attached, which is a procedure
+for storing something into a data structure.
+
+Procedures with setters are treated specially when the procedure appears
+in the special form @code{set!} (REFFIXME). How it works is best shown
+by example.
+
+Suppose we have a procedure called @code{foo-ref}, which accepts two
+arguments, a value of type @code{foo} and an integer. The procedure
+returns the value stored at the given index in the @code{foo} object.
+Let @code{f} be a variable containing such a @code{foo} data
+structure.@footnote{Working definitions would be:
+@lisp
+(define foo-ref vector-ref)
+(define foo-set! vector-set!)
+(define f (make-vector 2 #f))
+@end lisp}
+
+@lisp
+(foo-ref f 0) @result{} bar
+(foo-ref f 1) @result{} braz
+@end lisp
+
+Also suppose that a corresponding setter procedure called
+@code{foo-set!} does exist.
+
+@lisp
+(foo-set! f 0 'bla)
+(foo-ref f 0) @result{} bla
+@end lisp
+
+Now we could create a new procedure called @code{foo}, which is a
+procedure with setter, by calling @code{make-procedure-with-setter} with
+the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
+Let us call this new procedure @code{foo}.
+
+@lisp
+(define foo (make-procedure-with-setter foo-ref foo-set!))
+@end lisp
+
+@code{foo} can from now an be used to either read from the data
+structure stored in @code{f}, or to write into the structure.
+
+@lisp
+(set! (foo f 0) 'dum)
+(foo f 0) @result{} dum
+@end lisp
+
@deffn primitive make-procedure-with-setter procedure setter
Create a new procedure which behaves like @var{procedure}, but
with the associated setter @var{setter}.
@end deffn
@deffn primitive setter proc
+Return the setter of @var{proc}, which must be either a procedure with
+setter or an operator struct.
@end deffn
HCoop / bpt / guile.git / commitdiff