mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-12 14:50:19 +02:00
Code Activity

* Improve symbol documentation.

Browse source 
* Move variables doc into Modules chapter.
* Move Rx doc into Guile Modules part.
* Other minor doc changes.
This commit is contained in:
Neil Jerram 2001-12-01 15:53:04 +00:00
parent 3fd8eb6743
commit 2a946b44f4
6 changed files with 399 additions and 373 deletions
Download patch file Download diff file Expand all files Collapse all files

28
doc/ref/ChangeLog
View file

@ -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> 2001-11-25 Thien-Thi Nguyen <ttn@glug.org>
* posix.texi: Fix spelling. Thanks to Chris Cramer. * posix.texi: Fix spelling. Thanks to Chris Cramer.

2
doc/ref/Makefile.am
View file

@ -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 \ debugging.texi indices.texi script-getopt.texi data-rep.texi \
extend.texi repl-modules.texi srfi-modules.texi misc-modules.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. # Optionally support building an HTML version of the reference manual.
if HTMLDOC if HTMLDOC

40
doc/ref/guile.texi
View file

@ -7,18 +7,30 @@
@set MANUAL_EDITION 1.1 @set MANUAL_EDITION 1.1
@c %**end of header @c %**end of header
@c Notes: (distilled from Jim's and Tim's notes, and kept up to date) @c Notes
@c @c
@c Remember to use "primitive" whereever appropriate. @c We no longer use the category "primitive" to distinguish C-defined
@c FIXME: gotta change existing "subr" uses to "Primitive". @c Scheme procedures from those defined in Scheme. Instead, the
@c [JimB:] In my text for the Guile snarfer, I've used the term "subr" @c reference manual now includes a C declaration as well as a Scheme
@c to denote a C function made available to the Scheme world as a @c declaration for each procedure that is available in both Scheme and
@c function. This terminology is weird, but consistent with the @c C.
@c function names and also with Emacs Lisp, which I assume takes
@c Maclisp's lead.
@c @c
@c When adding a new function to the Guile manual, please document @c When adding a new reference entry to the Guile manual, please
@c it with @deffn as one of `primitive', `procedure', or `syntax'. @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
@c For a list of Guile primitives that are not yet incorporated into the @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 @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 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 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 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 Alternatively, if you know of any reason why some of these should
@c *not* go in the manual, please let me know. @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 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 @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 @sp 10
@comment The title is printed in a large font. @comment The title is printed in a large font.
@title Guile Reference Manual @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} @subtitle For use with Guile @value{VERSION}
@c AUTHORS @c AUTHORS
@ -237,6 +250,7 @@ Part IV: Guile Modules
* Value History:: Maintaining a value history in the REPL. * Value History:: Maintaining a value history in the REPL.
* Pretty Printing:: Nicely formatting Scheme objects for output. * Pretty Printing:: Nicely formatting Scheme objects for output.
* Formatted Output:: The @code{format} procedure. * Formatted Output:: The @code{format} procedure.
* Rx Regexps:: The Rx regular expression library.
* Expect:: Controlling interactive programs with Guile. * Expect:: Controlling interactive programs with Guile.
* The Scheme shell (scsh):: Using scsh interfaces in Guile. * The Scheme shell (scsh):: Using scsh interfaces in Guile.

135
doc/ref/misc-modules.texi
View file

@ -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 important for smobs, for which a write procedure can be defined and be
used by @code{write}, but not by @code{pretty-print}. used by @code{write}, but not by @code{pretty-print}.
@page @page
@node Formatted Output @node Formatted Output
@chapter 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. 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 Local Variables:
@c TeX-master: "guile.texi" @c TeX-master: "guile.texi"
@c End: @c End:

486
doc/ref/scheme-data.texi
View file

