7.3.2 The global-env field

Accessor for <library>: library-global-env lib

Return the lexical environment exported by the <library> object lib.

The global-env is a data structure used to map the label gensyms of top level syntactic bindings defined by a library to the corresponding storage location gensyms. “Top level bindings” does not mean “exported bindings”: not all the entries in global-env represent exported bindings, it is the role of the export-subst to select the exported ones.

An global-env is an alist whose entries have the format:

(?label . ?export-descriptor)

and ?export-descriptor has the format:

(?binding-type . ?binding-value)

where: ?label is the syntactic binding’s label gensym; ?binding-type is a symbol representing the syntactic binding’s type; the format of ?binding-value depends upon the type.

The symbol ?binding-type is one among:

global

Denotes a syntactic binding representing a variable binding which is never assigned in the code (it is initialised to a value and that value never changes). The export descriptor has the format:

(global . ?lex/loc)

where ?lex/loc is a gensym acting both as lexical gensym and storage location gensym; after the library is invoked: the loc gensym holds the variable’s value in its value slot (immutable). This binding can be exported.

mutable

Denotes a syntactic binding representing a variable binding which is assigned somewhere in the code. The export descriptor has the format:

(mutable . ?lex/loc)

where ?lex/loc is a gensym acting both as lexical gensym and storage location gensym; after the library is invoked: the loc gensym holds the variable’s value in its value slot (mutable). This binding cannot be exported.

global-macro

Denotes a syntactic binding representing a non–variable macro. The export descriptor has the format:

(global-macro . ?loc)

where ?loc is the storage location gensym; after the library has been visited: ?loc holds the macro transformer in its value slot. This binding can be exported.

Syntactic bindings of this type are established by uses of define-syntax, let-syntax and similar when the result of evaluating the right–hand side expression is a function.

global-macro!

Denotes a syntactic binding representing a variable macro. The export descriptor has the format:

(global-macro! . ?loc)

where ?loc is the storage location gensym; after the library has been visited: ?loc holds the macro transformer in its value slot. This binding can be exported.

Syntactic bindings of this type are established by uses of define-syntax, let-syntax and similar when the result of evaluating the right–hand side expression is the return value of a call to make-variable-transformer.

global-etv

Denotes a syntactic binding representing an expand–time value. The export descriptor has the format:

(global-etv . ?loc)

where ?loc is the storage location gensym; after the library has been visited: ?loc holds the actual expand–time object. This binding can be exported.

Syntactic bindings of this type are established by define-syntax, let-syntax and similar when the result of evaluating their right–hand side expression is the return value of a call to make-expand-time-value.

$struct-type-descriptor

Denotes a syntactic binding representing a Vicare’s struct–type name. The export descriptor has the format:

($struct-type-descriptor . ?type-descriptor-struct)

where ?type-descriptor-struct is a struct representing the struct–type descriptor.

Syntactic bindings of this type are established by uses of the syntax define-struct.

$record-type-descriptor

Denotes a syntactic binding representing a R6RS record–type name. The export descriptor has one of the formats:

($record-type-descriptor . (?rtd-id ?rcd-id))
($record-type-descriptor . (?rtd-id ?rcd-id . ?spec))

where: ?rtd-id is the syntactic identifier to which the record–type descriptor is bound; ?rcd-id is the syntactic identifier to which the default record–constructor descriptor is bound; ?spec is an instance of record type r6rs-record-type-spec.

Syntactic bindings of this type are established by uses of the syntaxes define-record-type and define-condition-type.

$module

Denotes a syntactic binding representing a module interface. The export descriptor has format:

($module . ?module-interface)

where ?module-interface is a record of type module-interface.

Syntactic bindings of this type are established by uses of the syntax module.

$fluid

Denotes a syntactic binding representing a fluid syntax. The export descriptor has format:

($fluid . ?fluid-label)

where ?fluid-label is the label gensym associated to the fluid syntax.

$synonym

Denotes a syntactic binding representing a synonym syntax. The export descriptor has format:

($synonym . ?synonym-label)

where ?synonym-label is the label gensym associated to the aliased syntax.

Example library

We can toy with the global-env with the following program:

(import (vicare)
  (vicare libraries))

(library (demo)
  (export var macro var-macro macro-id
          etv color <color> modu fluid synonym alias)
  (import (vicare))
  (define var 1)
  (define (fun) 2)
  (define-syntax macro (lambda (stx) 3))
  (define-syntax macro-id (identifier-syntax 4))
  (define-syntax var-macro
    (make-variable-transformer (lambda (stx) 5)))
  (define-syntax etv (make-expand-time-value 6))
  (module modu (modu-var) (define modu-var 7))
  (define-fluid-syntax fluid (lambda (stx) 8))
  (define-syntax synonym (make-synonym-transformer #'var))
  (define-alias alias var)
  (define-struct color (red green blue))
  (define-record-type <color> (fields red green blue))
  (define mvar 9)
  (set! mvar 10)
  #| end of library |# )

(define lib
  (find-library-by-name '(demo)))

(print-gensym #f)
(pretty-print
 (library-global-env lib))

(flush-output-port (current-output-port))