ids.scrbl (4009B)
1 #lang scribble/manual 2 @require[racket/require 3 "utils.rkt" 4 @for-label[racket/base 5 racket/contract 6 phc-toolkit/ids 7 phc-toolkit/contract]] 8 @title{Generating identifiers} 9 @author{@author+email["Suzanne Soy" "racket@suzanne.soy"]} 10 @defmodule[phc-toolkit/ids 11 #:use-sources 12 [(submod (lib "phc-toolkit/ids.rkt") typed)]] 13 14 @defform[(define-temp-ids maybe-concise simple-format base+ellipses 15 maybe-first-base maybe-prefix) 16 #:grammar 17 [(base+ellipses base 18 (base+ellipses ooo)) 19 (maybe-concise (code:line) 20 (code:line #:concise)) 21 (maybe-first-base (code:line) 22 (code:line #:first-base first-base)) 23 (maybe-prefix (code:line) 24 (code:line #:prefix prefix))] 25 #:contracts 26 [(simple-format (syntax/c 27 (and/c string? 28 (or/c (regexp-match/c #rx"^[^~]*~a[^~]*$") 29 (regexp-match/c #rx"^[^~]*$"))))) 30 (base identifier?) 31 (first-base identifier?) 32 (prefix (or/c string? identifier?)) 33 (ooo (id/c ...))]]{ 34 Defines @racket[_new-name] as a syntax attribute, with the same nested 35 structure as @racket[base]. The @racket[_new-name] is obtained by applying the 36 @racket[base] to the given @racket[simple-format] string. The generated syntax 37 contains identifiers derived using the @racket[base] and 38 @racket[simple-format] in the same way. Each of the generated identifiers is 39 unique, in the sense that there are not two generated identifiers which are 40 @racket[free-identifier=?] to each other. 41 42 If the @racket[#:first-base] option is specified, then @racket[_new-first] is 43 also defined to be the first generated identifier in the whole tree. In other 44 words, @racket[_new-first] will be bound to the same identifier as 45 @racket[_new-name] if there are no ellipses, to the value of 46 @racket[(stx-car _new-name)] if there is one level of ellipses, to the value 47 of @racket[(stx-car (stx-car _new-name))] if there are two levels, and so on. 48 The identifier @racket[_new-first] is generated by applying 49 @racket[first-base] to the @racket[simple-format]. 50 51 If the @racket[#:prefix] option is specified, then the generated identifiers 52 are prefixed with @racket[prefix], followed by a colon @racket[":"]. This does 53 not impact the @racket[_new-name] and @racket[_new-first] identifiers, so it 54 can be useful when succinct identifiers are desired for the syntax attributes 55 within the macro which uses @racket[define-temp-ids], but the generated 56 identifiers should contain more context, to improve the readability of error 57 messages which involve the generated temporary identifiers. 58 59 If the @racket[#:concise] option is specified, then the generated identifiers 60 are more concise, which makes them easier to read when debugging macros, but 61 also means that two distinct identifiers can look the same (but have distinct 62 scopes). If the @racket[#:concise] option is omitted, the generated identifiers 63 may contain extra characters do help visually disambiguate similar identifiers 64 (those extra characters are obtained using @racket[generate-temporary]). 65 66 @history[#:changed "1.1" 67 @list{The lexical context for the defined identifier 68 @racket[_new-name] is now taken from the format, instead of being 69 taken from the base @racket[name]. Previously, the lexical context 70 was taken from the base @racket[name], except when the simple format 71 did not contain any @racket["~a"], in which case it was taken from 72 the whole @racket[base+ellipses] (this was a bug, which is fixed now 73 that both cases use the lexical context of @racket[format]). The 74 same applies to the lexical context for @racket[_new-first]}]} 75 76 @include-section{ids-untyped.scrbl}