commit e0a59049e5966b8e3f2c31c4a613905f524453ef
parent ee106049e282d2c632f312a7a399156385af23c7
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 8 Jan 2008 16:09:25 +0000
scribble reader interface and doc adjustments
svn: r8257
original commit: 4c1856f189d8f829be11f4268864d75df146a558
Diffstat:
2 files changed, 37 insertions(+), 48 deletions(-)
diff --git a/collects/scribble/comment-reader.ss b/collects/scribble/comment-reader.ss
@@ -1,20 +1,20 @@
-(module comment-reader mzscheme
- (require (lib "kw.ss"))
+(module comment-reader scheme/base
- (provide (rename *read read)
- (rename *read-syntax read-syntax))
+ (provide (rename-out [*read read]
+ [*read-syntax read-syntax])
+ make-comment-readtable)
- (define/kw (*read #:optional [inp (current-input-port)])
+ (define (*read [inp (current-input-port)])
(parameterize ([current-readtable (make-comment-readtable)])
(read/recursive inp)))
- (define/kw (*read-syntax #:optional src [port (current-input-port)])
+ (define (*read-syntax src [port (current-input-port)])
(parameterize ([current-readtable (make-comment-readtable)])
(read-syntax/recursive src port)))
- (define (make-comment-readtable)
- (make-readtable (current-readtable)
+ (define (make-comment-readtable #:readtable [rt (current-readtable)])
+ (make-readtable rt
#\; 'terminating-macro
(case-lambda
[(char port)
@@ -22,7 +22,7 @@
[(char port src line col pos)
(let ([v (do-comment port (lambda () (read-syntax/recursive src port #\@)))])
(let-values ([(eline ecol epos) (port-next-location port)])
- (datum->syntax-object
+ (datum->syntax
#f
v
(list src line col pos (and pos epos (- epos pos))))))])))
diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl
@@ -757,23 +757,35 @@ Useful for implementing languages that are textual by default (see
@filepath{docreader.ss} for example).
}
-@defform[(make-at-readtable [keyword-args ...])]{
+@defproc[(make-at-readtable [#:readtable readtable readtable? (current-readtable)]
+ [#:command-char command-char character? #\@]
+ [#:start-inside? start-inside? any/c #f]
+ [#:datum-readtable datum-readtable
+ (or/c readtable? boolean?
+ (readtable? . -> . readtable?))
+ #t]
+ [#:syntax-post-processor syntax-post-proc (syntax? . -> . syntax?) values])
+ readtable?]{
+
Constructs an @"@"-readtable. The keyword arguments can customize the
-resulting reader in several ways.
+resulting reader in several ways:
@itemize{
-@item{@scheme[#:readtable] --- a readtable to base the @"@"-readtable
- on. Defaults to the current readtable.}
-@item{@scheme[#:command-char] --- the character used for @"@"-forms;
- defaults to @scheme[#\@].}
-@item{@scheme[#:datum-readtable] --- determines the readtable used for
- reading the datum part. The default (@scheme[#t]) is to use the
+
+@item{@scheme[readtable] --- a readtable to base the @"@"-readtable
+ on.}
+
+@item{@scheme[command-char] --- the character used for @"@"-forms.}
+
+@item{@scheme[datum-readtable] --- determines the readtable used for
+ reading the datum part. A @scheme[#t] values uses 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 a
convenient @litchar["key=val"] syntax for attributes.}
-@item{@scheme[#:syntax-post-processor] --- function that is applied on
+
+@item{@scheme[syntax-post-proc] --- 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
@@ -786,41 +798,18 @@ resulting reader in several ways.
(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 @schemeid[mk-] prefix for all command names:
+@item{@scheme[start-inside?] --- if true, creates a readtable for
+use starting in text mode, instead of S-expression mode.}
- @schemeblock[
- (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 ...)))]))
- ]
-}
-@item{@scheme[#:start-inside?] --- used internally by the above
- @schemeid[-inside] variants.}
}}
@defproc[(use-at-readtable ...) void?]{
-Installs the Scribble readtable as the default. Useful for REPL
-experimentation. (Note: enables line and column tracking.) The given
-keyword arguments are used with `make-at-readtable'.
-}
+
+Passes all arguments to @scheme[make-at-readtable], and installs the
+resulting readtable using @scheme[current-readtable]. It also enables
+line counting for the current input-port via @scheme[port-count-lines!].}
@; *** End reader-import section ***
))])]
