suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve docs on gensym', generate-temporaries', and compiled code

Browse Source
This commit is contained in:
Matthew Flatt 2012-07-06 13:16:15 -06:00
parent 2b9f57b01d
commit 4c469d5338
2 changed files with 24 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
collects/scribblings/reference/printer.scrbl
View File

@ -527,14 +527,26 @@ representation. @tech{Unreadable symbols}, which are typically
generated indirectly during expansion and compilation, are saved and
restored consistently through @litchar{#~}.
Due to the restrictions on @tech{uninterned} symbols in @litchar{#~},
do not use @racket[gensym] or @racket[string->uninterned-symbol] to
construct an identifier for a top-level or module binding. Instead,
generate distinct identifiers either with
@racket[generate-temporaries] or by applying the result of
@racket[make-syntax-introducer] to an existing identifier; those
functions will lead to top-level and module bindings with
@tech{unreadable symbol}ic names.
The dynamic nature @tech{uninterned} symbols and their localization
within @litchar{#~} can cause problems when @racket[gensym] or
@racket[string->uninterned-symbol] is used to construct an identifier
for a top-level or module binding (depending on how the identifier and
its references are compiled). To avoid problems, generate distinct
identifiers either with @racket[generate-temporaries] or by applying
the result of @racket[make-syntax-introducer] to an existing
identifier; those functions lead to top-level and module variables
with @tech{unreadable symbol}ic names, and the names are deterministic
as long as expansion is otherwise deterministic.
Despite the problems inherent with @tech{uninterned} symbols as
variable names, they are partially supported even across multiple
@litchar{#~}s: When compiled code contains a reference to a module-defined
variable whose name is an @tech{uninterned} symbol, the relative
position of the variable among the module's definitions is recorded,
and the reference can be linked back to the definition based on its
position and the characters in its name. This accommodation works only
for variable references in compiled code; it does not work for
@racket[syntax]-quoted identifiers, for example.
Finally, a compiled form may contain path literals. Although paths are
not normally printed in a way that can be read back in, path literals

7
collects/scribblings/reference/stx-ops.scrbl
View File

@ -285,9 +285,10 @@ must be a syntax pair that can be flattened into a list. The elements
of @racket[stx-pair] can be anything, but string, symbol, keyword
(possibly wrapped as syntax), and identifier elements will be embedded
in the corresponding generated name, which is useful for debugging
purposes. The generated identifiers are built with interned symbols
(not @racket[gensym]s), so the limitations described with
@racket[current-compile] do not apply.}
purposes.
The generated identifiers are built with interned symbols (not
@racket[gensym]s); see also @secref["print-compiled"].}
@defproc[(identifier-prune-lexical-context [id-stx identifier?]