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

reference: improve cross referencing on source locations

Browse Source 
Closes #2785
This commit is contained in:
Matthew Flatt 2021-04-29 13:09:26 -06:00
parent 0eeb8d26f3
commit 85e2282b66
3 changed files with 23 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
pkgs/racket-doc/scribblings/reference/exns.scrbl
View File

@ -981,6 +981,18 @@ Returns the @racket[srcloc]-getting procedure associated with @racket[v].}
[span (or/c exact-nonnegative-integer? #f)]) [span (or/c exact-nonnegative-integer? #f)])
#:inspector #f]{ #:inspector #f]{
A @deftech{source location} is most frequently represented by a
@racket[srcloc] structure. More generally, a source location has the
same information as a @racket[srcloc] structure, but potentially
represented or accessed differently. For example, source-location
information is accessed from a @tech{syntax object} with functions
like @racket[syntax-source] and @racket[syntax-line], while
@racket[datum->syntax] accepts a source location as a list, vector, or
another syntax object. For ports, a combination of
@racket[object-name] and @racket[port-next-location] provides location
information, especially in a port for which counting has been enabled
through @racket[port-count-lines!].
The fields of a @racket[srcloc] instance are as follows: The fields of a @racket[srcloc] instance are as follows:
@itemize[ @itemize[

15
pkgs/racket-doc/scribblings/reference/stx-ops.scrbl
View File

@ -35,7 +35,8 @@ Returns @racket[#t] if @racket[v] is a @tech{syntax object} and
@defproc[(syntax-source [stx syntax?]) any/c]{ @defproc[(syntax-source [stx syntax?]) any/c]{
Returns the source for the @tech{syntax object} @racket[stx], or @racket[#f] Returns the source component of the @tech{source location}
for the @tech{syntax object} @racket[stx], or @racket[#f]
if none is known. The source is represented by an arbitrary value if none is known. The source is represented by an arbitrary value
(e.g., one passed to @racket[read-syntax]), but it is typically a file (e.g., one passed to @racket[read-syntax]), but it is typically a file
path string.} path string.}
@ -44,7 +45,8 @@ path string.}
@defproc[(syntax-line [stx syntax?]) @defproc[(syntax-line [stx syntax?])
(or/c exact-positive-integer? #f)]{ (or/c exact-positive-integer? #f)]{
Returns the line number (positive exact integer) for the start of the Returns the line number (positive exact integer)
of the @tech{source location} for the start of the
@tech{syntax object} in its source, or @racket[#f] if the line number or @tech{syntax object} in its source, or @racket[#f] if the line number or
source is unknown. The result is @racket[#f] if and only if source is unknown. The result is @racket[#f] if and only if
@racket[(syntax-column stx)] produces @racket[#f]. See also @racket[(syntax-column stx)] produces @racket[#f]. See also
@ -54,7 +56,8 @@ source is unknown. The result is @racket[#f] if and only if
@defproc[(syntax-column [stx syntax?]) @defproc[(syntax-column [stx syntax?])
(or/c exact-nonnegative-integer? #f)]{ (or/c exact-nonnegative-integer? #f)]{
Returns the column number (non-negative exact integer) for the start Returns the column number (non-negative exact integer)
of the @tech{source location} for the start
of the @tech{syntax object} in its source, or @racket[#f] if the source of the @tech{syntax object} in its source, or @racket[#f] if the source
column is unknown. The result is @racket[#f] if and only if column is unknown. The result is @racket[#f] if and only if
@racket[(syntax-line stx)] produces @racket[#f]. See also @racket[(syntax-line stx)] produces @racket[#f]. See also
@ -64,7 +67,8 @@ column is unknown. The result is @racket[#f] if and only if
@defproc[(syntax-position [stx syntax?]) @defproc[(syntax-position [stx syntax?])
(or/c exact-positive-integer? #f)]{ (or/c exact-positive-integer? #f)]{
Returns the character position (positive exact integer) for the start Returns the character position (positive exact integer)
of the @tech{source location} for the start
of the @tech{syntax object} in its source, or @racket[#f] if the source of the @tech{syntax object} in its source, or @racket[#f] if the source
position is unknown. See also @secref["linecol"].} position is unknown. See also @secref["linecol"].}
@ -72,7 +76,8 @@ position is unknown. See also @secref["linecol"].}
@defproc[(syntax-span [stx syntax?]) @defproc[(syntax-span [stx syntax?])
(or/c exact-nonnegative-integer? #f)]{ (or/c exact-nonnegative-integer? #f)]{
Returns the span (non-negative exact integer) in characters of the Returns the span (non-negative exact integer) in characters
of the @tech{source location} for
@tech{syntax object} in its source, or @racket[#f] if the span is @tech{syntax object} in its source, or @racket[#f] if the span is
unknown.} unknown.}

2
pkgs/racket-doc/scribblings/reference/syntax-model.scrbl
View File

@ -156,7 +156,7 @@ relevant.
@section[#:tag "stxobj-model"]{Syntax Objects} @section[#:tag "stxobj-model"]{Syntax Objects}
A @deftech{syntax object} combines a simpler Racket value, such as a symbol or pair, with A @deftech{syntax object} combines a simpler Racket value, such as a symbol or pair, with
@tech{lexical information}, source-location information, @tech{syntax properties}, and @tech{tamper @tech{lexical information}, @tech{source-location} information, @tech{syntax properties}, and @tech{tamper
status}. The @deftech{lexical information} of a @tech{syntax object} comprises a set of @tech{scope status}. The @deftech{lexical information} of a @tech{syntax object} comprises a set of @tech{scope
sets}, one for each @tech{phase level}. In particular, an @tech{identifier} is represented as a syntax sets}, one for each @tech{phase level}. In particular, an @tech{identifier} is represented as a syntax
object containing a @tech{symbol}, and its @tech{lexical information} can be combined with the global object containing a @tech{symbol}, and its @tech{lexical information} can be combined with the global