77 lines
3.9 KiB
Racket
77 lines
3.9 KiB
Racket
#lang scribble/manual
|
|
@require[racket/require
|
|
"utils.rkt"
|
|
@for-label[racket/base
|
|
racket/contract
|
|
phc-toolkit/ids
|
|
phc-toolkit/contract]]
|
|
@title{Generating identifiers}
|
|
@author{@author+email["Georges Dupéron" "georges.duperon@gmail.com"]}
|
|
@defmodule[phc-toolkit/ids
|
|
#:use-sources
|
|
[(submod (lib "phc-toolkit/ids.rkt") typed)]]
|
|
|
|
@defform[(define-temp-ids maybe-concise simple-format base+ellipses
|
|
maybe-first-base maybe-prefix)
|
|
#:grammar
|
|
[(base+ellipses base
|
|
(base+ellipses ooo))
|
|
(maybe-concise (code:line)
|
|
(code:line #:concise))
|
|
(maybe-first-base (code:line)
|
|
(code:line #:first-base first-base))
|
|
(maybe-prefix (code:line)
|
|
(code:line #:prefix prefix))]
|
|
#:contracts
|
|
[(simple-format (syntax/c
|
|
(and/c string?
|
|
(or/c (regexp-match/c #rx"^[^~]*~a[^~]*$")
|
|
(regexp-match/c #rx"^[^~]*$")))))
|
|
(base identifier?)
|
|
(first-base identifier?)
|
|
(prefix (or/c string? identifier?))
|
|
(ooo (id/c ...))]]{
|
|
Defines @racket[_new-name] as a syntax attribute, with the same nested
|
|
structure as @racket[base]. The @racket[_new-name] is obtained by applying the
|
|
@racket[base] to the given @racket[simple-format] string. The generated syntax
|
|
contains identifiers derived using the @racket[base] and
|
|
@racket[simple-format] in the same way. Each of the generated identifiers is
|
|
unique, in the sense that there are not two generated identifiers which are
|
|
@racket[free-identifier=?] to each other.
|
|
|
|
If the @racket[#:first-base] option is specified, then @racket[_new-first] is
|
|
also defined to be the first generated identifier in the whole tree. In other
|
|
words, @racket[_new-first] will be bound to the same identifier as
|
|
@racket[_new-name] if there are no ellipses, to the value of
|
|
@racket[(stx-car _new-name)] if there is one level of ellipses, to the value
|
|
of @racket[(stx-car (stx-car _new-name))] if there are two levels, and so on.
|
|
The identifier @racket[_new-first] is generated by applying
|
|
@racket[first-base] to the @racket[simple-format].
|
|
|
|
If the @racket[#:prefix] option is specified, then the generated identifiers
|
|
are prefixed with @racket[prefix], followed by a colon @racket[":"]. This does
|
|
not impact the @racket[_new-name] and @racket[_new-first] identifiers, so it
|
|
can be useful when succinct identifiers are desired for the syntax attributes
|
|
within the macro which uses @racket[define-temp-ids], but the generated
|
|
identifiers should contain more context, to improve the readability of error
|
|
messages which involve the generated temporary identifiers.
|
|
|
|
If the @racket[#:concise] option is specified, then the generated identifiers
|
|
are more concise, which makes them easier to read when debugging macros, but
|
|
also means that two distinct identifiers can look the same (but have distinct
|
|
scopes). If the @racket[#:concise] option is omitted, the generated identifiers
|
|
may contain extra characters do help visually disambiguate similar identifiers
|
|
(those extra characters are obtained using @racket[generate-temporary]).
|
|
|
|
@history[#:changed "1.1"
|
|
@list{The lexical context for the defined identifier
|
|
@racket[_new-name] is now taken from the format, instead of being
|
|
taken from the base @racket[name]. Previously, the lexical context
|
|
was taken from the base @racket[name], except when the simple format
|
|
did not contain any @racket["~a"], in which case it was taken from
|
|
the whole @racket[base+ellipses] (this was a bug, which is fixed now
|
|
that both cases use the lexical context of @racket[format]). The
|
|
same applies to the lexical context for @racket[_new-first]}]}
|
|
|
|
@include-section{ids-untyped.scrbl}
|