summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/ChangeLog28
-rw-r--r--doc/ref/Makefile.am2
-rw-r--r--doc/ref/guile.texi40
-rw-r--r--doc/ref/misc-modules.texi135
-rwxr-xr-xdoc/ref/scheme-data.texi472
-rw-r--r--doc/ref/scheme-modules.texi81
6 files changed, 392 insertions, 366 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index f4f9d0167..45392ab27 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,3 +1,31 @@
+2001-12-01 Neil Jerram <neil@ossau.uklinux.net>
+
+ * scheme-data.texi (Variables): Node moved to modules chapter.
+ (Symbol Read Syntax): New node, with syntax-related material taken
+ from old Symbols node.
+ (Symbol Primitives): Renamed from `Symbols'.
+ (Symbols and Variables): Renamed to `Symbols'.
+ (Symbol Props): Renamed from `Symbol Tables'.
+ (Symbols): General review, improvements and additional material
+ throughout this section.
+
+ * guile.texi: Updated Notes comment.
+
+ * scheme-data.texi (Rx Interface): Node moved to Guile Modules
+ part, as the Rx interface is not core Guile.
+
+2001-11-30 Neil Jerram <neil@ossau.uklinux.net>
+
+ * scheme-data.texi (String Miscellanea): Removed, moving doc for
+ string-ci->symbol into the node on Symbols.
+
+ * Makefile.am (ETAGS_ARGS): Added.
+
+ * scheme-data.texi (Symbol Tables): Removed doc for gentemp,
+ intern-symbol, string->obarray-symbol, symbol-binding,
+ symbol-bound?, symbol-set!, unintern-symbol, symbol-interned?; all
+ of which no longer exist.
+
2001-11-25 Thien-Thi Nguyen <ttn@glug.org>
* posix.texi: Fix spelling. Thanks to Chris Cramer.
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index 5fbacd8a7..2f976f8bd 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -34,6 +34,8 @@ guile_TEXINFOS = preface.texi intro.texi program.texi scheme-intro.texi \
debugging.texi indices.texi script-getopt.texi data-rep.texi \
extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi
+ETAGS_ARGS = $(info_TEXINFOS) $(guile_TEXINFOS)
+
# Optionally support building an HTML version of the reference manual.
if HTMLDOC
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index fdd6df748..f49cdbc24 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -7,18 +7,30 @@
@set MANUAL_EDITION 1.1
@c %**end of header
-@c Notes: (distilled from Jim's and Tim's notes, and kept up to date)
+@c Notes
@c
-@c Remember to use "primitive" whereever appropriate.
-@c FIXME: gotta change existing "subr" uses to "Primitive".
-@c [JimB:] In my text for the Guile snarfer, I've used the term "subr"
-@c to denote a C function made available to the Scheme world as a
-@c function. This terminology is weird, but consistent with the
-@c function names and also with Emacs Lisp, which I assume takes
-@c Maclisp's lead.
+@c We no longer use the category "primitive" to distinguish C-defined
+@c Scheme procedures from those defined in Scheme. Instead, the
+@c reference manual now includes a C declaration as well as a Scheme
+@c declaration for each procedure that is available in both Scheme and
+@c C.
@c
-@c When adding a new function to the Guile manual, please document
-@c it with @deffn as one of `primitive', `procedure', or `syntax'.
+@c When adding a new reference entry to the Guile manual, please
+@c document it with @deffn using one of the following categories:
+@c
+@c {Scheme Procedure}
+@c {Scheme Syntax}
+@c {C Function}
+@c {C Macro}
+@c
+@c If the entry is for a new primitive, it should have both a @deffn
+@c {Scheme Procedure} line and a @deffnx {C Function} line; see the
+@c manual source for plenty of existing examples of this.
+@c
+@c For {C Function} entries where the return type and all parameter
+@c types are SCM, we omit the SCMs. This is easier to read and also
+@c gets round the problem that Texinfo doesn't allow a @deftypefnx
+@c inside a @deffn.
@c
@c For a list of Guile primitives that are not yet incorporated into the
@c reference manual, see the file `new-docstrings.texi', which holds all
@@ -26,8 +38,9 @@
@c that are not in the reference manual. If you have worked with some
@c of these concepts, implemented them, or just happen to know what they
@c do, please write up a little explanation -- it would be a big help.
-@c Alternatively, if you know of a great reason why some of these should
-@c *not* go in the manual, please let me know.
+@c Alternatively, if you know of any reason why some of these should
+@c *not* go in the manual, please let the mailing list
+@c <guile-devel@gnu.org> know.
@c Define indices that are used in the Guile Scheme part of the
@c reference manual to group stuff according to whether it is R5RS or a
@@ -81,7 +94,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.6 2001-11-11 15:01:51 ossau Exp $
+@subtitle $Id: guile.texi,v 1.7 2001-12-01 15:53:04 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@c AUTHORS
@@ -237,6 +250,7 @@ Part IV: Guile Modules
* Value History:: Maintaining a value history in the REPL.
* Pretty Printing:: Nicely formatting Scheme objects for output.
* Formatted Output:: The @code{format} procedure.
+* Rx Regexps:: The Rx regular expression library.
* Expect:: Controlling interactive programs with Guile.
* The Scheme shell (scsh):: Using scsh interfaces in Guile.
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
index be4f2ca46..552a28647 100644
--- a/doc/ref/misc-modules.texi
+++ b/doc/ref/misc-modules.texi
@@ -55,6 +55,7 @@ Guile's object types as the builtin procedures. This is particularly
important for smobs, for which a write procedure can be defined and be
used by @code{write}, but not by @code{pretty-print}.
+
@page
@node Formatted Output
@chapter Formatted Output
@@ -286,6 +287,140 @@ large version of @code{format} by default, so that the start-up time
of the interpreter is not unnecessarily increased.
+@page
+@node Rx Regexps
+@chapter The Rx Regular Expression Library
+
+[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!]
+
+@cindex rx
+@cindex finite automaton
+
+The @file{guile-lang-allover} package provides an interface to Tom
+Lord's Rx library (currently only to POSIX regular expressions). Use of
+the library requires a two step process: compile a regular expression
+into an efficient structure, then use the structure in any number of
+string comparisons.
+
+For example, given the regular expression @samp{abc.} (which matches any
+string containing @samp{abc} followed by any single character):
+
+@smalllisp
+guile> @kbd{(define r (regcomp "abc."))}
+guile> @kbd{r}
+#<rgx abc.>
+guile> @kbd{(regexec r "abc")}
+#f
+guile> @kbd{(regexec r "abcd")}
+#((0 . 4))
+guile>
+@end smalllisp
+
+The definitions of @code{regcomp} and @code{regexec} are as follows:
+
+@deffn {Scheme Procedure} regcomp pattern [flags]
+Compile the regular expression pattern using POSIX rules. Flags is
+optional and should be specified using symbolic names:
+@defvar REG_EXTENDED
+use extended POSIX syntax
+@end defvar
+@defvar REG_ICASE
+use case-insensitive matching
+@end defvar
+@defvar REG_NEWLINE
+allow anchors to match after newline characters in the
+string and prevents @code{.} or @code{[^...]} from matching newlines.
+@end defvar
+
+The @code{logior} procedure can be used to combine multiple flags.
+The default is to use
+POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
+and @code{\?}
+operators. Backslashes in @var{pattern} must be escaped if specified in a
+literal string e.g., @code{"\\(a\\)\\?"}.
+@end deffn
+
+@deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
+Match @var{string} against the compiled POSIX regular expression
+@var{regex}.
+@var{match-pick} and @var{flags} are optional. Possible flags (which can be
+combined using the logior procedure) are:
+
+@defvar REG_NOTBOL
+The beginning of line operator won't match the beginning of
+@var{string} (presumably because it's not the beginning of a line)
+@end defvar
+
+@defvar REG_NOTEOL
+Similar to REG_NOTBOL, but prevents the end of line operator
+from matching the end of @var{string}.
+@end defvar
+
+If no match is possible, regexec returns #f. Otherwise @var{match-pick}
+determines the return value:
+
+@code{#t} or unspecified: a newly-allocated vector is returned,
+containing pairs with the indices of the matched part of @var{string} and any
+substrings.
+
+@code{""}: a list is returned: the first element contains a nested list
+with the matched part of @var{string} surrounded by the the unmatched parts.
+Remaining elements are matched substrings (if any). All returned
+substrings share memory with @var{string}.
+
+@code{#f}: regexec returns #t if a match is made, otherwise #f.
+
+vector: the supplied vector is returned, with the first element replaced
+by a pair containing the indices of the matched portion of @var{string} and
+further elements replaced by pairs containing the indices of matched
+substrings (if any).
+
+list: a list will be returned, with each member of the list
+specified by a code in the corresponding position of the supplied list:
+
+a number: the numbered matching substring (0 for the entire match).
+
+@code{#\<}: the beginning of @var{string} to the beginning of the part matched
+by regex.
+
+@code{#\>}: the end of the matched part of @var{string} to the end of
+@var{string}.
+
+@code{#\c}: the "final tag", which seems to be associated with the "cut
+operator", which doesn't seem to be available through the posix
+interface.
+
+e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
+@var{string}.
+@end deffn
+
+Here are some other procedures that might be used when using regular
+expressions:
+
+@deffn {Scheme Procedure} compiled-regexp? obj
+Test whether obj is a compiled regular expression.
+@end deffn
+
+@deffn {Scheme Procedure} regexp->dfa regex [flags]
+@end deffn
+
+@deffn {Scheme Procedure} dfa-fork dfa
+@end deffn
+
+@deffn {Scheme Procedure} reset-dfa! dfa
+@end deffn
+
+@deffn {Scheme Procedure} dfa-final-tag dfa
+@end deffn
+
+@deffn {Scheme Procedure} dfa-continuable? dfa
+@end deffn
+
+@deffn {Scheme Procedure} advance-dfa! dfa string
+@end deffn
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
index 463233546..6ff70438b 100755
--- a/doc/ref/scheme-data.texi
+++ b/doc/ref/scheme-data.texi
@@ -47,7 +47,7 @@ sections of this manual that cover them.
* Characters:: New character names.
* Strings:: Special things about strings.
* Regular Expressions:: Pattern matching and substitution.
-* Symbols and Variables:: Manipulating the Scheme symbol table.
+* Symbols:: Symbols.
* Keywords:: Self-quoting, customizable display keywords.
* Pairs:: Scheme's basic building block.
* Lists:: Special list functions supported by Guile.
@@ -1427,7 +1427,6 @@ called with string containing unusal 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
@@ -1823,19 +1822,6 @@ 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
@@ -1861,7 +1847,6 @@ installation includes regular expression support by checking whether the
* Regexp Functions:: Functions that create and match regexps.
* Match Structures:: Finding what was matched by a regexp.
* Backslash Escapes:: Removing the special meaning of regexp metacharacters.
-* Rx Interface:: Tom Lord's Rx library does things differently.
@end menu
[FIXME: it may be useful to include an Examples section. Parts of this
@@ -2173,212 +2158,103 @@ support strings with different quoting conventions (an ungainly and
confusing extension when implemented in other languages), we must adhere
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!]
-
-@cindex rx
-@cindex finite automaton
-
-Guile includes an interface to Tom Lord's Rx library (currently only to
-POSIX regular expressions). Use of the library requires a two step
-process: compile a regular expression into an efficient structure, then
-use the structure in any number of string comparisons.
-
-For example, given the
-regular expression @samp{abc.} (which matches any string containing
-@samp{abc} followed by any single character):
-
-@smalllisp
-guile> @kbd{(define r (regcomp "abc."))}
-guile> @kbd{r}
-#<rgx abc.>
-guile> @kbd{(regexec r "abc")}
-#f
-guile> @kbd{(regexec r "abcd")}
-#((0 . 4))
-guile>
-@end smalllisp
-
-The definitions of @code{regcomp} and @code{regexec} are as follows:
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} regcomp pattern [flags]
-Compile the regular expression pattern using POSIX rules. Flags is
-optional and should be specified using symbolic names:
-@defvar REG_EXTENDED
-use extended POSIX syntax
-@end defvar
-@defvar REG_ICASE
-use case-insensitive matching
-@end defvar
-@defvar REG_NEWLINE
-allow anchors to match after newline characters in the
-string and prevents @code{.} or @code{[^...]} from matching newlines.
-@end defvar
-
-The @code{logior} procedure can be used to combine multiple flags.
-The default is to use
-POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
-and @code{\?}
-operators. Backslashes in @var{pattern} must be escaped if specified in a
-literal string e.g., @code{"\\(a\\)\\?"}.
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
-
-Match @var{string} against the compiled POSIX regular expression
-@var{regex}.
-@var{match-pick} and @var{flags} are optional. Possible flags (which can be
-combined using the logior procedure) are:
-
-@defvar REG_NOTBOL
-The beginning of line operator won't match the beginning of
-@var{string} (presumably because it's not the beginning of a line)
-@end defvar
-
-@defvar REG_NOTEOL
-Similar to REG_NOTBOL, but prevents the end of line operator
-from matching the end of @var{string}.
-@end defvar
-
-If no match is possible, regexec returns #f. Otherwise @var{match-pick}
-determines the return value:
-
-@code{#t} or unspecified: a newly-allocated vector is returned,
-containing pairs with the indices of the matched part of @var{string} and any
-substrings.
-
-@code{""}: a list is returned: the first element contains a nested list
-with the matched part of @var{string} surrounded by the the unmatched parts.
-Remaining elements are matched substrings (if any). All returned
-substrings share memory with @var{string}.
-
-@code{#f}: regexec returns #t if a match is made, otherwise #f.
-
-vector: the supplied vector is returned, with the first element replaced
-by a pair containing the indices of the matched portion of @var{string} and
-further elements replaced by pairs containing the indices of matched
-substrings (if any).
-
-list: a list will be returned, with each member of the list
-specified by a code in the corresponding position of the supplied list:
-
-a number: the numbered matching substring (0 for the entire match).
-
-@code{#\<}: the beginning of @var{string} to the beginning of the part matched
-by regex.
-
-@code{#\>}: the end of the matched part of @var{string} to the end of
-@var{string}.
-
-@code{#\c}: the "final tag", which seems to be associated with the "cut
-operator", which doesn't seem to be available through the posix
-interface.
-e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
-@var{string}.
-@end deffn
-
-Here are some other procedures that might be used when using regular
-expressions:
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} compiled-regexp? obj
-Test whether obj is a compiled regular expression.
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} regexp->dfa regex [flags]
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} dfa-fork dfa
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} reset-dfa! dfa
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} dfa-final-tag dfa
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} dfa-continuable? dfa
-@end deffn
+@node Symbols
+@section Symbols
+@tpindex Symbols
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} advance-dfa! dfa string
-@end deffn
+Symbols have two main uses. Crucially, they are used for denoting
+variables in a Scheme program. In addition, they are very useful for
+describing discrete literal data.
+A symbol is an object with a name that consists of a string of
+characters. In the usual case (where the name doesn't include any
+characters that could be confused with other elements of Scheme syntax)
+a symbol can be written in a Scheme program by writing the sequence of
+characters that make up the symbol's name. For example, the read syntax
+for the symbol named "multiply-by-2" is simply
-@node Symbols and Variables
-@section Symbols and Variables
+@lisp
+multiply-by-2
+@end lisp
-@c FIXME::martin: Review me!
+Symbols, then, look rather like strings but without any quotation marks.
+But there are several functional differences between them. The first
+big functional difference between symbols and strings concerns
+uniqueness. If the same-looking string is read twice from two different
+places in a program, the result is two @emph{distinguishable} string
+objects whose contents just happen to be the same. If, on the other
+hand, the same-looking symbol is read twice from two different places in
+a program, the result is the @emph{same} symbol object both times.
-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.
+@lisp
+(define str1 "hello")
+(define str2 "hello")
+(eq? str1 str2) @result{} #f
-The association between symbols and values is maintained in special data
-structures, the symbol tables.
+(define sym1 (quote hello))
+(define sym2 (quote hello))
+(eq? sym1 sym2) @result{} #t
+@end lisp
-In addition, Guile offers variables as first-class objects. They can
-be used for interacting with the module system.
+The second important difference is that symbols, unlike strings, are not
+self-evaluating. An unquoted symbol is interpreted as a variable
+reference, and the result of evaluating that symbol is the corresponding
+variable's value. (By the way, this is why we needed the @code{(quote
+@dots{})}s in the example above: @code{(quote hello)} returns the symbol
+object named "hello" itself, whereas an unquoted @code{hello} would try
+to find and dereference a variable associated with that symbol.)
+
+For example, when the expression @code{(string-length "abcd")} is read
+and evaluated, the sequence of characters @code{string-length} is read
+as the symbol whose name is "string-length". This symbol is associated
+with a variable whose value is the procedure that implements string
+length calculation. Therefore evaluation of the @code{string-length}
+symbol results in that procedure.
+
+Although the use of symbols for variable references is undoubtedly their
+most important role in Scheme, it is not documented further here. See
+instead @ref{Binding Constructs}, for how associations between symbols
+and variables are created, and @ref{Modules}, for how those associations
+are affected by Guile's module system. The rest of this section
+explains how symbols can also be used to represent discrete values, and
+documents the procedures available that relate to symbols as data
+objects @i{per se}.
@menu
-* Symbols:: All about symbols as a data type.
-* Symbol Tables:: Tables for mapping symbols to values.
-* Variables:: First-class variables.
+* Symbol Read Syntax:: Extended read syntax for symbols.
+* Symbol Primitives:: Operations related to symbols.
+* Symbol Discrete:: Using symbols as discrete values.
+* Symbol Props:: Function slots and property lists.
@end menu
-@node Symbols
-@subsection Symbols
-@tpindex Symbols
-
-@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 (@pxref{Association Lists}) or hash tables
-(@pxref{Hash Tables}), because this usage improves the readability a
-lot, and does not cause any performance loss.
+@node Symbol Read Syntax
+@subsection Extended Read Syntax for Symbols
The read syntax for symbols is a sequence of letters, digits, and
-@dfn{extended alphabetic characters} that begins with a character that
-cannot begin a number is an identifier. In addition, @code{+},
-@code{-}, and @code{...} are identifiers.
+@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
+begin with @code{+}, @code{-} or @code{.}.
Extended alphabetic characters may be used within identifiers as if
-they were letters. The following are extended alphabetic characters:
+they were letters. The set of extended alphabetic characters is:
@example
! $ % & * + - . / : < = > ? @@ ^ _ ~
@end example
-In addition to the read syntax defined above (which is taken from R5RS
-(@pxref{Formal syntax,,,r5rs,The Revised^5 Report on Scheme})), 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:
+In addition to the standard read syntax defined above (which is taken
+from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
+Scheme})), Guile provides an extended symbol read syntax that allows the
+inclusion of unusual characters such as space characters, newlines and
+parentheses. If (for whatever reason) you need to write a symbol
+containing characters not mentioned above, you can do so as follows.
@itemize @bullet
@item
-Begin the symbol with the two character @code{#@{},
+Begin the symbol with the characters @code{#@{},
@item
write the characters of the symbol and
@@ -2387,19 +2263,27 @@ write the characters of the symbol and
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.
+Here are a few examples of this form of read syntax. The first symbol
+needs to use extended syntax because it contains a space character, the
+second because it contains a line break, and the last because it 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.
+Although Guile provides this extended read syntax for symbols,
+widespread usage of it is discouraged because it is not portable and not
+very readable.
+
+
+@node Symbol Primitives
+@subsection Operations Related to Symbols
@rnindex symbol?
@deffn {Scheme Procedure} symbol? obj
@@ -2433,6 +2317,13 @@ standard case is lower case:
@end lisp
@end deffn
+@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
+
@rnindex symbol->string
@deffn {Scheme Procedure} symbol->string s
@deffnx {C Function} scm_symbol_to_string (s)
@@ -2461,19 +2352,10 @@ 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.
+@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} gensym [prefix]
@deffnx {C Function} scm_gensym (prefix)
@@ -2484,42 +2366,24 @@ is increased by 1 at each call. There is no provision for
resetting the counter.
@end deffn
-@deffn {Scheme Procedure} 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 {Scheme Procedure} 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 Symbol Discrete
+@subsection Using Symbols as Discrete Values
-@deffn {Scheme Procedure} string->obarray-symbol obarray string [soft?]
-Intern a new symbol in @var{obarray}, a symbol table, with name
-@var{string}.
-@end deffn
+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.
-@deffn {Scheme Procedure} 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},
-use the global symbol table. If @var{string} is not interned in
-@var{obarray}, an error is signalled.
-@end deffn
+It is very common in Scheme programs to use symbols as keys in
+association lists (@pxref{Association Lists}) or hash tables
+(@pxref{Hash Tables}), because this usage improves the readability a
+lot, and does not cause any performance loss.
-@deffn {Scheme Procedure} symbol-bound? obarray string
-Return @code{#t} if @var{obarray} contains a symbol with name
-@var{string} bound to a defined value. This differs from
-@var{symbol-interned?} in that the mere mention of a symbol
-usually causes it to be interned; @code{symbol-bound?}
-determines whether a symbol has been given any meaningful
-value.
-@end deffn
+
+@node Symbol Props
+@subsection Function Slots and Property Lists
@deffn {Scheme Procedure} symbol-fref symbol
@deffnx {C Function} scm_symbol_fref (symbol)
@@ -2531,16 +2395,6 @@ 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
-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}.
@@ -2551,95 +2405,6 @@ Return the @dfn{property list} currently associated with @var{symbol}.
Change the binding of @var{symbol}'s property slot.
@end deffn
-@deffn {Scheme Procedure} symbol-set! obarray string value
-Find the symbol in @var{obarray} whose name is @var{string}, and rebind
-it to @var{value}. An error is signalled if @var{string} is not present
-in @var{obarray}.
-@end deffn
-
-@deffn {Scheme Procedure} 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
-@tpindex Variables
-
-A variable is a box-like object that can hold any Scheme value. It is
-said to be @dfn{undefined} if its box holds a special Scheme value that
-denotes undefined-ness (which is different from all other Scheme values,
-including for example @code{#f}); otherwise the variable is
-@dfn{defined}.
-
-On its own, a variable object is anonymous. A variable is said to be
-@dfn{bound} when it is associated with a name in some way, usually a
-symbol in a module obarray. When this happens, the relationship is
-mutual: the variable is bound to the name (in that module), and the name
-(in that module) is bound to the variable.
-
-(That's the theory, anyway. In practice, defined-ness and bound-ness
-sometimes get confused, because Lisp and Scheme implementations have
-often conflated --- or deliberately drawn no distinction between --- a
-name that is unbound and a name that is bound to a variable whose value
-is undefined. We will try to be clear about the difference and explain
-any confusion where it is unavoidable.)
-
-Variables do not have a read syntax. Most commonly they are created and
-bound implicitly by @code{define} expressions: a top-level @code{define}
-expression of the form
-
-@lisp
-(define @var{name} @var{value})
-@end lisp
-
-@noindent
-creates a variable with initial value @var{value} and binds it to the
-name @var{name} in the current module. But they can also be created
-dynamically by calling one of the constructor procedures
-@code{make-variable} and @code{make-undefined-variable}.
-
-First-class variables are especially useful for interacting with the
-current module system (@pxref{The Guile module system}).
-
-@deffn {Scheme Procedure} make-undefined-variable
-@deffnx {C Function} scm_make_undefined_variable ()
-Return a variable that is initially unbound.
-@end deffn
-
-@deffn {Scheme Procedure} make-variable init
-@deffnx {C Function} scm_make_variable (init)
-Return a variable initialized to value @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} variable-bound? var
-@deffnx {C Function} scm_variable_bound_p (var)
-Return @code{#t} iff @var{var} is bound to a value.
-Throws an error if @var{var} is not a variable object.
-@end deffn
-
-@deffn {Scheme Procedure} variable-ref var
-@deffnx {C Function} scm_variable_ref (var)
-Dereference @var{var} and return its value.
-@var{var} must be a variable object; see @code{make-variable}
-and @code{make-undefined-variable}.
-@end deffn
-
-@deffn {Scheme Procedure} variable-set! var val
-@deffnx {C Function} scm_variable_set_x (var, val)
-Set the value of the variable @var{var} to @var{val}.
-@var{var} must be a variable object, @var{val} can be any
-value. Return an unspecified value.
-@end deffn
-
-@deffn {Scheme Procedure} variable? obj
-@deffnx {C Function} scm_variable_p (obj)
-Return @code{#t} iff @var{obj} is a variable object, else
-return @code{#f}.
-@end deffn
-
@node Keywords
@section Keywords
@@ -2777,8 +2542,8 @@ Or, even more economically, like this:
@end lisp
For further details on @code{let-keywords}, @code{define*} and other
-facilities provided by the @code{(ice-9 optargs)} module, @ref{Optional
-Arguments}.
+facilities provided by the @code{(ice-9 optargs)} module, see
+@ref{Optional Arguments}.
@node Keyword Read Syntax
@@ -2786,10 +2551,11 @@ Arguments}.
Guile, by default, only recognizes the keyword syntax specified by R5RS.
A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
-as a Scheme symbol, is the external representation of the keyword named
-@code{NAME}. Keyword objects print using this syntax as well, so values
-containing keyword objects can be read back into Guile. When used in an
-expression, keywords are self-quoting objects.
+as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external
+representation of the keyword named @code{NAME}. Keyword objects print
+using this syntax as well, so values containing keyword objects can be
+read back into Guile. When used in an expression, keywords are
+self-quoting objects.
If the @code{keyword} read option is set to @code{'prefix}, Guile also
recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
@@ -2817,7 +2583,7 @@ interface} and @ref{Reader options}.
#:type
:type
-@result{}
+@print{}
ERROR: In expression :type:
ERROR: Unbound variable: :type
ABORT: (unbound-variable)
diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi
index ac6ead1e8..c8d96082f 100644
--- a/doc/ref/scheme-modules.texi
+++ b/doc/ref/scheme-modules.texi
@@ -32,10 +32,14 @@ designed languages: ML, Python, Perl, and Modula 3 all allow the
clutter the global name space.
@cindex name space - private
+In addition, Guile offers variables as first-class objects. They can
+be used for interacting with the module system.
+
@menu
* Scheme and modules:: How modules are handled in standard Scheme.
* The Guile module system:: How Guile does it.
* Dynamic Libraries:: Loading libraries of compiled code at run time.
+* Variables:: First-class variables.
@end menu
@@ -827,6 +831,83 @@ the same place on all machines (which seems like a good idea to me
anyway).
+@node Variables
+@section Variables
+@tpindex Variables
+
+A variable is a box-like object that can hold any Scheme value. It is
+said to be @dfn{undefined} if its box holds a special Scheme value that
+denotes undefined-ness (which is different from all other Scheme values,
+including for example @code{#f}); otherwise the variable is
+@dfn{defined}.
+
+On its own, a variable object is anonymous. A variable is said to be
+@dfn{bound} when it is associated with a name in some way, usually a
+symbol in a module obarray. When this happens, the relationship is
+mutual: the variable is bound to the name (in that module), and the name
+(in that module) is bound to the variable.
+
+(That's the theory, anyway. In practice, defined-ness and bound-ness
+sometimes get confused, because Lisp and Scheme implementations have
+often conflated --- or deliberately drawn no distinction between --- a
+name that is unbound and a name that is bound to a variable whose value
+is undefined. We will try to be clear about the difference and explain
+any confusion where it is unavoidable.)
+
+Variables do not have a read syntax. Most commonly they are created and
+bound implicitly by @code{define} expressions: a top-level @code{define}
+expression of the form
+
+@lisp
+(define @var{name} @var{value})
+@end lisp
+
+@noindent
+creates a variable with initial value @var{value} and binds it to the
+name @var{name} in the current module. But they can also be created
+dynamically by calling one of the constructor procedures
+@code{make-variable} and @code{make-undefined-variable}.
+
+First-class variables are especially useful for interacting with the
+current module system (@pxref{The Guile module system}).
+
+@deffn {Scheme Procedure} make-undefined-variable
+@deffnx {C Function} scm_make_undefined_variable ()
+Return a variable that is initially unbound.
+@end deffn
+
+@deffn {Scheme Procedure} make-variable init
+@deffnx {C Function} scm_make_variable (init)
+Return a variable initialized to value @var{init}.
+@end deffn
+
+@deffn {Scheme Procedure} variable-bound? var
+@deffnx {C Function} scm_variable_bound_p (var)
+Return @code{#t} iff @var{var} is bound to a value.
+Throws an error if @var{var} is not a variable object.
+@end deffn
+
+@deffn {Scheme Procedure} variable-ref var
+@deffnx {C Function} scm_variable_ref (var)
+Dereference @var{var} and return its value.
+@var{var} must be a variable object; see @code{make-variable}
+and @code{make-undefined-variable}.
+@end deffn
+
+@deffn {Scheme Procedure} variable-set! var val
+@deffnx {C Function} scm_variable_set_x (var, val)
+Set the value of the variable @var{var} to @var{val}.
+@var{var} must be a variable object, @var{val} can be any
+value. Return an unspecified value.
+@end deffn
+
+@deffn {Scheme Procedure} variable? obj
+@deffnx {C Function} scm_variable_p (obj)
+Return @code{#t} iff @var{obj} is a variable object, else
+return @code{#f}.
+@end deffn
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End: