suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve readable-snip<%> and related docs

Browse Source 
svn: r15784
This commit is contained in:
Matthew Flatt 2009-08-19 20:51:23 +00:00
parent 543f586a97
commit 8da19de7b2
2 changed files with 33 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
collects/scribblings/gui/readable-snip-intf.scrbl
View File

@ -4,10 +4,18 @@
@definterface/title[readable-snip<%> ()]{ @definterface/title[readable-snip<%> ()]{
A @scheme[readable-snip<%>] object is treated specially by the port A @scheme[readable-snip<%>] object is treated specially by the port
generated by @scheme[open-input-text-editor]. When a generated by @scheme[open-input-text-editor]: When a
@scheme[readable-snip<%>] object is encountered for the input stream, @scheme[readable-snip<%>] object is encountered for the input stream,
its @method[readable-snip<%> read-special] method is called to its @method[readable-snip<%> read-special] method is called to
generate the read result for the snip. generate the read result for the snip, which is returned from the
port as a ``special'' value in the sense of
@scheme[read-char-or-special].
Since @scheme[read] and @scheme[read-syntax] build on
@scheme[read-char-or-special], a snip can implement
@scheme[readable-snip<%>] so that it produces a whole S-expression or
some other kind of value when @scheme[read] is used on a stream
containing the snip.
@defmethod[(read-special [source any/c] @defmethod[(read-special [source any/c]
[line (or/c exact-nonnegative-integer? false/c)] [line (or/c exact-nonnegative-integer? false/c)]
@ -16,10 +24,10 @@ A @scheme[readable-snip<%>] object is treated specially by the port
any/c]{ any/c]{
The arguments are the same as the arguments to a procedure returned by The arguments are the same as the arguments to a procedure returned by
a custom input port's @scheme[read]; see @secref[#:doc '(lib a custom input port's @scheme[_read-in]; see @secref[#:doc '(lib
"scribblings/reference/reference.scrbl") "customport"] for "scribblings/reference/reference.scrbl") "customport"] for
details. The result is also the same as the result from a details. The result is also the same as the result from a
@scheme[read]-produced procedure. @scheme[_read-in]-produced procedure.
}} }}

40
collects/scribblings/reference/custom-ports.scrbl
View File

@ -62,9 +62,9 @@ The arguments implement the port as follows:
@item{@scheme[eof];} @item{@scheme[eof];}
@item{a procedure of arity four (representing a ``special'' @item{a procedure of arity four (representing a ``special''
result, as discussed further below) and optionally of arity zero, result, as discussed @elemref["special"]{further below}) and
but a procedure result is allowed only when optionally of arity zero, but a procedure result is allowed only
@scheme[peek] is not @scheme[#f];} when @scheme[peek] is not @scheme[#f];}
@item{a @techlink{pipe} input port that supplies bytes to be @item{a @techlink{pipe} input port that supplies bytes to be
used as long as the pipe has content (see used as long as the pipe has content (see
@ -91,9 +91,9 @@ The arguments implement the port as follows:
If the result of a @scheme[read-in] call is not one of the above If the result of a @scheme[read-in] call is not one of the above
values, the @exnraise[exn:fail:contract]. If a returned integer is values, the @exnraise[exn:fail:contract]. If a returned integer is
larger than the supplied byte string's length, the larger than the supplied byte string's length, the
@exnraise[exn:fail:contract]. If @scheme[peek] is @exnraise[exn:fail:contract]. If @scheme[peek] is @scheme[#f] and
@scheme[#f] and a procedure for a special result is returned, the a procedure for a @elemref["special"]{special} result is returned,
@exnraise[exn:fail:contract]. the @exnraise[exn:fail:contract].
The @scheme[read-in] procedure can report an error by raising an The @scheme[read-in] procedure can report an error by raising an
exception, but only if no bytes are read. Similarly, no bytes exception, but only if no bytes are read. Similarly, no bytes
@ -156,8 +156,8 @@ The arguments implement the port as follows:
@item{a mutable byte string to receive peeked bytes;} @item{a mutable byte string to receive peeked bytes;}
@item{a non-negative number of bytes (or specials) to skip before @item{a non-negative number of bytes (or
peeking; and} @elemref["special"]{specials}) to skip before peeking; and}
@item{either @scheme[#f] or a progress event produced by @item{either @scheme[#f] or a progress event produced by
@scheme[get-progress-evt].} @scheme[get-progress-evt].}
@ -180,9 +180,9 @@ The arguments implement the port as follows:
the progress event is ready. Also like @scheme[read-in], the progress event is ready. Also like @scheme[read-in],
@scheme[peek] must not block indefinitely. @scheme[peek] must not block indefinitely.
The skip count provided to @scheme[peek] is a number of The skip count provided to @scheme[peek] is a number of bytes (or
bytes (or specials) that must remain present in the port---in @elemref["special"]{specials}) that must remain present in the
addition to the peek results---when the peek results are port---in addition to the peek results---when the peek results are
reported. If a progress event is supplied, then the peek is reported. If a progress event is supplied, then the peek is
effectively canceled when another process reads data before the effectively canceled when another process reads data before the
given number can be skipped. If a progress event is not supplied given number can be skipped. If a progress event is not supplied
@ -196,8 +196,9 @@ The arguments implement the port as follows:
implemented automatically in terms of reads, but with several implemented automatically in terms of reads, but with several
limitations. First, the automatic implementation is not limitations. First, the automatic implementation is not
thread-safe. Second, the automatic implementation cannot handle thread-safe. Second, the automatic implementation cannot handle
special results (non-byte and non-eof), so @scheme[read-in] cannot @elemref["special"]{special} results (non-byte and non-eof), so
return a procedure for a special when @scheme[peek] is @scheme[read-in] cannot return a procedure for a
@elemref["special"]{special} when @scheme[peek] is
@scheme[#f]. Finally, the automatic peek implementation is @scheme[#f]. Finally, the automatic peek implementation is
incompatible with progress events, so if @scheme[peek] is incompatible with progress events, so if @scheme[peek] is
@scheme[#f], then @scheme[progress-evt] and @scheme[commit] must @scheme[#f], then @scheme[progress-evt] and @scheme[commit] must
@ -249,10 +250,10 @@ The arguments implement the port as follows:
that was previously peeked, but only if no other process removed that was previously peeked, but only if no other process removed
data first. (The removed data does not need to be reported, data first. (The removed data does not need to be reported,
because it has been peeked already.) More precisely, assuming because it has been peeked already.) More precisely, assuming
that @math{k_p} bytes, specials, and mid-stream @scheme[eof]s have that @math{k_p} bytes, @elemref["special"]{specials}, and
been previously peeked or skipped at the start of the port's mid-stream @scheme[eof]s have been previously peeked or skipped
stream, @scheme[commit] must satisfy the following at the start of the port's stream, @scheme[commit] must satisfy
constraints: the following constraints:
@itemize[ @itemize[
@ -333,8 +334,9 @@ The arguments implement the port as follows:
] ]
When @scheme[read-in] or @scheme[peek] (or an event produced by one @elemtag["special"]{@bold{``Special'' results:}} When
of these) returns a procedure, and the procedure is used to obtain a @scheme[read-in] or @scheme[peek] (or an event produced by one of
these) returns a procedure, and the procedure is used to obtain a
non-byte result. (This non-byte result is @italic{not} intended to non-byte result. (This non-byte result is @italic{not} intended to
return a character or @scheme[eof]; in particular, @scheme[read-char] return a character or @scheme[eof]; in particular, @scheme[read-char]
raises an exception if it encounters a special-result procedure, even raises an exception if it encounters a special-result procedure, even