8 Check Syntax
Check Syntax is a part of the DrRacket collection, but is implemented via the tools API.
8.1 Accessing Check Syntax Programmatically
| (require drracket/check-syntax) | package: drracket |
procedure
(make-traversal namespace path) →
(->* (syntax?) ((-> any/c void?)) void?) (-> void?) namespace : namespace? path : (or/c #f path-string?)
This function creates some local state about a traversal of syntax objects
and returns two functions. The first one should be called with each of the
(fully expanded) syntax objects that make up a program (there will be only
one if the program is a module) and then the second one should be called to
indicate there are no more.
The optional argument to the first function is ignored. It is left there for historical reasons. In the past it was called for each sequence of binding identifiers encountered in define-values, define-syntaxes, and define-values-for-syntax.
During the dynamic extent of the call to the two result functions, the value of the current-annotations parameter is consulted and various methods are invoked in the corresponding object (if any), to indicate what has been found in the syntax object. These methods will only be called if the syntax objects have source locations.
parameter
→ (or/c #f (is-a?/c syncheck-annotations<%>)) (current-annotations ca) → void? ca : (or/c #f (is-a?/c syncheck-annotations<%>))
The methods of the value of this parameter are invoked by the functions returned
from make-traversal.
parameter
→ (or/c +inf.0 (and/c exact-integer? (>=/c 2))) (current-max-to-send-at-once m) → void? m : (or/c +inf.0 (and/c exact-integer? (>=/c 2)))
No longer used.
|
Classes implementing this interface are
accceptors of information about a traversal
of syntax objects. See make-traversal.
Do not implement this interface directly, as it
is liable to change without warning. Instead, use
the annotations-mixin and override
the methods you’re interested in. The
annotations-mixin will keep in sync
with this interface, providing methods that
ignore their arguments.
method
(send a-syncheck-annotations syncheck:find-source-object stx)
→ (or/c #f (not/c #f)) stx : syntax? This should return #f if the source of this syntax object is uninteresting for annotations (if, for example, the only interesting annotations are those in the original file and this is a syntax object introduced by a macro and thus has a source location from some other file).Otherwise, it should return some (non-#f) value that will then be passed to one of the other methods below as a source-obj argument.
method
(send a-syncheck-annotations syncheck:add-background-color source-obj start end color) → void? source-obj : (not/c #f) start : exact-nonnegative-integer? end : exact-nonnegative-integer? color : string? Called to indicate that the color color should be drawn on the background of the given range in the editor, when the mouse moves over it. This method is typically called in conjuction with some other method that provides some other annotation on the source.
method
(send a-syncheck-annotations syncheck:add-require-open-menu source-obj start end file) → void? source-obj : (not/c #f) start : exact-nonnegative-integer? end : exact-nonnegative-integer? file : path-string? Called to indicate that there is a require at the location from start to end, and that it corresponds to file. Check Syntax adds a popup menu.
method
(send a-syncheck-annotations syncheck:add-docs-menu source-obj start end id label path tag) → void? source-obj : (not/c #f) start : exact-nonnegative-integer? end : exact-nonnegative-integer? id : symbol? label : any/c path : any/c tag : any/c Called to indicate that there is something that has documentation between the range start and end. The documented identifier’s name is given by id and the docs are found in the html file path at the html tag tag. The label argument describes the binding for use in the menu item (although it may be longer than 200 characters).
method
(send a-syncheck-annotations syncheck:add-id-set all-ids new-name-interferes?) → void?
all-ids :
(listof (list/c (not/c #f) exact-nonnegative-integer? exact-nonnegative-integer?)) new-name-interferes? : (-> symbol boolean?) This method is no longer called by Check Syntax. It is here for backwards compatibility only. The information it provided must now be synthesized from the information supplied to syncheck:add-arrow/name-dup.
method
(send a-syncheck-annotations syncheck:add-arrow start-source-obj start-left start-right end-source-obj end-left end-right actual? phase-level) → void? start-source-obj : (not/c #f) start-left : exact-nonnegative-integer? start-right : exact-nonnegative-integer? end-source-obj : (not/c #f) end-left : exact-nonnegative-integer? end-right : exact-nonnegative-integer? actual? : boolean? phase-level : (or/c exact-nonnegative-integer? #f) This function is not called directly anymore by Check Syntax. Instead syncheck:add-arrow/name-dup is.This method is invoked by the default implementation of syncheck:add-arrow/name-dup in annotations-mixin.
method
(send a-syncheck-annotations syncheck:add-arrow/name-dup start-source-obj start-left start-right end-source-obj end-left end-right actual? phase-level require-arrow? name-dup?) → void? start-source-obj : (not/c #f) start-left : exact-nonnegative-integer? start-right : exact-nonnegative-integer? end-source-obj : (not/c #f) end-left : exact-nonnegative-integer? end-right : exact-nonnegative-integer? actual? : boolean? phase-level : (or/c exact-nonnegative-integer? #f) require-arrow? : boolean? name-dup? : (-> string? boolean?) Called to indicate that there should be an arrow between the locations described by the first six arguments.The phase-level argument indicates the phase of the binding and the actual? argument indicates if the binding is a real one, or a predicted one from a syntax template (predicted bindings are drawn with question marks in Check Syntax).
The require-arrow? argument indicates if this arrow points from an imported identifier to its corresponding require.
The name-dup? predicate returns #t in case that this variable (either the start or end), when replaced with the given string, would shadow some other binding (or otherwise interfere with the binding structure of the program at the time the program was expanded).
method
(send a-syncheck-annotations syncheck:add-tail-arrow from-source-obj from-pos to-source-obj to-pos) → void? from-source-obj : (not/c #f) from-pos : exact-nonnegative-integer? to-source-obj : (not/c #f) to-pos : exact-nonnegative-integer? Called to indicate that there are two expressions, beginning at from-pos and to-pos that are in tail position with respect to each other.
method
(send a-syncheck-annotations syncheck:add-mouse-over-status source-obj pos-left pos-right str) → void? source-obj : (not/c #f) pos-left : exact-nonnegative-integer? pos-right : exact-nonnegative-integer? str : string? Called to indicate that the message in str should be shown when the mouse passes over the given position.
method
(send a-syncheck-annotations syncheck:add-jump-to-definition source-obj start end id filename submods) → void? source-obj : (not/c #f) start : exact-nonnegative-integer? end : exact-nonnegative-integer? id : any/c filename : path-string? submods : (listof symbol?) Called to indicate that there is some identifier at the given location (named id) that is defined in the submods of the file filename (where an empty list in submods means that the identifier is defined at the top-level module).
method
(send a-syncheck-annotations syncheck:add-definition-target source-obj start finish style-name) → void? source-obj : (not/c #f) start : exact-nonnegative-integer? finish : exact-nonnegative-integer? style-name : any/c
method
(send a-syncheck-annotations syncheck:color-range source-obj start finish style-name mode) → void? source-obj : (not/c #f) start : exact-nonnegative-integer? finish : exact-nonnegative-integer? style-name : any/c mode : any/c Called to indicate that the given location should be colored according to the style style-name when in mode. The mode either indicates regular check syntax or is used indicate blame for potential contract violations (and still experimental).
method
(send a-syncheck-annotations syncheck:add-rename-menu id all-ids new-name-interferes?) → void? id : symbol?
all-ids :
(listof (list/c (not/c #f) exact-nonnegative-integer? exact-nonnegative-integer?)) new-name-interferes? : (-> symbol boolean?) This method is listed only for backwards compatibility. It is not called by Check Syntax anymore.
| ||
|
Supplies all of the methods in syncheck-annotations<%>
with default behavior. Be sure to use this mixin to future-proof
your code and then override the methods you’re interested in.
By default:
The syncheck:find-source-object method ignores its arguments and returns #f;
the syncheck:add-arrow/name-dup method drops the require-arrow? and name-dup? arguments and calls syncheck:add-arrow; and
all of the other methods ignore their arguments and return (void).
Here is an example showing how use this library to extract all
of the arrows that Check Syntax would draw from various
expressions. One subtle point: arrows are only included when
the corresponding identifiers are syntax-original?;
the code below manages this by copying the properties from
an identifier that is syntax-original? in the
call to datum->syntax.
> (require drracket/check-syntax racket/class)
> (define arrows-collector% (class (annotations-mixin object%) (super-new) (define/override (syncheck:find-source-object stx) stx) (define/override (syncheck:add-arrow/name-dup start-source-obj start-left start-right end-source-obj end-left end-right actual? phase-level require-arrow? name-dup?) (set! arrows (cons (list start-source-obj end-source-obj) arrows))) (define arrows '()) (define/public (get-collected-arrows) arrows)))
> (define (arrows form) (define base-namespace (make-base-namespace)) (define-values (add-syntax done) (make-traversal base-namespace #f)) (define collector (new arrows-collector%)) (parameterize ([current-annotations collector] [current-namespace base-namespace]) (add-syntax (expand form)) (done)) (send collector get-collected-arrows))
> (define (make-id name pos orig?) (datum->syntax #f name (list #f #f #f pos (string-length (symbol->string name))) (and orig? #'is-orig)))
> (arrows `(λ (,(make-id 'x 1 #t)) ,(make-id 'x 2 #t))) '((#<syntax::1 x> #<syntax::2 x>))
> (arrows `(λ (x) x)) '()
> (arrows `(λ (,(make-id 'x 1 #f)) ,(make-id 'x 2 #t))) '()
> (arrows `(λ (,(make-id 'x 1 #t)) x)) '()
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
syntax
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
syntax
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
syntax
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
syntax
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
syntax
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
syntax
Bound to an identifier created with
define-local-member-name
that is used in syncheck-annotations<%>.
8.2 Check Syntax Button
| (require drracket/syncheck-drracket-button) | |
| package: drracket | |
value
syncheck-drracket-button :
(list/c string? (is-a?/c bitmap%) (-> (is-a?/c top-level-window<%>) any))
This is meant to be used with the 'drracket:toolbar-buttons
argument to the info proc returned
from read-language.
syntax
This is defined with define-local-member-name and
is bound to a method of no arguments of the DrRacket frame that runs Check
Syntax.
value
The bitmap in the Check Syntax button on the DrRacket frame.
8.3 Syntax Properties that Check Syntax Looks For
Check Syntax collects the values of the syntax-propertys named 'disappeared-use, 'disappeared-binding, and 'sub-range-binders, and uses them to add additional arrows to the program text. These properties are intended for use when a macro discards or manufactures identifiers that, from the programmers perspective, should be binding each other.
For example, here is a macro that discards its arguments, but adds properties to the result syntax object so the arguments are treated as a binding/bound pair by Check Syntax.
(define-syntax (m stx) (syntax-case stx () [(_ id1 id2) (and (identifier? #'id1) (identifier? #'id2)) (syntax-property (syntax-property #'1 'disappeared-use (list (syntax-local-introduce #'id1))) 'disappeared-binding (list (syntax-local-introduce #'id2)))]))
See also current-recorded-disappeared-uses.
The value of the 'sub-range-binders property is expected
to be a tree of cons pairs (in any configuration) whose leaves
are either ignored or are vectors of the shape
(vector/c syntax? exact-nonnegative-integer? exact-nonnegative-integer? syntax? exact-nonnegative-integer? exact-nonnegative-integer?)
.
If the leaf is a vector, the first syntax object is expected to be an identifier whose
bound occurrences should have arrows that point to the syntax object in the fourth
position in the vector. The numbers indicate the starting point and the range inside
the corresponding identifier to consider as the location of the end of the arrow.
Here’s an example:
#lang racket/base (require (for-syntax racket/base)) (define-syntax (define/hyphen stx) (syntax-case stx () [(_ id1 id2 rhs-expr) (let () (define first-part (symbol->string (syntax-e #'id1))) (define second-part (symbol->string (syntax-e #'id2))) (define first-len (string-length first-part)) (define second-len (string-length second-part)) (define hyphenated-id (datum->syntax #'id1 (string->symbol (string-append first-part "-" second-part)))) (syntax-property #`(define #,hyphenated-id rhs-expr) 'sub-range-binders (list (vector (syntax-local-introduce hyphenated-id) 0 first-len (syntax-local-introduce #'id1) 0 first-len) (vector (syntax-local-introduce hyphenated-id) (+ first-len 1) second-len (syntax-local-introduce #'id2) 0 second-len))))])) (define/hyphen big generator 11) (+ big-generator big-generator)
After putting this code in the DrRacket window, mouse over the words “big” and “generator” to see arrows pointing to the individual pieces of the identifier big-generator.
Finally, Check Syntax only draws arrows between identifiers that are syntax-original? or that have the syntax-property 'original-for-check-syntax set to #t.