format-id-record-untyped.scrbl (5783B)
1 #lang scribble/manual 2 @require[racket/require 3 "utils.rkt" 4 scribble/struct 5 scribble/decode 6 @for-label[phc-toolkit/untyped-only/format-id-record 7 phc-toolkit/stx 8 racket/syntax 9 syntax/parse 10 racket/contract 11 racket/base]] 12 @title[#:tag "phc-toolkit-format-id-record"]{Formatting identifiers so that 13 DrRacket still shows arrows} 14 @author{@author+email["Suzanne Soy" "racket@suzanne.soy"]} 15 @defmodule[phc-toolkit/untyped-only/format-id-record 16 #:use-sources 17 [(lib "phc-toolkit/untyped-only/format-id-record.rkt")]] 18 19 @defproc[(format-id/record [lctx (or/c syntax? #f)] 20 [fmt (stx-e/c 21 (and/c string? 22 (regexp-match/c "^([^~]|~~|~a|~A)*$")))] 23 [#:source src (or/c syntax? #f) #f] 24 [#:props props (or/c syntax? #f) #f] 25 [vs (or/c string? symbol? keyword? char? number? 26 (syntax/c string?) 27 identifier? 28 (syntax/c keyword?) 29 (syntax/c char?) 30 (syntax/c number?))] 31 ...) 32 identifier?]{ 33 Like @racket[format-id], but cooperates with @racket[with-sub-range-binders] 34 to record sub-range binders, which allow DrRacket to draw arrows from the 35 identifiers present in @racket[vs ...] to occurrences of the resulting 36 identifier. It also means that when one or more identifiers present in 37 @racket[vs ...] are concatenated with other strings, it is possible to rename 38 parts of the resulting identifier in DrRacket. 39 40 If @racket[fmt] is a syntax object containing a string, then arrows are drawn 41 from the format itself to the generated identifier, for each part of the 42 format which appears in the identifier (e.g. if the format is 43 @racket["x~~y~az"], then two arrows will be drawn from the format, one for 44 @racket["x~~y"], and one for @racket["z"]. 45 46 This function must be called within the dynamic extent of 47 @racket[with-sub-range-binders] or @racket[with-arrows].} 48 49 @defform[(with-sub-range-binders body-expr ... stx-expr)]{ 50 The value produced by @racket[stx-expr] must be a syntax object. All 51 @seclink["Syntax_Properties_that_Check_Syntax_Looks_For" 52 #:doc '(lib "scribblings/tools/tools.scrbl")]{sub-range binders} 53 recorded via @racket[record-sub-range-binders!] or 54 @racket[maybe-record-sub-range-binders!] are added to the syntax object in a 55 @seclink["Syntax_Properties_that_Check_Syntax_Looks_For" 56 #:doc '(lib "scribblings/tools/tools.scrbl") 57 ]{@racket['sub-range-binders]} property. 58 } 59 60 @defform[(with-arrows body-expr ... stx-expr)]{ 61 Equivalent to: 62 63 @racketblock[(with-disappeared-uses 64 (with-sub-range-binders 65 body-expr ... stx-expr))]} 66 67 @defform[(syntax-parser-with-arrows . syntax-parser-options+clauses)]{ 68 Equivalent to: 69 70 @racketblock[(λ (stx) 71 (with-arrows 72 ((syntax-parser . syntax-parser-options+clauses) stx)))] 73 74 Within the @racket[syntax-parser-options+clauses], it is possible to use the 75 @racket[stx] identifier to refer to the whole syntax, in addition to using 76 @racket[syntax/parse]'s @racket[this-syntax].} 77 78 @defproc[(record-sub-range-binders! [sub-range-binders 79 (or/c sub-range-binder/c 80 (listof sub-range-binder/c))]) 81 void?]{ 82 Cooperates with the enclosing @racket[with-sub-range-binders] or 83 @racket[with-arrows] to record the given sub-range-binders so that they are 84 added to the syntax object returned by @racket[with-sub-range-binders] or 85 @racket[with-arrows]. 86 87 This function must be called within the dynamic extent of 88 @racket[with-sub-range-binders] or @racket[with-arrows].} 89 90 @defproc[(maybe-record-sub-range-binders! [sub-range-binders 91 (or/c sub-range-binder/c 92 (listof sub-range-binder/c))]) 93 void?]{ 94 Cooperates with the enclosing @racket[with-sub-range-binders] or 95 @racket[with-arrows] to record the given sub-range-binders so that they are 96 added to the syntax object returned by @racket[with-sub-range-binders] or 97 @racket[with-arrows]. 98 99 If this function is not called within the dynamic extent of 100 @racket[with-sub-range-binders] or @racket[with-arrows], it has no effect and 101 the sub-range-binders are not recorded.} 102 103 @defparam[current-recorded-sub-range-binders sub-range-binders 104 (or/c (listof sub-range-binder/c) false/c)]{ 105 This parameter contains the list of sub-range-binders recorded so far by the 106 nearest @racket[with-sub-range-binders] or @racket[with-arrows].} 107 108 @defthing[sub-range-binder/c chaperone-contract? 109 #:value 110 (or/c (vector/c syntax? 111 exact-nonnegative-integer? exact-nonnegative-integer? 112 (real-in 0 1) (real-in 0 1) 113 syntax? 114 exact-nonnegative-integer? exact-nonnegative-integer? 115 (real-in 0 1) (real-in 0 1)) 116 (vector/c syntax? 117 exact-nonnegative-integer? exact-nonnegative-integer? 118 syntax? 119 exact-nonnegative-integer? exact-nonnegative-integer?) 120 )]{ 121 A contract accepting valid representations of 122 @seclink["Syntax_Properties_that_Check_Syntax_Looks_For" 123 #:doc '(lib "scribblings/tools/tools.scrbl")]{sub-range binders}. 124 }