Symbols and Variables
=====================
Guile symbol tables are hash tables. Each hash table, also called an
"obarray" (for `object array'), is a vector of association lists. Each
entry in the alists is a pair (SYMBOL . VALUE). To "intern" a symbol
in a symbol table means to return its (SYMBOL . VALUE) pair, adding a
new entry to the symbol table (with an undefined value) if none is yet
present.
- primitive: builtin-bindings
Create and return a copy of the global symbol table, removing all
unbound symbols.
- primitive: gensym [prefix]
Create a new symbol with name constructed from a prefix and a
counter value. The string PREFIX can be specified as an optional
argument. Default prefix is `g'. The counter is increased by 1
at each call. There is no provision for resetting the counter.
- primitive: gentemp [prefix [obarray]]
Create a new symbol with a name unique in an obarray. The name is
constructed from an optional string PREFIX and a counter value.
The default prefix is T. The 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.
- primitive: intern-symbol obarray string
Add a new symbol to OBARRAY with name STRING, bound to an
unspecified initial value. The symbol table is not modified if a
symbol with this name is already present.
- primitive: string->obarray-symbol obarray string [soft?]
Intern a new symbol in OBARRAY, a symbol table, with name STRING.
If OBARRAY is `#f', use the default system symbol table. If
OBARRAY is `#t', the symbol should not be interned in any symbol
table; merely return the pair (SYMBOL . #<UNDEFINED>).
The SOFT? argument determines whether new symbol table entries
should be created when the specified symbol is not already present
in OBARRAY. If SOFT? is specified and is a true value, then new
entries should not be added for symbols not already present in the
table; instead, simply return `#f'.
- primitive: string->symbol string
Returns the symbol whose name is STRING. This procedure can
create symbols with names containing special characters or letters
in the non-standard case, but it is usually a bad idea to create
such symbols because in some implementations of Scheme they cannot
be read as themselves. See `symbol->string'.
The following examples assume that the implementation's standard
case is lower case:
(eq? 'mISSISSIppi 'mississippi)
==> #t
(string->symbol "mISSISSIppi")
==>
the symbol with name "mISSISSIppi"
(eq? 'bitBlt (string->symbol "bitBlt"))
==> #f
(eq? 'JollyWog
(string->symbol
(symbol->string 'JollyWog)))
==> #t
(string=? "K. Harper, M.D."
(symbol->string
(string->symbol "K. Harper, M.D.")))
==> #t
- primitive: symbol->string symbol
Returns the name of SYMBOL as a string. If the symbol was part of
an object returned as the value of a literal expression (section
Note:Literal expressions.) or by a
call to the `read' procedure, and its name contains alphabetic
characters, then the string returned will contain characters in the
implementation's preferred standard case--some implementations will
prefer upper case, others lower case. If the symbol was returned
by `string->symbol', the case of characters in the string returned
will be the same as the case in the string that was passed to
`string->symbol'. It is an error to apply mutation procedures like
`string-set!' to strings returned by this procedure. (r5rs)
The following examples assume that the implementation's standard
case is lower case:
(symbol->string 'flying-fish)
==> "flying-fish"
(symbol->string 'Martin) ==> "martin"
(symbol->string
(string->symbol "Malvina"))
==> "Malvina"
- primitive: symbol-binding obarray string
Look up in OBARRAY the symbol whose name is STRING, and return the
value to which it is bound. If OBARRAY is `#f', use the global
symbol table. If STRING is not interned in OBARRAY, an error is
signalled.
- primitive: symbol-bound? obarray string
Return #T if OBARRAY contains a symbol with name STRING bound to a
defined value. This differs from SYMBOL-BOUND? in that the mere
mention of a symbol usually causes it to be interned;
`symbol-bound?' determines whether a symbol has been given any
meaningful value.
- primitive: symbol-fref symbol
Return the contents of SYMBOL's "function slot".
- primitive: symbol-fset! symbol value
Change the binding of SYMBOL's function slot.
- primitive: symbol-hash symbol
Return a hash value for SYMBOL.
- primitive: symbol-interned? obarray string
Return #T if OBARRAY contains a symbol with name STRING, and #F
otherwise.
- primitive: symbol-pref symbol
Return the "property list" currently associated with SYMBOL.
- primitive: symbol-pset! symbol value
Change the binding of SYMBOL's property slot.
- primitive: symbol-set! obarray string value
Find the symbol in OBARRAY whose name is STRING, and rebind it to
VALUE. An error is signalled if STRING is not present in OBARRAY.
- primitive: symbol? obj
Returns #t if OBJ is a symbol, otherwise returns #f. (r5rs)
- primitive: unintern-symbol obarray string
Remove the symbol with name STRING from OBARRAY. This function
returns `#t' if the symbol was present and `#f' otherwise.
- primitive: builtin-variable name
Return the built-in variable with the name NAME. NAME must be a
symbol (not a string). Then use `variable-ref' to access its
value.
- primitive: make-undefined-variable [name-hint]
Return a variable object initialized to an undefined value. If
given, uses NAME-HINT as its internal (debugging) name, otherwise
just treat it as an anonymous variable. Remember, of course, that
multiple bindings to the same variable may exist, so NAME-HINT is
just that--a hint.
- primitive: make-variable init [name-hint]
Return a variable object initialized to value INIT. If given,
uses NAME-HINT as its internal (debugging) name, otherwise just
treat it as an anonymous variable. Remember, of course, that
multiple bindings to the same variable may exist, so NAME-HINT is
just that--a hint.
- primitive: variable-bound? var
Return `#t' iff VAR is bound to a value. Throws an error if VAR
is not a variable object.
- primitive: variable-ref var
Dereference VAR and return its value. VAR must be a variable
object; see `make-variable' and `make-undefined-variable'.
- primitive: variable-set! var val
Set the value of the variable VAR to VAL. VAR must be a variable
object, VAL can be any value. Returns an unspecified value.
- primitive: variable? obj
Return `#t' iff OBJ is a variable object, else return `#f'.