From 4c1856f189d8f829be11f4268864d75df146a558 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 --- collects/scribble/comment-reader.ss | 18 +++--- collects/scribble/reader.ss | 59 ++++++++++--------- collects/scribblings/quick/quick.scrbl | 1 - collects/scribblings/scribble/reader.scrbl | 67 +++++++++------------- 4 files changed, 68 insertions(+), 77 deletions(-) diff --git a/collects/scribble/comment-reader.ss b/collects/scribble/comment-reader.ss index c8a4c94a43..30c71370ff 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/scribble/reader.ss b/collects/scribble/reader.ss index fa5dbd8284..fb779fd30f 100644 --- a/collects/scribble/reader.ss +++ b/collects/scribble/reader.ss @@ -1,9 +1,9 @@ ;; ============================================================================ ;; Implements the @-reader macro for embedding text in Scheme code. -(module reader mzscheme +(module reader scheme/base - (require (lib "kw.ss") (lib "string.ss") (lib "readerr.ss" "syntax")) + (require (lib "string.ss") (lib "readerr.ss" "syntax")) ;; -------------------------------------------------------------------------- ;; utilities for syntax specifications below @@ -158,7 +158,7 @@ (define eol-token "\n") (define (eol-syntax? x) (and (syntax? x) (eq? eol-token (syntax-e x)))) ;; sanity check, in case this property gets violated in the future - (unless (eol-syntax? (datum->syntax-object #f eol-token)) + (unless (eol-syntax? (datum->syntax #f eol-token)) (internal-error 'invalid-assumption)) ;; -------------------------------------------------------------------------- @@ -251,7 +251,7 @@ (unless (eol-syntax? eol) (internal-error 'done-items)) (cons (syntax-property - (datum->syntax-object eol spaces eol) + (datum->syntax eol spaces eol) 'scribble 'indentation) r)))] ;; can have special comment values from "@||" @@ -266,7 +266,7 @@ [1st (and (syntax? stx0) (syntax-e stx0))]) (if (and (string? 1st) (not (eq? eol-token 1st)) (string? 2nd) (not (eq? eol-token 2nd))) - (cons (datum->syntax-object stx0 + (cons (datum->syntax stx0 (string-append 1st 2nd) (list (syntax-source stx0) (syntax-line stx0) @@ -297,7 +297,7 @@ ;; `done-items' to finish the job (define-values (line col pos) (port-next-location inp)) (define (make-stx sexpr) - (datum->syntax-object #f + (datum->syntax #f (if (bytes? sexpr) (bytes->string/utf-8 sexpr) sexpr) (list source-name line col pos (span-from pos)))) (cond @@ -415,7 +415,7 @@ [#",@" unquote-splicing])) => cadr] [else (internal-error 'get-rprefixes)])]) - (loop (cons (datum->syntax-object #f sym + (loop (cons (datum->syntax #f sym (list source-name line col pos (span-from pos))) r))))] @@ -425,7 +425,7 @@ (cond [start-inside? - (datum->syntax-object #f (get-lines* #f #f #f re:line-item-no-nests #f) + (datum->syntax #f (get-lines* #f #f #f re:line-item-no-nests #f) (list source-name line-num col-num position (span-from position)))] [(*skip re:whitespaces) (read-error* "unexpected whitespace after ~a" ch:command)] @@ -458,7 +458,7 @@ (syntax-property (if (syntax? stx) stx - (datum->syntax-object #f stx + (datum->syntax #f stx (list source-name line-num col-num position (span-from position)))) 'scribble (list 'form ds ls)) @@ -470,7 +470,7 @@ (if (null? rpfxs) stx (loop (cdr rpfxs) (list (car rpfxs) stx))))]) - (datum->syntax-object #f stx + (datum->syntax #f stx (list source-name line-num col-num position (span-from position))))])) @@ -496,12 +496,12 @@ ;; readtable (provide make-at-readtable) - (define/kw (make-at-readtable - #:key [readtable (current-readtable)] - [command-char ch:command] - [start-inside? #f] - [datum-readtable #t] - [syntax-post-processor values]) + (define (make-at-readtable + #:readtable [readtable (current-readtable)] + #:command-char [command-char ch:command] + #:start-inside? [start-inside? #f] + #:datum-readtable [datum-readtable #t] + #:syntax-post-processor [syntax-post-processor values]) (define dispatcher (make-dispatcher start-inside? command-char (lambda () cmd-rt) (lambda () datum-rt) @@ -521,7 +521,7 @@ (unless m (raise-read-error "unbalanced `|'" source-name line-num col-num position #f)) - (datum->syntax-object + (datum->syntax #f (string->symbol (bytes->string/utf-8 (cadr m))) (list source-name line-num col-num position (add1 (bytes-length (car m))))))))) @@ -535,9 +535,11 @@ at-rt) (provide use-at-readtable) - (define (use-at-readtable . args) - (port-count-lines! (current-input-port)) - (current-readtable (apply make-at-readtable args))) + (define use-at-readtable + (make-keyword-procedure + (lambda (kws kw-args . rest) + (port-count-lines! (current-input-port)) + (keyword-apply current-readtable kws kw-args rest)))) ;; utilities for below (define make-default-at-readtable @@ -565,28 +567,29 @@ (parameterize ([current-readtable (make-default-at-readtable)]) body ...)])) - (define/kw (*read #:optional [inp (current-input-port)]) + (define (*read [inp (current-input-port)]) (with-at-reader (read inp))) - (define/kw (*read-syntax #:optional [src default-src] - [inp (current-input-port)]) + (define (*read-syntax [src default-src] + [inp (current-input-port)]) (with-at-reader (read-syntax (src-name src inp) inp))) - (define/kw (read-inside #:optional [inp (current-input-port)]) + (define (read-inside [inp (current-input-port)]) (let*-values ([(line col pos) (port-next-location inp)] [(inside-dispatcher) (make-default-at-dispatcher/inside)]) (with-at-reader - (syntax-object->datum + (syntax->datum (inside-dispatcher #f inp (object-name inp) line col pos))))) - (define/kw (read-inside-syntax #:optional [src default-src] - [inp (current-input-port)]) + (define (read-inside-syntax [src default-src] + [inp (current-input-port)]) (let*-values ([(line col pos) (port-next-location inp)] [(inside-dispatcher) (make-default-at-dispatcher/inside)]) (with-at-reader (inside-dispatcher #f inp (src-name src inp) line col pos)))) - (provide (rename *read read) (rename *read-syntax read-syntax) + (provide (rename-out [*read read] + [*read-syntax read-syntax]) read-inside read-inside-syntax) ) diff --git a/collects/scribblings/quick/quick.scrbl b/collects/scribblings/quick/quick.scrbl index 580d889334..9b00f87537 100644 --- a/collects/scribblings/quick/quick.scrbl +++ b/collects/scribblings/quick/quick.scrbl @@ -30,7 +30,6 @@ (lambda () (make-element #f (list)))))) @; ---------------------------------------------------------------------- -@section{Why Pictures? Why DrScheme?} This tutorial provides a brief introduction to the PLT Scheme programming language by using one of its picture-drawing diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl index db9e1af894..d48686252e 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 *** ))])]