6.29.3 Symbol values

Under Vicare, Scheme symbols are data structures having a field value initialised, at symbol construction time, to the built–in value ‘#<unbound-object>’; this field has multiple purposes:

• When the symbol is the unique identifier of a Vicare data structure type: value holds the struct–type descriptor of the data structure.
• When the symbol is the unique identifier of a R6RS record type: value holds the type–descriptor of the record.
• When the symbol is the “public name” of a core primitive defined by Vicare (for example display or +): we have to assume that value holds a Scheme object for internal use by Vicare.
• When the symbol is a label gensym associated to a syntactic binding exported by the boot image: value holds the syntactic binding descriptor.
• When the symbol is a label gensym associated to a syntactic binding imported in the current lexical environment: value holds the syntactic binding descriptor.
• When the symbol is a storage location gensym (loc gensym) associated to a lexical syntactic binding: value holds the current value of the lexical variable.
• When the symbol is a fresh symbol returned by a call to gensym: we can use value for any purpose we want.

In practise, we should never use the value field of symbols unless they are gensyms we are using for a specific purpose, in which case the ability to associate a value with a symbol can be quite useful in building some form of associative array with distributed storage.

The following bindings are exported by the library (vicare).

Function: top-level-value loc

Expect the argument to be a loc gensym associated to a binding; extract the value from the slot value of the symbol object and return it. If the value is the unbound object: raise an exception.

This is both a primitive function and a core primitive operation.

NOTE In binary code, this function has a specific purpose: to retrieve the value of a binding defined in a previously evaluated expression in the context of an interaction environment; we have to know the internals of the expander to understand it. Let’s say we are evaluating expressions at the REPL; first we do:

vicare> (define a 1)

the expander creates a new top level binding in the interaction environment; such interaction environment bindings are special in that they have a single gensym to serve both as lex gensym and loc gensym; the expander transforms the input form into the core language form:

(set! lex.a 1)

where lex.a is both the lex gensym and the loc gensym associated to the binding; the compiler transforms the core language expression into:

($init-symbol-value! lex.a 1)

which, compiled and evaluated, will store the value in the value field of the gensym lex.a.

Later we do:

vicare> a

the expander finds the binding in the interaction environment and transforms the variable reference into the core language expression:

lex.a

the compiler then transforms the core language variable reference into:

(top-level-value 'lex.a)

which, compiled and evaluated, will return the binding’s value.

The same processing happens when we evaluate multiple expressions with eval in the context of the same interaction environment.

Function: top-level-bound? loc

Return #t if the symbol object loc has a proper value in its value field; return #f if the field value is set to the unbound object.

Function: set-top-level-value! loc value

This function can be used to set a new object in a loc gensym, so that it can be later retrieved by top-level-value.

Function: reset-symbol-proc! sym

sym is meant to be a location gensym. If the value currently in the field value of sym is a closure object: store such value also in the field proc of symX.

NOTE Whenever binary code performs a call to a global closure object, it does the following:

• From the relocation vector of the current code object: retrieve the loc gensym of the procedure to call.
• From the loc gensym: extract the value of the proc slot, which is meant to be a closure object. This is done by accessing the gensym object with a low–level assembly instruction, not by using the primitive operation $symbol-proc.
• Actually call the closure object.

Function: set-symbol-value! sym value

Store value in the value field of the symbol sym.

Function: symbol-value sym

Return the value in the value field of the symbol sym.

Function: symbol-bound? sym

Return true if sym is a symbol and its value field is not set to the built–in ‘#<unbound-object>’ machine word value.

Function: unbound-object

Return the unbound object.

Function: unbound-object? obj

Return #t if obj is the unbound object.