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