From e0a59049e5966b8e3f2c31c4a613905f524453ef Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Tue, 8 Jan 2008 16:09:25 +0000 Subject: [PATCH] scribble reader interface and doc adjustments svn: r8257 original commit: 4c1856f189d8f829be11f4268864d75df146a558 --- collects/scribble/comment-reader.ss | 18 +++--- collects/scribblings/scribble/reader.scrbl | 67 +++++++++------------- 2 files changed, 37 insertions(+), 48 deletions(-) diff --git a/collects/scribble/comment-reader.ss b/collects/scribble/comment-reader.ss index c8a4c94a..30c71370 100644 --- 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 index db9e1af8..d4868625 100644 --- 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 *** ))])]