mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-29 16:30:19 +02:00
Code Activity

* scheme-procedures.texi (Lambda): Documented the lambda form.

Browse source 
(Procedure Properties): Concept and usage explanation added.
	(Procedures with Setters): Explain by example, introduce
	definitions.

	* scheme-data.texi (Symbols and Variables): Split and reorganized
	this section.
	(Symbols): New introductory text.
	(Characters): Added char-ci* procedures to rn index.
This commit is contained in:
Martin Grabmüller 2001-04-11 14:56:30 +00:00
parent b592004c72
commit f4f2b29a5f
3 changed files with 364 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

12
doc/ChangeLog
View file

@ -1,3 +1,15 @@
2001-04-11 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* scheme-procedures.texi (Lambda): Documented the lambda form.
(Procedure Properties): Concept and usage explanation added.
(Procedures with Setters): Explain by example, introduce
definitions.
* scheme-data.texi (Symbols and Variables): Split and reorganized
this section.
(Symbols): New introductory text.
(Characters): Added char-ci* procedures to rn index.
2001-04-10 Neil Jerram <neil@ossau.uklinux.net>
* scm.texi (Handling Errors): Improve Texinfo markup. Thanks to

263
doc/scheme-data.texi
View file

@ -53,9 +53,9 @@ sections of this manual that cover them.
* 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
@ -1135,21 +1135,6 @@ Return a new random state using @var{seed}.
@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
@ -1214,79 +1199,95 @@ Several characters have more than one name:
#\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.
@ -1298,19 +1299,23 @@ Uppercase and lowercase are as defined by the isupper and islower
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
@ -2090,6 +2095,10 @@ to this cumbersome escape syntax.
@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!]
@ -2233,60 +2242,82 @@ Test whether obj is a compiled regular expression.
@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!
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>}).
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.
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}.
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.
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.
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
@ -2336,6 +2367,57 @@ standard case is lower case:
@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},
@ -2383,18 +2465,29 @@ it to @var{value}. An error is signalled if @var{string} is not present
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).
@ -2755,10 +2848,12 @@ by @code{set-cdr!} is unspecified.
@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:
@ -2790,6 +2885,8 @@ 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
@ -2823,6 +2920,8 @@ applications (REFFIXME).
@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
@ -2881,6 +2980,8 @@ use the procedure @code{copy-tree} (REFFIXME).
@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.
@ -2918,6 +3019,8 @@ return it.
@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
@ -2977,6 +3080,8 @@ of the modified list is not lost, it is wise to save the return value of
@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.
@ -3042,6 +3147,8 @@ Like @code{delete!}, but only deletes the first occurrence of
@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
@ -3103,6 +3210,8 @@ not for high-level Scheme programs.
@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
@ -4835,8 +4944,8 @@ using @code{run-hook}.
(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
@ -4852,10 +4961,10 @@ on the second call to @code{add-hook!}.
(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

178
doc/scheme-procedures.texi
View file

@ -14,6 +14,69 @@
@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
@ -22,6 +85,42 @@
@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
@ -39,6 +138,10 @@ In @var{obj}'s property list, set the property named @var{key} to
@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
@ -46,18 +149,10 @@ first expression is a string constant, that string is assumed to contain
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
@ -83,6 +178,63 @@ Return the source property specified by @var{key} from
@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}.
@ -99,6 +251,8 @@ procedure with setter, or an operator struct.
@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