commit b1e8c2cace9741c4fbd617872e07add971a16567
parent fb3077b79f9fa4d08eb9439962c49b6a423eb555
Author: Eli Barzilay <eli@racket-lang.org>
Date: Mon, 16 Jul 2007 16:55:12 +0000
more readtable customization
svn: r6924
original commit: 67941597640f6cd2805b92b5895d89896ca9d8f7
Diffstat:
1 file changed, 56 insertions(+), 15 deletions(-)
diff --git a/collects/scribble/doc.txt b/collects/scribble/doc.txt
@@ -645,25 +645,66 @@ in reading.
> (read-inside [input-port])
> (read-inside-syntax [source-name] [input-port])
-These `-inner' variants parse as if starting inside a "@{...}", and
+These `-inside' variants parse as if starting inside a "@{...}", and
they return a (syntactic) list. Useful for implementing languages
that are textual by default (see "docreader.ss" for example).
-> (make-at-readtable [readtable])
+> (make-at-readtable [keyword-args...])
+
+Constructs an @-readtable. The keyword arguments can customize the
+resulting reader in several ways.
+
+* #:readtable -- a readtable to base the @-readtable on. Defaults to
+ the current readtable.
+
+* #:command-char -- the character used for @-forms; defaults to `#\@'.
+
+* #:datum-readtable -- determines the readtable used for reading the
+ datum part. The default (#t) is to use the @-readtable, otherwise
+ it can be a readtable, or a readtable-to-readtable function that
+ will construct one from the @-readtable. The idea is that you may
+ want to have completely different uses for the datum part, for
+ example, introducing an easy syntax for `key=val' attributes.
+
+* #:syntax-post-processor -- a function that is applied on each
+ resulting syntax value after it has been parsed (but before it is
+ wrapped quoting punctuations). You can use this to further control
+ uses of @-forms, for example, making the command be the head of a
+ list:
+
+ (use-at-readtable
+ #:syntax-post-processor
+ (lambda (stx)
+ (syntax-case stx ()
+ [(cmd rest ...) #'(list 'cmd rest ...)]
+ [_else (error "@ forms must have a body")])))
+
+ Beware that the syntax may contain placeholder values at this stage
+ (e.g: the command part), so you can `plant' your own form that will
+ do some plain processing later. For example, here's a setup that
+ uses a `mk-' prefix for all command names:
+
+ (use-at-readtable
+ #:syntax-post-processor
+ (lambda (stx)
+ (syntax-case stx ()
+ [(cmd rest ...) #'(add-mk cmd rest ...)]
+ [_else (error "@ forms must have a body")])))
+ (define-syntax (add-mk stx)
+ (syntax-case stx ()
+ [(_ cmd rest ...)
+ (identifier? #'cmd)
+ (with-syntax ([mk-cmd (datum->syntax-object
+ #'cmd
+ (string->symbol
+ (format "mk-~a" (syntax-e #'cmd)))
+ #'cmd)])
+ (syntax/loc stx (mk-cmd rest ...)))]))
-Constructs an @-readtable, based on the input argument if given, or
-`current-readtable' otherwise.
+* #:start-inside? -- used internally by the above `-inside' variants.
-> (use-at-readtable)
+> (use-at-readtable [keyword-args])
Installs the Scribble readtable as the default. Useful for REPL
-experimentation. (Note: enables line and column tracking.)
-
-> datum-readtable
-
-A parameter that determines the readtable used for reading the datum
-part. The default (#t) is to use the current readtable (usually a
-result of `make-at-readtable'), otherwise it can be a readtable, or a
-readtable-to-readtable function that will construct one. (The idea is
-that you may want to have completely different uses for the datum
-part.)
+experimentation. (Note: enables line and column tracking.) The given
+keyword arguments are used with `make-at-readtable'.
