47 |
* Characters:: New character names. |
* Characters:: New character names. |
48 |
* Strings:: Special things about strings. |
* Strings:: Special things about strings. |
49 |
* Regular Expressions:: Pattern matching and substitution. |
* Regular Expressions:: Pattern matching and substitution. |
50 |
* Symbols and Variables:: Manipulating the Scheme symbol table. |
* Symbols:: Symbols. |
51 |
* Keywords:: Self-quoting, customizable display keywords. |
* Keywords:: Self-quoting, customizable display keywords. |
52 |
* Pairs:: Scheme's basic building block. |
* Pairs:: Scheme's basic building block. |
53 |
* Lists:: Special list functions supported by Guile. |
* Lists:: Special list functions supported by Guile. |
1427 |
* String Searching:: Searching in strings. |
* String Searching:: Searching in strings. |
1428 |
* Alphabetic Case Mapping:: Convert the alphabetic case of strings. |
* Alphabetic Case Mapping:: Convert the alphabetic case of strings. |
1429 |
* Appending Strings:: Appending strings to form a new string. |
* Appending Strings:: Appending strings to form a new string. |
|
* String Miscellanea:: Miscellaneous string procedures. |
|
1430 |
@end menu |
@end menu |
1431 |
|
|
1432 |
@node String Syntax |
@node String Syntax |
1822 |
@end deffn |
@end deffn |
1823 |
|
|
1824 |
|
|
|
@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 |
|
|
|
|
|
|
|
1825 |
@node Regular Expressions |
@node Regular Expressions |
1826 |
@section Regular Expressions |
@section Regular Expressions |
1827 |
@tpindex Regular expressions |
@tpindex Regular expressions |
1847 |
* Regexp Functions:: Functions that create and match regexps. |
* Regexp Functions:: Functions that create and match regexps. |
1848 |
* Match Structures:: Finding what was matched by a regexp. |
* Match Structures:: Finding what was matched by a regexp. |
1849 |
* 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. |
|
1850 |
@end menu |
@end menu |
1851 |
|
|
1852 |
[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 |
2158 |
confusing extension when implemented in other languages), we must adhere |
confusing extension when implemented in other languages), we must adhere |
2159 |
to this cumbersome escape syntax. |
to this cumbersome escape syntax. |
2160 |
|
|
|
@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 |
|
2161 |
|
|
2162 |
@c FIXME::martin: Review me! |
@node Symbols |
2163 |
|
@section Symbols |
2164 |
Symbols are a data type with a special property. On the one hand, |
@tpindex Symbols |
|
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. |
|
2165 |
|
|
2166 |
In addition, Guile offers variables as first-class objects. They can |
Symbols have two main uses. Crucially, they are used for denoting |
2167 |
be used for interacting with the module system. |
variables in a Scheme program. In addition, they are very useful for |
2168 |
|
describing discrete literal data. |
2169 |
|
|
2170 |
|
A symbol is an object with a name that consists of a string of |
2171 |
|
characters. In the usual case (where the name doesn't include any |
2172 |
|
characters that could be confused with other elements of Scheme syntax) |
2173 |
|
a symbol can be written in a Scheme program by writing the sequence of |
2174 |
|
characters that make up the symbol's name. For example, the read syntax |
2175 |
|
for the symbol named "multiply-by-2" is simply |
2176 |
|
|
2177 |
|
@lisp |
2178 |
|
multiply-by-2 |
2179 |
|
@end lisp |
2180 |
|
|
2181 |
|
Symbols, then, look rather like strings but without any quotation marks. |
2182 |
|
But there are several functional differences between them. The first |
2183 |
|
big functional difference between symbols and strings concerns |
2184 |
|
uniqueness. If the same-looking string is read twice from two different |
2185 |
|
places in a program, the result is two @emph{distinguishable} string |
2186 |
|
objects whose contents just happen to be the same. If, on the other |
2187 |
|
hand, the same-looking symbol is read twice from two different places in |
2188 |
|
a program, the result is the @emph{same} symbol object both times. |
2189 |
|
|
2190 |
|
@lisp |
2191 |
|
(define str1 "hello") |
2192 |
|
(define str2 "hello") |
2193 |
|
(eq? str1 str2) @result{} #f |
2194 |
|
|
2195 |
|
(define sym1 (quote hello)) |
2196 |
|
(define sym2 (quote hello)) |
2197 |
|
(eq? sym1 sym2) @result{} #t |
2198 |
|
@end lisp |
2199 |
|
|
2200 |
|
The second important difference is that symbols, unlike strings, are not |
2201 |
|
self-evaluating. An unquoted symbol is interpreted as a variable |
2202 |
|
reference, and the result of evaluating that symbol is the corresponding |
2203 |
|
variable's value. (By the way, this is why we needed the @code{(quote |
2204 |
|
@dots{})}s in the example above: @code{(quote hello)} returns the symbol |
2205 |
|
object named "hello" itself, whereas an unquoted @code{hello} would try |
2206 |
|
to find and dereference a variable associated with that symbol.) |
2207 |
|
|
2208 |
|
For example, when the expression @code{(string-length "abcd")} is read |
2209 |
|
and evaluated, the sequence of characters @code{string-length} is read |
2210 |
|
as the symbol whose name is "string-length". This symbol is associated |
2211 |
|
with a variable whose value is the procedure that implements string |
2212 |
|
length calculation. Therefore evaluation of the @code{string-length} |
2213 |
|
symbol results in that procedure. |
2214 |
|
|
2215 |
|
Although the use of symbols for variable references is undoubtedly their |
2216 |
|
most important role in Scheme, it is not documented further here. See |
2217 |
|
instead @ref{Binding Constructs}, for how associations between symbols |
2218 |
|
and variables are created, and @ref{Modules}, for how those associations |
2219 |
|
are affected by Guile's module system. The rest of this section |
2220 |
|
explains how symbols can also be used to represent discrete values, and |
2221 |
|
documents the procedures available that relate to symbols as data |
2222 |
|
objects @i{per se}. |
2223 |
|
|
2224 |
@menu |
@menu |
2225 |
* Symbols:: All about symbols as a data type. |
* Symbol Read Syntax:: Extended read syntax for symbols. |
2226 |
* Symbol Tables:: Tables for mapping symbols to values. |
* Symbol Primitives:: Operations related to symbols. |
2227 |
* Variables:: First-class variables. |
* Symbol Discrete:: Using symbols as discrete values. |
2228 |
|
* Symbol Props:: Function slots and property lists. |
2229 |
@end menu |
@end menu |
2230 |
|
|
|
@node Symbols |
|
|
@subsection Symbols |
|
|
@tpindex Symbols |
|
|
|
|
|
@c FIXME::martin: Review me! |
|
2231 |
|
|
2232 |
Symbols are especially useful because two symbols which are spelled the |
@node Symbol Read Syntax |
2233 |
same way are equivalent in the sense of @code{eq?}. That means that |
@subsection Extended Read Syntax for Symbols |
|
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. |
|
2234 |
|
|
2235 |
The read syntax for symbols is a sequence of letters, digits, and |
The read syntax for symbols is a sequence of letters, digits, and |
2236 |
@dfn{extended alphabetic characters} that begins with a character that |
@dfn{extended alphabetic characters}, beginning with a character that |
2237 |
cannot begin a number is an identifier. In addition, @code{+}, |
cannot begin a number. In addition, the special cases of @code{+}, |
2238 |
@code{-}, and @code{...} are identifiers. |
@code{-}, and @code{...} are read as symbols even though numbers can |
2239 |
|
begin with @code{+}, @code{-} or @code{.}. |
2240 |
|
|
2241 |
Extended alphabetic characters may be used within identifiers as if |
Extended alphabetic characters may be used within identifiers as if |
2242 |
they were letters. The following are extended alphabetic characters: |
they were letters. The set of extended alphabetic characters is: |
2243 |
|
|
2244 |
@example |
@example |
2245 |
! $ % & * + - . / : < = > ? @@ ^ _ ~ |
! $ % & * + - . / : < = > ? @@ ^ _ ~ |
2246 |
@end example |
@end example |
2247 |
|
|
2248 |
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 |
2249 |
(@pxref{Formal syntax,,,r5rs,The Revised^5 Report on Scheme})), Guile |
from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on |
2250 |
provides a method for writing symbols with unusual characters, such as |
Scheme})), Guile provides an extended symbol read syntax that allows the |
2251 |
space characters. If you (for whatever reason) need to write a symbol |
inclusion of unusual characters such as space characters, newlines and |
2252 |
containing characters not mentioned above, you write symbols as follows: |
parentheses. If (for whatever reason) you need to write a symbol |
2253 |
|
containing characters not mentioned above, you can do so as follows. |
2254 |
|
|
2255 |
@itemize @bullet |
@itemize @bullet |
2256 |
@item |
@item |
2257 |
Begin the symbol with the two character @code{#@{}, |
Begin the symbol with the characters @code{#@{}, |
2258 |
|
|
2259 |
@item |
@item |
2260 |
write the characters of the symbol and |
write the characters of the symbol and |
2263 |
finish the symbol with the characters @code{@}#}. |
finish the symbol with the characters @code{@}#}. |
2264 |
@end itemize |
@end itemize |
2265 |
|
|
2266 |
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 |
2267 |
containing a space character, the second containing a line break and the |
needs to use extended syntax because it contains a space character, the |
2268 |
last one looks like a number. |
second because it contains a line break, and the last because it looks |
2269 |
|
like a number. |
2270 |
|
|
2271 |
@lisp |
@lisp |
2272 |
#@{foo bar@}# |
#@{foo bar@}# |
2273 |
|
|
2274 |
#@{what |
#@{what |
2275 |
ever@}# |
ever@}# |
2276 |
|
|
2277 |
#@{4242@}# |
#@{4242@}# |
2278 |
@end lisp |
@end lisp |
2279 |
|
|
2280 |
Usage of this form of read syntax is discouraged, because it is not |
Although Guile provides this extended read syntax for symbols, |
2281 |
portable at all, and is not very readable. |
widespread usage of it is discouraged because it is not portable and not |
2282 |
|
very readable. |
2283 |
|
|
2284 |
|
|
2285 |
|
@node Symbol Primitives |
2286 |
|
@subsection Operations Related to Symbols |
2287 |
|
|
2288 |
@rnindex symbol? |
@rnindex symbol? |
2289 |
@deffn {Scheme Procedure} symbol? obj |
@deffn {Scheme Procedure} symbol? obj |
2317 |
@end lisp |
@end lisp |
2318 |
@end deffn |
@end deffn |
2319 |
|
|
2320 |
|
@deffn {Scheme Procedure} string-ci->symbol str |
2321 |
|
@deffnx {C Function} scm_string_ci_to_symbol (str) |
2322 |
|
Return the symbol whose name is @var{str}. @var{str} is |
2323 |
|
converted to lowercase before the conversion is done, if Guile |
2324 |
|
is currently reading symbols case-insensitively. |
2325 |
|
@end deffn |
2326 |
|
|
2327 |
@rnindex symbol->string |
@rnindex symbol->string |
2328 |
@deffn {Scheme Procedure} symbol->string s |
@deffn {Scheme Procedure} symbol->string s |
2329 |
@deffnx {C Function} scm_symbol_to_string (s) |
@deffnx {C Function} scm_symbol_to_string (s) |
2352 |
@end lisp |
@end lisp |
2353 |
@end deffn |
@end deffn |
2354 |
|
|
2355 |
@node Symbol Tables |
@deffn {Scheme Procedure} symbol-hash symbol |
2356 |
@subsection Symbol Tables |
@deffnx {C Function} scm_symbol_hash (symbol) |
2357 |
|
Return a hash value for @var{symbol}. |
2358 |
@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. |
|
2359 |
|
|
2360 |
@deffn {Scheme Procedure} gensym [prefix] |
@deffn {Scheme Procedure} gensym [prefix] |
2361 |
@deffnx {C Function} scm_gensym (prefix) |
@deffnx {C Function} scm_gensym (prefix) |
2366 |
resetting the counter. |
resetting the counter. |
2367 |
@end deffn |
@end deffn |
2368 |
|
|
2369 |
@deffn {Scheme Procedure} gentemp [prefix [obarray]] |
|
2370 |
Create a new symbol with a name unique in an obarray. |
@node Symbol Discrete |
2371 |
The name is constructed from an optional string @var{prefix} |
@subsection Using Symbols as Discrete Values |
2372 |
and a counter value. The default prefix is @code{t}. The |
|
2373 |
@var{obarray} is specified as a second optional argument. |
Symbols are especially useful because two symbols which are spelled the |
2374 |
Default is the system obarray where all normal symbols are |
same way are equivalent in the sense of @code{eq?}. That means that |
2375 |
interned. The counter is increased by 1 at each |
they are actually the same Scheme object. The advantage is that symbols |
2376 |
call. There is no provision for resetting the counter. |
can be compared extremely efficiently, although they carry more |
2377 |
@end deffn |
information for the human reader than, say, numbers. |
2378 |
|
|
2379 |
@deffn {Scheme Procedure} intern-symbol obarray string |
It is very common in Scheme programs to use symbols as keys in |
2380 |
Add a new symbol to @var{obarray} with name @var{string}, bound to an |
association lists (@pxref{Association Lists}) or hash tables |
2381 |
unspecified initial value. The symbol table is not modified if a symbol |
(@pxref{Hash Tables}), because this usage improves the readability a |
2382 |
with this name is already present. |
lot, and does not cause any performance loss. |
2383 |
@end deffn |
|
2384 |
|
|
2385 |
@deffn {Scheme Procedure} string->obarray-symbol obarray string [soft?] |
@node Symbol Props |
2386 |
Intern a new symbol in @var{obarray}, a symbol table, with name |
@subsection Function Slots and Property Lists |
|
@var{string}. |
|
|
@end deffn |
|
|
|
|
|
@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 |
|
|
|
|
|
@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 |
|
2387 |
|
|
2388 |
@deffn {Scheme Procedure} symbol-fref symbol |
@deffn {Scheme Procedure} symbol-fref symbol |
2389 |
@deffnx {C Function} scm_symbol_fref (symbol) |
@deffnx {C Function} scm_symbol_fref (symbol) |
2395 |
Change the binding of @var{symbol}'s function slot. |
Change the binding of @var{symbol}'s function slot. |
2396 |
@end deffn |
@end deffn |
2397 |
|
|
|
@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 |
|
|
|
|
2398 |
@deffn {Scheme Procedure} symbol-pref symbol |
@deffn {Scheme Procedure} symbol-pref symbol |
2399 |
@deffnx {C Function} scm_symbol_pref (symbol) |
@deffnx {C Function} scm_symbol_pref (symbol) |
2400 |
Return the @dfn{property list} currently associated with @var{symbol}. |
Return the @dfn{property list} currently associated with @var{symbol}. |
2405 |
Change the binding of @var{symbol}'s property slot. |
Change the binding of @var{symbol}'s property slot. |
2406 |
@end deffn |
@end deffn |
2407 |
|
|
|
@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 |
|
|
|
|
2408 |
|
|
2409 |
@node Keywords |
@node Keywords |
2410 |
@section Keywords |
@section Keywords |
2542 |
@end lisp |
@end lisp |
2543 |
|
|
2544 |
For further details on @code{let-keywords}, @code{define*} and other |
For further details on @code{let-keywords}, @code{define*} and other |
2545 |
facilities provided by the @code{(ice-9 optargs)} module, @ref{Optional |
facilities provided by the @code{(ice-9 optargs)} module, see |
2546 |
Arguments}. |
@ref{Optional Arguments}. |
2547 |
|
|
2548 |
|
|
2549 |
@node Keyword Read Syntax |
@node Keyword Read Syntax |
2551 |
|
|
2552 |
Guile, by default, only recognizes the keyword syntax specified by R5RS. |
Guile, by default, only recognizes the keyword syntax specified by R5RS. |
2553 |
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 |
2554 |
as a Scheme symbol, is the external representation of the keyword named |
as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external |
2555 |
@code{NAME}. Keyword objects print using this syntax as well, so values |
representation of the keyword named @code{NAME}. Keyword objects print |
2556 |
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 |
2557 |
expression, keywords are self-quoting objects. |
read back into Guile. When used in an expression, keywords are |
2558 |
|
self-quoting objects. |
2559 |
|
|
2560 |
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 |
2561 |
recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens |
recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens |
2583 |
#:type |
#:type |
2584 |
|
|
2585 |
:type |
:type |
2586 |
@result{} |
@print{} |
2587 |
ERROR: In expression :type: |
ERROR: In expression :type: |
2588 |
ERROR: Unbound variable: :type |
ERROR: Unbound variable: :type |
2589 |
ABORT: (unbound-variable) |
ABORT: (unbound-variable) |