{"size": 3662, "ext": "scrbl", "max_stars_repo_path": "pkgs/racket-doc/syntax/scribblings/parse/state.scrbl", "max_stars_repo_name": "lkh01/racket", "max_stars_repo_stars_event_min_datetime": "2018-07-29T04:13:52.000Z", "max_stars_repo_stars_event_max_datetime": "2022-02-14T16:11:17.000Z", "max_issues_repo_path": "pkgs/racket-doc/syntax/scribblings/parse/state.scrbl", "max_issues_repo_name": "lkh01/racket", "max_issues_repo_issues_event_min_datetime": "2017-08-25T20:26:37.000Z", "max_issues_repo_issues_event_max_datetime": "2022-02-26T17:48:40.000Z", "max_forks_repo_path": "pkgs/racket-doc/syntax/scribblings/parse/state.scrbl", "max_forks_repo_name": "lkh01/racket", "max_forks_repo_forks_event_min_datetime": "2016-04-25T11:47:57.000Z", "max_forks_repo_forks_event_max_datetime": "2017-05-09T14:52:48.000Z"}
{"max_stars_count": 10, "max_issues_count": 15, "max_forks_count": 3, "avg_line_length": 38.1458333333, "max_line_length": 97, "alphanum_fraction": 0.6714909885}
#lang scribble/doc
@(require scribble/manual
          scribble/struct
          scribble/decode
          scribble/eval
          "../common.rkt"
          "parse-common.rkt")

@(define the-eval (make-sp-eval))

@title[#:tag "state"]{Unwindable State}

@declare-exporting[syntax/parse]

@deftogether[[
@defproc[(syntax-parse-state-ref [key any/c]
                                 [default default/c (lambda () (error ....))])
         any/c]
@defproc[(syntax-parse-state-set! [key any/c] [value any/c]) void?]
@defproc[(syntax-parse-state-update! [key any/c]
                                     [update (-> any/c any/c)]
                                     [default default/c (lambda () (error ....))])
         void?]
@defproc[(syntax-parse-state-cons! [key any/c]
                                   [value any/c]
                                   [default default/c null])
         void?]
]]{

Get or update the current @racket[syntax-parse] state. Updates to the
state are unwound when @racket[syntax-parse] backtracks. Keys are
compared using @racket[eq?].

The state can be updated only within @racket[~do] patterns (or
@racket[#:do] blocks). In addition, @racket[syntax-parse]
automatically adds identifiers that match literals (from
@racket[~literal] patterns and literals declared with
@racket[#:literals], but not from @racket[~datum] or
@racket[#:datum-literals]) under the key @racket['literals].

@examples[#:eval the-eval
(define-syntax-class cond-clause
  #:literals (=> else)
  (pattern [test:expr => ~! answer:expr ...])
  (pattern [else answer:expr ...])
  (pattern [test:expr answer:expr ...]))
(syntax-parse #'(cond [A => B] [else C])
  [(_ c:cond-clause ...) (syntax-parse-state-ref 'literals null)])
]

@history[#:added "6.11.0.4"]
}

@defproc[(syntax-parse-track-literals [stx syntax?] [#:introduce? introduce? any/c #t]) syntax?]{

Add a @racket['disappeared-use] @tech[#:doc refman]{syntax property} to
@racket[stx] containing the information stored in the current
@racket[syntax-parse] state under the key @racket['literals]. If
@racket[stx] already has a @racket['disappeared-use] property, the
added information is @racket[cons]ed onto the property’s current value.

Due to the way @racket[syntax-parse] automatically adds identifiers that match
literals to the state under the key @racket['literals], as described in the
documentation for @racket[syntax-parse-state-ref],
@racket[syntax-parse-track-literals] can be used to automatically add any
identifiers used as literals to the @racket['disappeared-use] property.

If @racket[syntax-parse-track-literals] is called within the dynamic
extent of a @tech[#:doc refman]{syntax transformer} (see
@racket[syntax-transforming?]), @racket[introduce?] is not @racket[#f], and the
value in the current @racket[syntax-parse] state under the key
@racket['literals] is a list, then @racket[syntax-local-introduce] is applied to
any identifiers in the list before they are added to @racket[stx]’s
@racket['disappeared-use] property.

Most of the time, it is unnecessary to call this function directly. Instead, the
@racket[#:track-literals] option should be provided to @racket[syntax-parse],
which will automatically call @racket[syntax-parse-track-literals] on
syntax-valued results.

@examples[#:eval the-eval
(define-syntax-class cond-clause
  #:literals (=> else)
  (pattern [test:expr => ~! answer:expr ...])
  (pattern [else answer:expr ...])
  (pattern [test:expr answer:expr ...]))
(syntax-property
 (syntax-parse #'(cond [A => B] [else C])
   [(_ c:cond-clause ...) (syntax-parse-track-literals #'#f)])
 'disappeared-use)
]

@history[#:added "6.90.0.29"]}

@(close-eval the-eval)
