more readtable customization

svn: r6924

original commit: 67941597640f6cd2805b92b5895d89896ca9d8f7

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, based on the input argument if given, or
+Constructs an @-readtable.  The keyword arguments can customize the
-`current-readtable' otherwise.
+resulting reader in several ways.
 
-> (use-at-readtable)
+* #: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 ...)))]))
+
+* #:start-inside? -- used internally by the above `-inside' variants.
+
+> (use-at-readtable [keyword-args])
 
 Installs the Scribble readtable as the default.  Useful for REPL
-experimentation.  (Note: enables line and column tracking.)
+experimentation.  (Note: enables line and column tracking.)  The given
-
+keyword arguments are used with `make-at-readtable'.
-> 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.)