From 56970fdae76b3cccaaed3ea601d0428c30c5c60c Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 17 Mar 2021 19:16:29 -0600 Subject: [PATCH] docs: clarifications on `identifier-binding` results --- .../scribblings/reference/stx-comp.scrbl | 75 ++++++++++++------- 1 file changed, 46 insertions(+), 29 deletions(-) diff --git a/pkgs/racket-doc/scribblings/reference/stx-comp.scrbl b/pkgs/racket-doc/scribblings/reference/stx-comp.scrbl index e3c47bbfaf..7a3c327404 100644 --- a/pkgs/racket-doc/scribblings/reference/stx-comp.scrbl +++ b/pkgs/racket-doc/scribblings/reference/stx-comp.scrbl @@ -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