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

docs: clarifications on identifier-binding results

Browse Source
This commit is contained in:
Matthew Flatt 2021-03-17 19:16:29 -06:00
parent 9a329574b4
commit 56970fdae7
1 changed files with 46 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
pkgs/racket-doc/scribblings/reference/stx-comp.scrbl
View File

@ -120,55 +120,72 @@ or four (if @racket[top-level-symbol?] is true) kinds of values, depending on th
has a @tech{local binding}.}
@item{The result is a list of seven items when @racket[id-stx]
has a @tech{module binding}: @racket[(list _source-mod _source-id
_nominal-source-mod _nominal-source-id _source-phase _import-phase
has a @tech{module binding}: @racket[(list _from-mod _from-sym
_nominal-from-mod _nominal-from-sym _from-phase _import-phase
_nominal-export-phase)].
@itemize[
@item{@racket[_source-mod] is a module path index (see
@secref["modpathidx"]) that indicates the defining module.}
@item{@racket[_from-mod] is a module path index (see
@secref["modpathidx"]) that indicates the defining module. It
is the ``self'' module path index if the binding refers to a
definition in the enclosing module of @racket[id-stx].}
@item{@racket[_source-id] is a symbol for the identifier's name
at its definition site in the source module. This can be
@item{@racket[_from-sym] is a symbol for the identifier's name
at its definition site in the originating module. This can be
different from the local name returned by
@racket[syntax->datum] for several reasons: the identifier is
renamed on import, it is renamed on export, or it is
implicitly renamed because the identifier (or its import) was
generated by a macro invocation.}
implicitly renamed because the binding site was generated by a
macro invocation. In that last case, it may be an
@tech{unreadable symbol}, and it may be different from the
result of @racket[syntax->datum] on the identifier in the
original source definition.}
@item{@racket[_nominal-source-mod] is a module path index (see
@secref["modpathidx"]) that indicates the module
@racket[require]d into the context of @racket[id-stx] to
provide its binding. It can be different from
@racket[_source-mod] due to a re-export in
@racket[_nominal-source-mod] of some imported identifier. If
the same binding is imported in multiple ways, an arbitrary
@item{@racket[_nominal-from-mod] is a module path index (see
@secref["modpathidx"]) that indicates the binding's module as
it appears locally in the source around @racket[id-stx]: it
indicates a module @racket[require]d into the context of
@racket[id-stx] to provide its binding, or it is the same
``self'' as @racket[_from-mod] for a binding that refers to a
definition in the enclosing module of @racket[id-stx]. It can
be different from @racket[_from-mod] due to a re-export in
@racket[_nominal-from-mod] of some imported identifier. If the
same binding is imported in multiple ways, an arbitrary
representative is chosen.}
@item{@racket[_nominal-source-id] is a symbol for the
identifier's name as exported by
@racket[_nominal-source-mod]. It can be different from
@racket[_source-id] due to a renaming @racket[provide], even if
@racket[_source-mod] and @racket[_nominal-source-mod] are the
same.}
@item{@racket[_nominal-from-sym] is a symbol for the binding's
identifier as it appears locally in the source around
@racket[id-stx]: it is the identifier's name as exported by
@racket[_nominal-from-mod], or it is the source identifier's
symbol for a definition within the enclosing module of
@racket[id-stx]. It can be different from @racket[_from-sym]
due to a renaming @racket[provide], even if @racket[_from-mod]
and @racket[_nominal-from-mod] are the same, or due to a
definition that was introduced by a macro expansion.}
@item{@racket[_source-phase] is an exact non-negative integer
representing the source phase. For example, it is @racket[1] if the source
definition is for-syntax.}
@item{@racket[_from-phase] is an exact non-negative integer
representing the originating phase. For example, it is
@racket[1] if the definition is for-syntax.}
@item{@racket[_import-phase] is @racket[0] if the binding
import of @racket[_nominal-source-mode] is a plain
@racket[require], @racket[1] if it is from a
import of @racket[_nominal-from-mode] is from a definition
or a plain @racket[require], @racket[1] if it is from a
@racket[for-syntax] import, etc.}
@item{@racket[_nominal-export-phase] is the @tech{phase level}
of the export from @racket[_nominal-source-mod].}
of the export from @racket[_nominal-from-mod] for an
imported binding or the phase level of the definition for a
binding from the enclosing module of @racket[id-stx].}
]}
@item{The result is @racket[(list _source-id)] if @racket[id-stx] has a
@tech{top-level binding} and @racket[top-level-symbol?] is true.}
@item{The result is @racket[(list _top-sym)] if @racket[id-stx]
has a @tech{top-level binding} and
@racket[top-level-symbol?] is true. The @racket[_top-sym]
can different from the name returned by
@racket[syntax->datum] when the binding definition was
generated by a macro invocation.}
@item{The result is @racket[#f] if @racket[id-stx] has a
@tech{top-level binding} and @racket[top-level-symbol?] is