@ -47,7 +47,7 @@ sections of this manual that cover them.
* Characters:: New character names. * Characters:: New character names.
* Strings:: Special things about strings. * Strings:: Special things about strings.
* Regular Expressions:: Pattern matching and substitution. * Regular Expressions:: Pattern matching and substitution.
* Symbols and Variables:: Manipulating the Scheme symbol table. * Symbols:: Symbols.
* Keywords:: Self-quoting, customizable display keywords. * Keywords:: Self-quoting, customizable display keywords.
* Pairs:: Scheme's basic building block. * Pairs:: Scheme's basic building block.
* Lists:: Special list functions supported by Guile. * Lists:: Special list functions supported by Guile.
@ -1427,7 +1427,6 @@ called with string containing unusal characters.
* String Searching:: Searching in strings. * String Searching:: Searching in strings.
* Alphabetic Case Mapping:: Convert the alphabetic case of strings. * Alphabetic Case Mapping:: Convert the alphabetic case of strings.
* Appending Strings:: Appending strings to form a new string. * Appending Strings:: Appending strings to form a new string.
* String Miscellanea:: Miscellaneous string procedures.
@end menu @end menu
@node String Syntax @node String Syntax
@ -1823,19 +1822,6 @@ concatenation of the given strings, @var{args}.
@end deffn @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 @node Regular Expressions
@section Regular Expressions @section Regular Expressions
@tpindex 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. * Regexp Functions:: Functions that create and match regexps.
* Match Structures:: Finding what was matched by a regexp. * Match Structures:: Finding what was matched by a regexp.
* Backslash Escapes:: Removing the special meaning of regexp metacharacters. * Backslash Escapes:: Removing the special meaning of regexp metacharacters.
* Rx Interface:: Tom Lord's Rx library does things differently.
@end menu @end menu
[FIXME: it may be useful to include an Examples section. Parts of this [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 confusing extension when implemented in other languages), we must adhere
to this cumbersome escape syntax. 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
@c NJFIXME not in libguile!
@deffn {Scheme Procedure} advance-dfa! dfa string
@end deffn
@node Symbols and Variables
@section Symbols and Variables
@c FIXME::martin: Review me!
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.
The association between symbols and values is maintained in special data
structures, the symbol tables.
In addition, Guile offers variables as first-class objects. They can
be used for interacting with the module system.
@menu
* Symbols:: All about symbols as a data type.
* Symbol Tables:: Tables for mapping symbols to values.
* Variables:: First-class variables.
@end menu
@node Symbols @node Symbols
@subsection Symbols @section Symbols
@tpindex Symbols @tpindex Symbols
@c FIXME::martin: Review me! 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.
Symbols are especially useful because two symbols which are spelled the A symbol is an object with a name that consists of a string of
same way are equivalent in the sense of @code{eq?}. That means that characters. In the usual case (where the name doesn't include any
they are actually the same Scheme object. The advantage is that symbols characters that could be confused with other elements of Scheme syntax)
can be compared extremely efficiently, although they carry more a symbol can be written in a Scheme program by writing the sequence of
information for the human reader than, say, numbers. characters that make up the symbol's name. For example, the read syntax
for the symbol named "multiply-by-2" is simply
It is very common in Scheme programs to use symbols as keys in @lisp
association lists (@pxref{Association Lists}) or hash tables multiply-by-2
(@pxref{Hash Tables}), because this usage improves the readability a @end lisp
lot, and does not cause any performance loss.
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.
@lisp
(define str1 "hello")
(define str2 "hello")
(eq? str1 str2) @result{} #f
(define sym1 (quote hello))
(define sym2 (quote hello))
(eq? sym1 sym2) @result{} #t
@end lisp
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
* 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 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 symbols is a sequence of letters, digits, and
@dfn{extended alphabetic characters} that begins with a character that @dfn{extended alphabetic characters}, beginning with a character that
cannot begin a number is an identifier. In addition, @code{+}, cannot begin a number. In addition, the special cases of @code{+},
@code{-}, and @code{...} are identifiers. @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 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 @example
! $ % & * + - . / : < = > ? @@ ^ _ ~ ! $ % & * + - . / : < = > ? @@ ^ _ ~
@end example @end example
In addition to the read syntax defined above (which is taken from R5RS In addition to the standard read syntax defined above (which is taken
(@pxref{Formal syntax,,,r5rs,The Revised^5 Report on Scheme})), Guile from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
provides a method for writing symbols with unusual characters, such as Scheme})), Guile provides an extended symbol read syntax that allows the
space characters. If you (for whatever reason) need to write a symbol inclusion of unusual characters such as space characters, newlines and
containing characters not mentioned above, you write symbols as follows: parentheses. If (for whatever reason) you need to write a symbol
containing characters not mentioned above, you can do so as follows.
@itemize @bullet @itemize @bullet
@item @item
Begin the symbol with the two character @code{#@{}, Begin the symbol with the characters @code{#@{},
@item @item
write the characters of the symbol and 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{@}#}. finish the symbol with the characters @code{@}#}.
@end itemize @end itemize
Here are a few examples of this form of read syntax; the first Here are a few examples of this form of read syntax. The first symbol
containing a space character, the second containing a line break and the needs to use extended syntax because it contains a space character, the
last one looks like a number. second because it contains a line break, and the last because it looks
like a number.
@lisp @lisp
#@{foo bar@}# #@{foo bar@}#
#@{what #@{what
ever@}# ever@}#
#@{4242@}# #@{4242@}#
@end lisp @end lisp
Usage of this form of read syntax is discouraged, because it is not Although Guile provides this extended read syntax for symbols,
portable at all, and is not very readable. 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? @rnindex symbol?
@deffn {Scheme Procedure} symbol? obj @deffn {Scheme Procedure} symbol? obj
@ -2433,6 +2317,13 @@ standard case is lower case:
@end lisp @end lisp
@end deffn @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 @rnindex symbol->string
@deffn {Scheme Procedure} symbol->string s @deffn {Scheme Procedure} symbol->string s
@deffnx {C Function} scm_symbol_to_string (s) @deffnx {C Function} scm_symbol_to_string (s)
@ -2461,19 +2352,10 @@ standard case is lower case:
@end lisp @end lisp
@end deffn @end deffn
@node Symbol Tables @deffn {Scheme Procedure} symbol-hash symbol
@subsection Symbol Tables @deffnx {C Function} scm_symbol_hash (symbol)
Return a hash value for @var{symbol}.
@c FIXME::martin: Review me! @end deffn
@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] @deffn {Scheme Procedure} gensym [prefix]
@deffnx {C Function} scm_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. resetting the counter.
@end deffn @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 @node Symbol Discrete
Add a new symbol to @var{obarray} with name @var{string}, bound to an @subsection Using Symbols as Discrete Values
unspecified initial value. The symbol table is not modified if a symbol
with this name is already present.
@end deffn
@deffn {Scheme Procedure} string->obarray-symbol obarray string [soft?] Symbols are especially useful because two symbols which are spelled the
Intern a new symbol in @var{obarray}, a symbol table, with name same way are equivalent in the sense of @code{eq?}. That means that
@var{string}. they are actually the same Scheme object. The advantage is that symbols
@end deffn can be compared extremely efficiently, although they carry more
information for the human reader than, say, numbers.
@deffn {Scheme Procedure} symbol-binding obarray string It is very common in Scheme programs to use symbols as keys in
Look up in @var{obarray} the symbol whose name is @var{string}, and association lists (@pxref{Association Lists}) or hash tables
return the value to which it is bound. If @var{obarray} is @code{#f}, (@pxref{Hash Tables}), because this usage improves the readability a
use the global symbol table. If @var{string} is not interned in lot, and does not cause any performance loss.
@var{obarray}, an error is signalled.
@end deffn
@deffn {Scheme Procedure} symbol-bound? obarray string
Return @code{#t} if @var{obarray} contains a symbol with name @node Symbol Props
@var{string} bound to a defined value. This differs from @subsection Function Slots and Property Lists
@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
@deffn {Scheme Procedure} symbol-fref symbol @deffn {Scheme Procedure} symbol-fref symbol
@deffnx {C Function} scm_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. Change the binding of @var{symbol}'s function slot.
@end deffn @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 @deffn {Scheme Procedure} symbol-pref symbol
@deffnx {C Function} scm_symbol_pref (symbol) @deffnx {C Function} scm_symbol_pref (symbol)
Return the @dfn{property list} currently associated with @var{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. Change the binding of @var{symbol}'s property slot.
@end deffn @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 @node Keywords
@section Keywords @section Keywords
@ -2777,8 +2542,8 @@ Or, even more economically, like this:
@end lisp @end lisp
For further details on @code{let-keywords}, @code{define*} and other For further details on @code{let-keywords}, @code{define*} and other
facilities provided by the @code{(ice-9 optargs)} module, @ref{Optional facilities provided by the @code{(ice-9 optargs)} module, see
Arguments}. @ref{Optional Arguments}.
@node Keyword Read Syntax @node Keyword Read Syntax
@ -2786,10 +2551,11 @@ Arguments}.
Guile, by default, only recognizes the keyword syntax specified by R5RS. 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 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 as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external
@code{NAME}. Keyword objects print using this syntax as well, so values representation of the keyword named @code{NAME}. Keyword objects print
containing keyword objects can be read back into Guile. When used in an using this syntax as well, so values containing keyword objects can be
expression, keywords are self-quoting objects. 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 If the @code{keyword} read option is set to @code{'prefix}, Guile also
recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
@ -2817,7 +2583,7 @@ interface} and @ref{Reader options}.
#:type #:type
:type :type
@result{} @print{}
ERROR: In expression :type: ERROR: In expression :type:
ERROR: Unbound variable: :type ERROR: Unbound variable: :type
ABORT: (unbound-variable) ABORT: (unbound-variable)

81
doc/ref/scheme-modules.texi
View file

@ -32,10 +32,14 @@ designed languages: ML, Python, Perl, and Modula 3 all allow the
clutter the global name space. clutter the global name space.
@cindex name space - private @cindex name space - private
In addition, Guile offers variables as first-class objects. They can
be used for interacting with the module system.
@menu @menu
* Scheme and modules:: How modules are handled in standard Scheme. * Scheme and modules:: How modules are handled in standard Scheme.
* The Guile module system:: How Guile does it. * The Guile module system:: How Guile does it.
* Dynamic Libraries:: Loading libraries of compiled code at run time. * Dynamic Libraries:: Loading libraries of compiled code at run time.
* Variables:: First-class variables.
@end menu @end menu
@ -827,6 +831,83 @@ the same place on all machines (which seems like a good idea to me
anyway). 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 Local Variables:
@c TeX-master: "guile.texi" @c TeX-master: "guile.texi"
@c End: @c End: