commit 526994ad26b7dd0ac529ca4dd25930a65827c9b7
parent 6f39353a52bcf3af80d6f13100451dab73e08251
Author: Eli Barzilay <eli@racket-lang.org>
Date: Fri, 13 Jul 2007 19:03:22 +0000
added datum-reader customizing, documented interface
svn: r6908
original commit: 75c571ba6dbb55c7204faac9bb19d9cbf36d30ba
Diffstat:
2 files changed, 95 insertions(+), 14 deletions(-)
diff --git a/collects/scribble/doc.txt b/collects/scribble/doc.txt
@@ -28,11 +28,6 @@ function to switch the current readtable to a readtable that parses
mzscheme -Le reader.ss scribble "(use-at-readtable)"
-In addition to `read' and `read-syntax', which are used by `#reader',
-the "reader.ss" library provides the procedures `read-inside' and
-`read-inside-syntax'; these `-inner' variants parse as if starting
-inside a "@{...}", and they return a (syntactic) list.
-
*** Concrete Syntax
Informally, the concrete syntax of @-forms is
@@ -570,7 +565,7 @@ matter, you can begin (or end) a line with a "@||".
@|| bar @|| --reads-as--> (foo " bar " "\n" " baz")
@|| baz}
-* Syntax Properties
+*** Syntax Properties
The Scribble reader attaches properties to syntax objects. These
properties might be useful in rare situations.
@@ -634,3 +629,41 @@ Here is an example of this.
bar
}
--> "foo\n bar"
+
+*** Interface
+
+The "reader.ss" module provides very little functionality for advanced
+needs.
+
+> (read [input-port])
+> (read-syntax [source-name] [input-port])
+
+These procedures implement the Scribble reader. They do so by
+constructing a reader table based on the current one, and using that
+in reading.
+
+> (read-inside [input-port])
+> (read-inside-syntax [source-name] [input-port])
+
+These `-inner' 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])
+
+Constructs an @-readtable, based on the input argument if given, or
+`current-readtable' otherwise.
+
+> (use-at-readtable)
+
+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.)
diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl
@@ -37,12 +37,7 @@ function to switch the current readtable to a readtable that parses
@commandline{mzscheme -Le reader.ss scribble "(use-at-readtable)"}
-In addition to @scheme[read] and @scheme[read-syntax], which are used
-by @schemefont{#reader}, the @file{reader.ss} library provides the
-procedures @scheme[read-inside] and @scheme[read-inside-syntax]; these
-@schemeid[-inner] variants parse as if starting inside a
-@litchar["@{"]...@litchar["}"], and they return a (syntactic) list.
-
+@;--------------------------------------------------------------------
@section{Concrete Syntax}
Informally, the concrete syntax of @"@"-forms is
@@ -140,7 +135,7 @@ use Scheme's @scheme[quote].
'@foo{bar}
}===|
-@; - - - - - - - - - - - - - - - - - - - - - - - -
+@;--------------------------------------------------------------------
@subsection{The Command Part}
Besides being a Scheme identifier, the @nonterm{cmd} part of an
@@ -229,6 +224,7 @@ Finally, note that there are currently no special rules for using
@@foo{bar}{baz}
}===|
+@;--------------------------------------------------------------------
@subsection{The Datum Part}
The datum part can contains arbitrary Scheme expressions, which
@@ -265,6 +261,7 @@ keyword-value arguments that precede the body of text arguments.
@foo[#:style 'big]{bar}
}===|
+@;--------------------------------------------------------------------
@subsection{The Body Part}
The syntax of the body part is intended to be as convenient as
@@ -330,6 +327,7 @@ of the text. This works for @litchar["@"] too:
@foo{@"@x{y}" --> (x "y")}
}===|
+@;--------------------------------------------------------------------
@subsubsub*section{Alternative Body Syntax}
In addition to the above, there is an alternative syntax for the body,
@@ -375,6 +373,7 @@ string for confusing situations. This works well when you only need
to quote short pieces, and the above works well when you have larger
multi-line body texts.
+@;--------------------------------------------------------------------
@subsubsub*section{Scheme Expression Escapes}
In some cases, you may want to use a Scheme identifier (or a number or
@@ -431,6 +430,7 @@ is little point in Scheme code that uses braces.
@|{blah}|
}===|
+@;--------------------------------------------------------------------
@subsubsub*section{Comments}
As noted above, there are two kinds of Scribble comments: @litchar["@;{...}"] is
@@ -456,6 +456,7 @@ you can get further control of the subforms.
Note how this is different from using @litchar["@||"]s in that strings
around it are not merged.
+@;--------------------------------------------------------------------
@subsubsub*section{Spaces, Newlines, and Indentation}
The Scribble syntax treats spaces and newlines in a special way is
@@ -631,7 +632,8 @@ matter, you can begin (or end) a line with a "@||".
@|| baz}
}===|
-@subsubsub*section{Syntax Properties}
+@;--------------------------------------------------------------------
+@section{Syntax Properties}
The Scribble reader attaches properties to syntax objects. These
properties might be useful in rare situations.
@@ -715,3 +717,49 @@ an example of this.
bar
})
]
+
+@;--------------------------------------------------------------------
+@section{Interface}
+
+The @file{reader.ss} module provides very little functionality for
+advanced needs.
+
+@defproc[(read [in input-port? (current-input-port)]) any]{}
+@defproc[(read-syntax [source-name any/c (object-name in)]
+ [in input-port? (current-input-port)])
+ (or/c syntax? eof-object?)]{
+These procedures implement the Scribble reader. They do so by
+constructing a reader table based on the current one, and using that
+in reading.
+}
+
+@defproc[(read-inside [in input-port? (current-input-port)]) any]{}
+@defproc[(read-inside-syntax [source-name any/c (object-name in)]
+ [in input-port? (current-input-port)])
+ (or/c syntax? eof-object?)]{
+These @schemeid[-inner] variants parse as if starting inside a
+@litchar["@{"]...@litchar["}"], and they return a (syntactic) list.
+Useful for implementing languages that are textual by default (see
+@file{docreader.ss} for example).
+}
+
+@defproc[(make-at-readtable
+ [readtable (or/c readtable? false/c) (current-readtable)])
+ readtable?]{
+Constructs an @"@"-readtable, based on the input argument.
+}
+
+@defproc[(use-at-readtable) void?]{
+Installs the Scribble readtable as the default. Useful for REPL
+experimentation. (Note: enables line and column tracking.)
+}
+
+@defparam[datum-readtable readtable
+ (or/c #t false/c readtable? (readtable? . -> . readtable?))]{
+A parameter that determines the readtable used for reading the datum
+part. The default (@scheme[#t]) is to use the current readtable
+(usually a result of @scheme[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.)
+}
