#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}