mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-06-10 14:00:21 +02:00
Various manual updates, including syncing with stable branch.
This commit is contained in:
Neil Jerram
parent
bc76d62865
commit
801892e788
5 changed files with 86 additions and 72 deletions
|
|
@ -1,3 +1,14 @@
|
|||
2002-03-27 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* scheme-compound.texi (List Searching): Remove docs for
|
||||
`scm_sloppy_mem*', which no longer exist.
|
||||
|
||||
2002-03-24 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* guile.texi (Top), intro.texi (What is Guile?, The Basic Guile
|
||||
Package): Use @ifnottex instead of @ifinfo, so that HTML
|
||||
generation works correctly.
|
||||
|
||||
2002-03-24 Marius Vollmer <mvo@zagadka.ping.de>
|
||||
|
||||
* tools.texi: Updated to reflect changes to the guile-snarf tool.
|
||||
|
|
|
|||
|
|
@ -121,7 +121,7 @@ by the Free Software Foundation.
|
|||
@sp 10
|
||||
@comment The title is printed in a large font.
|
||||
@title Guile Reference Manual
|
||||
@subtitle $Id: guile.texi,v 1.15 2002-03-16 13:51:03 ossau Exp $
|
||||
@subtitle $Id: guile.texi,v 1.16 2002-03-27 21:55:31 ossau Exp $
|
||||
@subtitle For use with Guile @value{VERSION}
|
||||
|
||||
@c AUTHORS
|
||||
|
|
@ -208,7 +208,7 @@ by Free Software Foundation.
|
|||
@c Where to find Guile examples.
|
||||
@set example-dir doc/examples
|
||||
|
||||
@ifinfo
|
||||
@ifnottex
|
||||
@node Top, Guile License, (dir), (dir)
|
||||
@top The Guile Reference Manual
|
||||
|
||||
|
|
@ -218,7 +218,7 @@ and interesting ways.
|
|||
|
||||
This Info file contains edition @value{MANUAL_EDITION} of the reference
|
||||
manual, corresponding to Guile version @value{VERSION}.
|
||||
@end ifinfo
|
||||
@end ifnottex
|
||||
|
||||
@menu
|
||||
Preface
|
||||
|
|
|
|||
|
|
@ -8,9 +8,9 @@ described in the
|
|||
@tex
|
||||
Revised$^5$
|
||||
@end tex
|
||||
@ifinfo
|
||||
@ifnottex
|
||||
Revised^5
|
||||
@end ifinfo
|
||||
@end ifnottex
|
||||
Report on the Algorithmic Language Scheme (usually known as R5RS),
|
||||
providing clean and general data and control structures. Guile goes
|
||||
beyond the rather austere language presented in R5RS, extending it with
|
||||
|
|
@ -899,9 +899,9 @@ known as R5RS, or the
|
|||
@iftex
|
||||
``Revised$^5$ Report on the Algorithmic Language Scheme'',
|
||||
@end iftex
|
||||
@ifinfo
|
||||
@ifnottex
|
||||
``Revised^5 Report on the Algorithmic Language Scheme'',
|
||||
@end ifinfo
|
||||
@end ifnottex
|
||||
we have included the report in the Guile distribution;
|
||||
@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
|
||||
Language Scheme}.
|
||||
|
|
|
|||
|
|
@ -27,8 +27,6 @@ values can be looked up within them.
|
|||
@section Pairs
|
||||
@tpindex Pairs
|
||||
|
||||
@c FIXME::martin: Review me!
|
||||
|
||||
Pairs are used to combine two Scheme objects into one compound object.
|
||||
Hence the name: A pair stores a pair of objects.
|
||||
|
||||
|
|
@ -133,8 +131,6 @@ by @code{set-cdr!} is unspecified.
|
|||
@section Lists
|
||||
@tpindex Lists
|
||||
|
||||
@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 @dfn{list}. Lists are made up of
|
||||
|
|
@ -173,8 +169,6 @@ or a pair which has a list in its cdr.
|
|||
@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
|
||||
|
|
@ -208,8 +202,6 @@ applications (@pxref{Simple Invocation}).
|
|||
@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
|
||||
|
|
@ -279,8 +271,6 @@ use the procedure @code{copy-tree} (@pxref{Copying}).
|
|||
@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.
|
||||
|
||||
|
|
@ -323,8 +313,6 @@ 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
|
||||
|
|
@ -463,8 +451,6 @@ 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 searched. When they fail, they return @code{#f}, otherwise
|
||||
|
|
@ -504,33 +490,10 @@ the non-empty lists returned by @code{(list-tail @var{lst}
|
|||
empty list) is returned.
|
||||
@end deffn
|
||||
|
||||
[FIXME: Is there any reason to have the `sloppy' functions available at
|
||||
high level at all? Maybe these docs should be relegated to a "Guile
|
||||
Internals" node or something. -twp]
|
||||
|
||||
@deffn {Scheme Procedure} sloppy-memq x lst
|
||||
This procedure behaves like @code{memq}, but does no type or error checking.
|
||||
Its use is recommended only in writing Guile internals,
|
||||
not for high-level Scheme programs.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} sloppy-memv x lst
|
||||
This procedure behaves like @code{memv}, but does no type or error checking.
|
||||
Its use is recommended only in writing Guile internals,
|
||||
not for high-level Scheme programs.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} sloppy-member x lst
|
||||
This procedure behaves like @code{member}, but does no type or error checking.
|
||||
Its use is recommended only in writing Guile internals,
|
||||
not for high-level Scheme programs.
|
||||
@end deffn
|
||||
|
||||
@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
|
||||
|
|
@ -893,7 +856,7 @@ The field holds a Scheme value and is GC protected. When a structure is
|
|||
created with this type of field, the field is initialized to refer to
|
||||
the structure's own handle. This kind of field is mainly useful when
|
||||
mixing Scheme and C code in which the C code may need to compute a
|
||||
structure's handle given only the address of its malloc-ed data.
|
||||
structure's handle given only the address of its malloc'd data.
|
||||
@end itemize
|
||||
|
||||
|
||||
|
|
@ -1713,19 +1676,19 @@ because association lists are so useful, Guile also provides specific
|
|||
procedures for manipulating them.
|
||||
|
||||
@menu
|
||||
* Alist Key Equality::
|
||||
* Adding or Setting Alist Entries::
|
||||
* Retrieving Alist Entries::
|
||||
* Removing Alist Entries::
|
||||
* Sloppy Alist Functions::
|
||||
* Alist Example::
|
||||
* Alist Key Equality::
|
||||
* Adding or Setting Alist Entries::
|
||||
* Retrieving Alist Entries::
|
||||
* Removing Alist Entries::
|
||||
* Sloppy Alist Functions::
|
||||
* Alist Example::
|
||||
@end menu
|
||||
|
||||
@node Alist Key Equality
|
||||
@subsubsection Alist Key Equality
|
||||
|
||||
All of Guile's dedicated association list procedures, apart from
|
||||
@code{acons}, come in three flavors, depending on the level of equality
|
||||
@code{acons}, come in three flavours, depending on the level of equality
|
||||
that is required to decide whether an existing key in the association
|
||||
list is the same as the key that the procedure call uses to identify the
|
||||
required entry.
|
||||
|
|
@ -1864,7 +1827,7 @@ function is @emph{not} destructive; @var{alist} is not modified.
|
|||
@deffnx {C Function} scm_assq_set_x (alist, key, val)
|
||||
@deffnx {C Function} scm_assv_set_x (alist, key, val)
|
||||
@deffnx {C Function} scm_assoc_set_x (alist, key, val)
|
||||
Re-associate @var{key} in @var{alist} with @var{value}: find any existing
|
||||
Reassociate @var{key} in @var{alist} with @var{value}: find any existing
|
||||
@var{alist} entry for @var{key} and associate it with the new
|
||||
@var{value}. If @var{alist} does not contain an entry for @var{key},
|
||||
add a new one. Return the (possibly new) alist.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
@chapter Simple Generic Data Types
|
||||
|
||||
This chapter describes those of Guile's simple data types which are
|
||||
primarily are used for their role as items of generic data. By
|
||||
primarily used for their role as items of generic data. By
|
||||
@dfn{simple} we mean data types that are not primarily used as
|
||||
containers to hold other data --- i.e. pairs, lists, vectors and so on.
|
||||
For the documentation of such @dfn{compound} data types, see
|
||||
|
|
@ -193,8 +193,7 @@ discover whether the value is any of the supported numerical types.
|
|||
|
||||
@deffn {Scheme Procedure} number? obj
|
||||
@deffnx {C Function} scm_number_p (obj)
|
||||
Return @code{#t} if @var{obj} is any kind of number, @code{#f} else.
|
||||
@findex number?
|
||||
Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
|
||||
@end deffn
|
||||
|
||||
For example:
|
||||
|
|
@ -265,7 +264,7 @@ completely invisible to the Scheme level programmer.
|
|||
|
||||
@deffn {Scheme Procedure} integer? x
|
||||
@deffnx {C Function} scm_integer_p (x)
|
||||
Return @code{#t} if @var{x} is an integer number, @code{#f} else.
|
||||
Return @code{#t} if @var{x} is an integer number, else @code{#f}.
|
||||
|
||||
@lisp
|
||||
(integer? 487)
|
||||
|
|
@ -329,11 +328,10 @@ with those that are already implemented.
|
|||
|
||||
@deffn {Scheme Procedure} real? obj
|
||||
@deffnx {C Function} scm_real_p (obj)
|
||||
Return @code{#t} if @var{obj} is a real number, @code{#f} else.
|
||||
Return @code{#t} if @var{obj} is a real number, else @code{#f}.
|
||||
Note that the sets of integer and rational values form subsets
|
||||
of the set of real numbers, so the predicate will also be fulfilled
|
||||
if @var{obj} is an integer number or a rational number.
|
||||
@findex real?
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} rational? x
|
||||
|
|
@ -1464,6 +1462,7 @@ called with string containing unusual characters.
|
|||
* String Searching:: Searching in strings.
|
||||
* Alphabetic Case Mapping:: Convert the alphabetic case of strings.
|
||||
* Appending Strings:: Appending strings to form a new string.
|
||||
* String Miscellanea:: Miscellaneous string procedures.
|
||||
@end menu
|
||||
|
||||
@node String Syntax
|
||||
|
|
@ -1859,6 +1858,19 @@ concatenation of the given strings, @var{args}.
|
|||
@end deffn
|
||||
|
||||
|
||||
@node String Miscellanea
|
||||
@subsection String Miscellanea
|
||||
|
||||
This section contains all remaining string procedures.
|
||||
|
||||
@deffn {Scheme Procedure} string-ci->symbol str
|
||||
@deffnx {C Function} scm_string_ci_to_symbol (str)
|
||||
Return the symbol whose name is @var{str}. @var{str} is
|
||||
converted to lowercase before the conversion is done, if Guile
|
||||
is currently reading symbols case-insensitively.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Regular Expressions
|
||||
@section Regular Expressions
|
||||
@tpindex Regular expressions
|
||||
|
|
@ -2262,6 +2274,7 @@ objects @i{per se}.
|
|||
@menu
|
||||
* Symbol Read Syntax:: Extended read syntax for symbols.
|
||||
* Symbol Primitives:: Operations related to symbols.
|
||||
* Symbol Tables:: Collecting symbols into obarrays.
|
||||
* Symbol Discrete:: Using symbols as discrete values.
|
||||
* Symbol Props:: Function slots and property lists.
|
||||
* Symbol Uninterned:: Uninterned symbols.
|
||||
|
|
@ -2271,7 +2284,7 @@ objects @i{per se}.
|
|||
@node Symbol Read Syntax
|
||||
@subsection Extended Read Syntax for Symbols
|
||||
|
||||
The read syntax for symbols is a sequence of letters, digits, and
|
||||
The read syntax for a symbol is a sequence of letters, digits, and
|
||||
@dfn{extended alphabetic characters}, beginning with a character that
|
||||
cannot begin a number. In addition, the special cases of @code{+},
|
||||
@code{-}, and @code{...} are read as symbols even though numbers can
|
||||
|
|
@ -2281,7 +2294,7 @@ Extended alphabetic characters may be used within identifiers as if
|
|||
they were letters. The set of extended alphabetic characters is:
|
||||
|
||||
@example
|
||||
! $ % & * + - . / : < = > ? @@ ^ _ ~
|
||||
! $ % & * + - . / : < = > ? @@ ^ _ ~
|
||||
@end example
|
||||
|
||||
In addition to the standard read syntax defined above (which is taken
|
||||
|
|
@ -2348,8 +2361,8 @@ standard case is lower case:
|
|||
(eq? 'mISSISSIppi 'mississippi) @result{} #t
|
||||
(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
|
||||
(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
|
||||
(eq? 'JollyWog
|
||||
(string->symbol (symbol->string 'JollyWog))) @result{} #t
|
||||
(eq? 'LolliPop
|
||||
(string->symbol (symbol->string 'LolliPop))) @result{} #t
|
||||
(string=? "K. Harper, M.D."
|
||||
(symbol->string
|
||||
(string->symbol "K. Harper, M.D."))) @result{}#t
|
||||
|
|
@ -2391,10 +2404,17 @@ standard case is lower case:
|
|||
@end lisp
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} symbol-hash symbol
|
||||
@deffnx {C Function} scm_symbol_hash (symbol)
|
||||
Return a hash value for @var{symbol}.
|
||||
@end deffn
|
||||
@node Symbol Tables
|
||||
@subsection Symbol Tables
|
||||
|
||||
@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.
|
||||
|
||||
@deffn {Scheme Procedure} gensym [prefix]
|
||||
@deffnx {C Function} scm_gensym (prefix)
|
||||
|
|
@ -2405,6 +2425,12 @@ is increased by 1 at each call. There is no provision for
|
|||
resetting the counter.
|
||||
@end deffn
|
||||
|
||||
@vgone{gentemp,1.6}
|
||||
@vgone{intern-symbol,1.6}
|
||||
@vgone{string->obarray-symbol,1.6}
|
||||
@vgone{symbol-binding,1.6}
|
||||
@vgone{symbol-bound?,1.6}
|
||||
|
||||
|
||||
@node Symbol Discrete
|
||||
@subsection Using Symbols as Discrete Values
|
||||
|
|
@ -2434,6 +2460,17 @@ Return the contents of @var{symbol}'s @dfn{function slot}.
|
|||
Change the binding of @var{symbol}'s function slot.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} symbol-hash symbol
|
||||
@deffnx {C Function} scm_symbol_hash (symbol)
|
||||
Return a hash value for @var{symbol}.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} symbol-interned? obarray string
|
||||
@deffnx {C Function} scm_symbol_interned_p (obarray, string)
|
||||
Return @code{#t} if @var{obarray} contains a symbol with name
|
||||
@var{string}, and @code{#f} otherwise.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} symbol-pref symbol
|
||||
@deffnx {C Function} scm_symbol_pref (symbol)
|
||||
Return the @dfn{property list} currently associated with @var{symbol}.
|
||||
|
|
@ -2444,6 +2481,10 @@ Return the @dfn{property list} currently associated with @var{symbol}.
|
|||
Change the binding of @var{symbol}'s property slot.
|
||||
@end deffn
|
||||
|
||||
@vgone{symbol-set!,1.6}
|
||||
@vgone{unintern-symbol,1.6}
|
||||
|
||||
|
||||
@node Symbol Uninterned
|
||||
@subsection Uninterned Symbols
|
||||
|
||||
|
|
@ -2465,14 +2506,14 @@ just returns that symbol. When not, a new symbol with the name is
|
|||
created and entered into the table so that it can be found later.
|
||||
|
||||
Sometimes you might want to create a symbol that is guaranteed `fresh',
|
||||
i.e., a symbol that did not exist previously. You might also want to
|
||||
i.e. a symbol that did not exist previously. You might also want to
|
||||
somehow guarantee that no one else will ever unintentionally stumble
|
||||
across your symbol in the future. These properties of a symbol are
|
||||
often needed when generating code during macro expansion. When
|
||||
introducing new temporary variables, you want to guarantee that they
|
||||
don't conflict with variables in other peoples code.
|
||||
don't conflict with variables in other people's code.
|
||||
|
||||
The simplest way to arrange for this is to create a new symbol and to
|
||||
The simplest way to arrange for this is to create a new symbol but
|
||||
not enter it into the global table of all symbols. That way, no one
|
||||
will ever get access to your symbol by chance. Symbols that are not in
|
||||
the table are called @dfn{uninterned}. Of course, symbols that
|
||||
|
|
@ -2531,6 +2572,7 @@ foo-3
|
|||
|
||||
@end lisp
|
||||
|
||||
|
||||
@node Keywords
|
||||
@section Keywords
|
||||
@tpindex Keywords
|
||||
|
|
@ -2717,8 +2759,6 @@ ABORT: (unbound-variable)
|
|||
@node Keyword Procedures
|
||||
@subsection Keyword Procedures
|
||||
|
||||
@c FIXME::martin: Review me!
|
||||
|
||||
The following procedures can be used for converting symbols to keywords
|
||||
and back.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue