23 Source Locations

There are two libraries in this collection for dealing with source locations; one for manipulating representations of them, and the other for quoting the location of a particular piece of source code.

23.1 Representations

(require unstable/srcloc)

This module defines utilities for manipulating representations of source locations, including both srcloc structures and all the values accepted by datum->syntax’s third argument: syntax objects, lists, vectors, and #f.

Examples:

> (source-location? #f)

#t

> (source-location? #'here)

#t

> (source-location? (make-srcloc 'here 1 0 1 0))

#t

> (source-location? (make-srcloc 'bad 1 #f 1 0))

#f

> (source-location? (list 'here 1 0 1 0))

#t

> (source-location? (list* 'bad 1 0 1 0 'tail))

#f

> (source-location? (vector 'here 1 0 1 0))

#t

> (source-location? (vector 'bad 0 0 0 0))

#f

Examples:

> (check-source-location! 'this-example #f)

> (check-source-location! 'this-example #'here)

> (check-source-location! 'this-example (make-srcloc 'here 1 0 1 0))

> (check-source-location! 'this-example (make-srcloc 'bad 1 #f 1 0))

this-example: expected a source location with line number

and column number both numeric or both #f; got 1 and #f

respectively: (srcloc 'bad 1 #f 1 0)

> (check-source-location! 'this-example (list 'here 1 0 1 0))

> (check-source-location! 'this-example (list* 'bad 1 0 1 0 'tail))

this-example: expected a source location (a list of 5

elements); got an improper list: '(bad 1 0 1 0 . tail)

> (check-source-location! 'this-example (vector 'here 1 0 1 0))

> (check-source-location! 'this-example (vector 'bad 0 0 0 0))

this-example: expected a source location with a positive

line number or #f (second element); got line number 0:

'#(bad 0 0 0 0)

Examples:

> (build-source-location)

(srcloc #f #f #f #f #f)

> (build-source-location-list)

'(#f #f #f #f #f)

> (build-source-location-vector)

'#(#f #f #f #f #f)

> (build-source-location-syntax)

#<syntax ()>

> (build-source-location #f)

(srcloc #f #f #f #f #f)

> (build-source-location-list #f)

'(#f #f #f #f #f)

> (build-source-location-vector #f)

'#(#f #f #f #f #f)

> (build-source-location-syntax #f)

#<syntax ()>

> (build-source-location (list 'here 1 2 3 4))

(srcloc 'here 1 2 3 4)

> (build-source-location-list (make-srcloc 'here 1 2 3 4))

'(here 1 2 3 4)

> (build-source-location-vector (make-srcloc 'here 1 2 3 4))

'#(here 1 2 3 4)

> (build-source-location-syntax (make-srcloc 'here 1 2 3 4))

#<syntax:1:2 ()>

> (build-source-location (list 'here 1 2 3 4) (vector 'here 5 6 7 8))

(srcloc 'here 1 2 3 12)

> (build-source-location-list (make-srcloc 'here 1 2 3 4) (vector 'here 5 6 7 8))

'(here 1 2 3 12)

> (build-source-location-vector (make-srcloc 'here 1 2 3 4) (vector 'here 5 6 7 8))

'#(here 1 2 3 12)

> (build-source-location-syntax (make-srcloc 'here 1 2 3 4) (vector 'here 5 6 7 8))

#<syntax:1:2 ()>

> (build-source-location (list 'here 1 2 3 4) (vector 'there 5 6 7 8))

(srcloc #f #f #f #f #f)

> (build-source-location-list (make-srcloc 'here 1 2 3 4) (vector 'there 5 6 7 8))

'(#f #f #f #f #f)

> (build-source-location-vector (make-srcloc 'here 1 2 3 4) (vector 'there 5 6 7 8))

'#(#f #f #f #f #f)

> (build-source-location-syntax (make-srcloc 'here 1 2 3 4) (vector 'there 5 6 7 8))

#<syntax ()>

Examples:

> (source-location-known? #f)

#f

> (source-location-known? (make-srcloc #f #f #f #f #f))

#f

> (source-location-known? (make-srcloc 'source 1 2 3 4))

#t

> (source-location-known? (list #f #f #f #f #f))

#f

> (source-location-known? (vector 'source #f #f #f #f))

#t

> (source-location-known? (datum->syntax #f null #f))

#t

> (source-location-known? (datum->syntax #f null (list 'source #f #f #f #f)))

#t

Examples:

> (source-location-source #f)

#f

> (source-location-line (make-srcloc 'source 1 2 3 4))

1

> (source-location-column (list 'source 1 2 3 4))

2

> (source-location-position (vector 'source 1 2 3 4))

3

> (source-location-span (datum->syntax #f null (list 'source 1 2 3 4)))

4

Examples:

> (source-location-end #f)

#f

> (source-location-end (make-srcloc 'source 1 2 3 4))

7

> (source-location-end (list 'source 1 2 3 #f))

#f

> (source-location-end (vector 'source 1 2 #f 4))

#f

Examples:

> (update-source-location #f #:source 'here)

'(here #f #f #f #f)

> (update-source-location (list 'there 1 2 3 4) #:line 20 #:column 79)

'(there 20 79 3 4)

> (update-source-location (vector 'everywhere 1 2 3 4) #:position #f #:span #f)

'#(everywhere 1 2 #f #f)

Examples:

> (source-location->string (make-srcloc 'here 1 2 3 4))

"here:1.2"

> (source-location->string (make-srcloc 'here #f #f 3 4))

"here::3-7"

> (source-location->string (make-srcloc 'here #f #f #f #f))

"here"

> (source-location->string (make-srcloc #f 1 2 3 4))

":1.2"

> (source-location->string (make-srcloc #f #f #f 3 4))

"::3-7"

> (source-location->string (make-srcloc #f #f #f #f #f))

""

> (source-location->prefix (make-srcloc 'here 1 2 3 4))

"here:1.2: "

> (source-location->prefix (make-srcloc 'here #f #f 3 4))

"here::3-7: "

> (source-location->prefix (make-srcloc 'here #f #f #f #f))

"here: "

> (source-location->prefix (make-srcloc #f 1 2 3 4))

":1.2: "

> (source-location->prefix (make-srcloc #f #f #f 3 4))

"::3-7: "

> (source-location->prefix (make-srcloc #f #f #f #f #f))

""

23.2 Quoting

(require unstable/location)

This module defines macros that evaluate to various aspects of their own source location.

Note: The examples below illustrate the use of these macros and the representation of their output. However, due to the mechanism by which they are generated, each example is considered a single character and thus does not have realistic line, column, and character positions.

Furthermore, the examples illustrate the use of source location quoting inside macros, and the difference between quoting the source location of the macro definition itself and quoting the source location of the macro’s arguments.

Examples:

> (quote-srcloc)

(srcloc 'eval 2 0 2 1)

> (define-syntax (not-here stx) #'(quote-srcloc))

> (not-here)

(srcloc 'eval 3 0 3 1)

> (not-here)

(srcloc 'eval 3 0 3 1)

> (define-syntax (here stx) #`(quote-srcloc #,stx))

> (here)

(srcloc 'eval 7 0 7 1)

> (here)

(srcloc 'eval 8 0 8 1)

Examples:

> (list (quote-source-file)           (quote-line-number)           (quote-column-number)           (quote-character-position)           (quote-character-span))

'(eval 2 0 2 1)

> (define-syntax (not-here stx)       #'(list (quote-source-file)               (quote-line-number)               (quote-column-number)               (quote-character-position)               (quote-character-span)))

> (not-here)

'(eval 3 0 3 1)

> (not-here)

'(eval 3 0 3 1)

> (define-syntax (here stx)       #`(list (quote-source-file #,stx)               (quote-line-number #,stx)               (quote-column-number #,stx)               (quote-character-position #,stx)               (quote-character-span #,stx)))

> (here)

'(eval 7 0 7 1)

> (here)

'(eval 8 0 8 1)

These forms use relative names for modules found in the collections or PLaneT cache; their results are suitable for printing, but not for accessing libraries programmatically, such as via dynamic-require.

Examples:

> (module A racket       (require unstable/location)       (define-syntax-rule (name) (quote-module-name))       (define-syntax-rule (path) (quote-module-path))       (define a-name (name))       (define a-path (path))       (provide (all-defined-out)))

> (require 'A)

> a-name

'A

> a-path

''A

> (module B racket       (require unstable/location)       (require 'A)       (define b-name (name))       (define b-path (path))       (provide (all-defined-out)))

> (require 'B)

> b-name

'B

> b-path

''B

> (quote-module-name)

'top-level

> (quote-module-path)

'top-level

> [current-namespace (module->namespace ''A)]

> (quote-module-name)

'A

> (quote-module-path)

''A