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

doc work, especially ports in reference

Browse Source 
svn: r6795
This commit is contained in:
Matthew Flatt 2007-07-02 08:07:55 +00:00
parent cf4785e59b
commit 174eb84534
16 changed files with 1348 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
collects/scribble/comment-reader.ss Normal file
View File

@ -0,0 +1,48 @@
(module comment-reader mzscheme
(require (lib "kw.ss"))
(provide (rename *read read)
(rename *read-syntax read-syntax))
(define/kw (*read #:optional [inp (current-input-port)])
(parameterize ([current-readtable (make-comment-readtable)])
(read/recursive inp)))
(define/kw (*read-syntax #:optional src [port (current-input-port)])
(parameterize ([current-readtable (make-comment-readtable)])
(read-syntax/recursive src port)))
(define (make-comment-readtable)
(make-readtable (current-readtable)
#\; 'terminating-macro
(case-lambda
[(char port)
(do-comment port (lambda () (read/recursive port #\@)))]
[(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
#f
v
(list src line col pos (and pos epos (- epos pos))))))])))
(define (do-comment port recur)
(let loop ()
(when (equal? #\; (peek-char port))
(read-char port)
(loop)))
`(code:comment
(unsyntax
(t
,@(let loop ()
(let ([c (read-char port)])
(cond
[(or (eof-object? c)
(char=? c #\newline))
null]
[(char=? c #\@)
(cons (recur) (loop))]
[else (cons (string c)
(loop))]))))))))

5
collects/scribble/eval.ss
View File

@ -115,6 +115,8 @@
(syntax-case s (code:comment eval:alts)
[(code:line v (code:comment . rest))
(do-eval #'v)]
[(code:comment . rest)
(list (list (void)) "" "")]
[(eval:alts p e)
(do-eval #'e)]
[else
@ -214,13 +216,14 @@
(eval `(define eval-example-string ,eval-example-string)))
(define-syntax schemeinput*
(syntax-rules (eval-example-string eval:alts)
(syntax-rules (eval-example-string eval:alts code:comment)
[(_ (eval-example-string s))
(make-paragraph
(list
(hspace 2)
(tt "> ")
(span-class "schemevalue" (schemefont s))))]
[(_ (code:comment . rest)) (schemeblock (code:comment . rest))]
[(_ (eval:alts a b)) (schemeinput* a)]
[(_ e) (schemeinput e)]))

13
collects/scribble/manual.ss
View File

@ -241,10 +241,12 @@
(lambda () (list desc ...)))]))
(define-syntax defstruct
(syntax-rules ()
[(_ name fields #:immutable #:inspector #f desc ...)
(*defstruct (quote-syntax name) 'name 'fields #t #t (lambda () (list desc ...)))]
[(_ name fields #:immutable desc ...)
(*defstruct (quote-syntax name) 'name 'fields #t (lambda () (list desc ...)))]
(*defstruct (quote-syntax name) 'name 'fields #t #f (lambda () (list desc ...)))]
[(_ name fields desc ...)
(*defstruct (quote-syntax name) 'name 'fields #f (lambda () (list desc ...)))]))
(*defstruct (quote-syntax name) 'name 'fields #f #f (lambda () (list desc ...)))]))
(define-syntax (defform*/subs stx)
(syntax-case stx ()
[(_ #:literals (lit ...) [spec spec1 ...] ([non-term-id non-term-form ...] ...) desc ...)
@ -638,7 +640,7 @@
(map symbol->string (car wrappers)))))))
(cdr wrappers))))
(define (*defstruct stx-id name fields immutable? content-thunk)
(define (*defstruct stx-id name fields immutable? transparent? content-thunk)
(define spacer (hspace 1))
(make-splice
(cons
@ -670,7 +672,8 @@
(list 'set- name '- (car f) '!))
fields))))))
,(map car fields)
,@(if immutable? '(#:immutable) null))))))))
,@(if immutable? '(#:immutable) null)
,@(if transparent? '(#:inspector #f) null))))))))
(map (lambda (v)
(cond
[(pair? v)
@ -904,7 +907,7 @@
(cond
[(string? i)
(cond
[(regexp-match #rx"^(.*)([()])(.*)$" i)
[(regexp-match #rx"^(.*)([()0-9])(.*)$" i)
=> (lambda (m)
(append (loop (cadr m))
(list (caddr m))

14
collects/scribble/scheme.ss
View File

@ -183,6 +183,10 @@
(- (cdar m) (caar m))
(literalize-spaces (substring i (cdar m))))
i)))
(define (no-fancy-chars s)
(cond
[(eq? s 'rsquo) "'"]
[else s]))
(define (loop init-line! quote-depth)
(lambda (c)
(cond
@ -194,11 +198,13 @@
(out "; " comment-color)
(let ([v (syntax-object->datum (cadr (syntax->list c)))])
(if (paragraph? v)
(map (lambda (v) (if (string? v)
(out v comment-color)
(out v #f)))
(map (lambda (v)
(let ([v (no-fancy-chars v)])
(if (string? v)
(out v comment-color)
(out v #f))))
(paragraph-content v))
(out v comment-color)))]
(out (no-fancy-chars v) comment-color)))]
[(and (pair? (syntax-e c))
(eq? (syntax-e (car (syntax-e c))) 'code:contract))
(advance c init-line!)

4
collects/scribblings/reference/custodians.scrbl
View File

@ -47,7 +47,7 @@ which is the main variant of PLT Scheme, and not normally available in
PLT Scheme CGC.}}
@defproc[(custodian-require-memory [limit-cust custodian?]
[need-amt non-negative-exact-integer?]
[need-amt nonnegative-exact-integer?]
[stop-cust custodian?]) void?]{
Registers a require check if PLT Scheme is compiled with support for
@ -60,7 +60,7 @@ garbage collection (see @secref["mz:gc-model"]) where allocating
tigger some shutdown, then @scheme[stop-cust] is shut down.}
@defproc[(custodian-limit-memory [limit-cust custodian?]
[limit-amt non-negative-exact-integer?]
[limit-amt nonnegative-exact-integer?]
[stop-cust custodian? limit-cust]) void?]{
Registers a limit check if PLT Scheme is compiled with support for

1035
collects/scribblings/reference/custom-ports.scrbl Normal file
View File

File diff suppressed because it is too large Load Diff

2
collects/scribblings/reference/exns.scrbl
View File

@ -83,7 +83,7 @@ for end users.}
@defproc*[([(raise-type-error [name symbol?][expected string?][v any/c]) any]
[(raise-type-error [name symbol?][expected string?][bad-pos non-negative-exact-integer?][v any/c]) any])]{
[(raise-type-error [name symbol?][expected string?][bad-pos nonnegative-exact-integer?][v any/c]) any])]{
Creates an @scheme[exn:fail:contract] value and @scheme[raise]s it as
an exception. The @scheme[name] argument is used as the source

10
collects/scribblings/reference/file-ports.scrbl
View File

@ -56,7 +56,10 @@ closed, either though @scheme[close-input-port] or indirectly via
handle. The input port will not closed automatically if it is
otherwise available for garbage collection (see
@secref["mz:gc-model"]); a @tech{will} could be associated input port
to close it more automatically (see @secref["mz:wills"]). }
to close it more automatically (see @secref["mz:wills"]).
A @tech{path} value that is the expanded version of @scheme[path] is
used as the name of the opened port.}
@defproc[(open-output-file [path path-string?]
[#:mode mode-flag (one-of/c 'binary 'text) 'binary]
@ -119,7 +122,10 @@ closed, either though @scheme[close-output-port] or indirectly via
handle. The output port will not closed automatically if it is
otherwise available for garbage collection (see
@secref["mz:gc-model"]); a @tech{will} could be associated input port
to close it more automatically (see @secref["mz:wills"]).}
to close it more automatically (see @secref["mz:wills"]).
A @tech{path} value that is the expanded version of @scheme[path] is
used as the name of the opened port.}
@defproc[(open-input-output-file [path path-string?]
[#:mode mode-flag (one-of/c 'binary 'text) 'binary]

10
collects/scribblings/reference/pipes.scrbl
View File

@ -8,8 +8,8 @@ OS-level pipes (which are @tech{file-stream ports}) for communicating
between different processes.
@defproc[(make-pipe [limit positive-exact-integer? #f]
[input-name-v any/c #f]
[output-name-v any/c #f])
[input-name any/c 'pipe]
[output-name any/c 'pipe])
any]{
Returns two port values: the first port is an input port and the
@ -25,10 +25,8 @@ pipe's output port thereafter will block until a read or peek from the
input port makes more space available. (Peeks effectively extend the
port's capacity until the peeked bytes are read.)
The optional @scheme[input-name-v] and @scheme[output-name-v] are used
as the names for the returned input and out ports, respectively, if
they are supplied. (See also @scheme[object-name].) Otherwise, the
name of each port is @scheme['pipe].}
The optional @scheme[input-name] and @scheme[output-name] are used
as the names for the returned input and out ports, respectively.}
@defproc[(pipe-content-length [pipe-port port?]) any]{

95
collects/scribblings/reference/port-line-counting.scrbl Normal file
View File

@ -0,0 +1,95 @@
#reader(lib "docreader.ss" "scribble")
@require["mz.ss"]
@title[#:tag "mz:linecol"]{Counting Positions, Lines, and Columns}
@index['("line numbers")]{
@index['("column numbers")]{
@index['("port positions")]{
By}}} default, Scheme keeps track of the @deftech{position} in a port as the
number of bytes that have been read from or written to any port
(independent of the read/write position, which is accessed or changed
with @scheme[file-position]). Optionally, however, Scheme can track
the position in terms of characters (after UTF-8 decoding), instead of
bytes, and it can track @deftech{line locations} and @deftech{column
locations}; this optional tracking must be specifically enabled for a
port via @scheme[port-count-lines!] or the
@scheme[port-count-lines-enabled] parameter. Position, line, and
column locations for a port are used by @scheme[read-syntax] and
@scheme[read-honu-syntax]. Position and line locations are numbered
from @math{1}; column locations are numbered from @math{0}.
When counting lines, Scheme treats linefeed, return, and
return-linefeed combinations as a line terminator and as a single
position (on all platforms). Each tab advances the column count to one
before the next multiple of @math{8}. When a sequence of bytes in the
range 128 to 253 forms a UTF-8 encoding of a character, the
position/column is incremented is incremented once for each byte, and
then decremented appropriately when a complete encoding sequence is
discovered. See also @secref["mz:ports"] for more information on UTF-8
decoding for ports.
A position is known for any port as long as its value can be expressed
as a fixnum (which is more than enough tracking for realistic
applications in, say, syntax-error reporting). If the position for a
port exceeds the value of the largest fixnum, then the position for
the port becomes unknown, and line and column tacking is disabled.
Return-linefeed combinations are treated as a single character
position only when line and column counting is enabled.
Certain kinds of exceptions (see @secref["mz:exns"]) encapsulate
source-location information using a @scheme[srcloc] structure.
@;------------------------------------------------------------------------
@defproc[(port-count-lines! [port port?]) void?]{
Turns on line and column counting for a port. Counting can be turned
on at any time, though generally it is turned on before any data is
read from or written to a port. When a port is created, if the value
of the @scheme[port-count-lines-enabled] parameter is true, then line
counting is automatically enabled for the port. Line counting cannot
be disabled for a port after it is enabled.}
@defproc[(port-next-location [port port?])
(values (or/c positive-exact-integer? false/c)
(or/c nonnegative-exact-integer? false/c)
(or/c positive-exact-integer? false/c))]{
Returns three values: an integer or @scheme[#f] for the line number of
the next read/written item, an integer or @scheme[#f] for the next
item's column, and an integer or @scheme[#f] for the next item's
position. The next column and position normally increases as bytes are
read from or written to the port, but if line/character counting is
enabled for @scheme[port], the column and position results can
decrease after reading or writing a byte that ends a UTF-8 encoding
sequence.}
@defstruct[srcloc ([source any/c]
[line (or/c positive-exact-integer? false/c)]
[column (or/c nonnegative-exact-integer? false/c)]
[position (or/c positive-exact-integer? false/c)]
[span (or/c nonnegative-exact-integer? false/c)])
#:immutable
#:inspector #f]{
The fields of an @scheme[srcloc] instance are as follows:
@itemize{
@item{@scheme[source] --- An arbitrary value identifying the source,
often a path (see @secref["mz:pathutils"]).}
@item{@scheme[line] --- The line number (counts from 1) or
@scheme[#f] (unknown).}
@item{@scheme[column] --- The column number (counts from 0) or
@scheme[#f] (unknown).}
@item{@scheme[position] --- The starting position (counts from 1) or
@scheme[#f] (unknown).}
@item{@scheme[span] --- The number of covered positions (counts from
0) or @scheme[#f] (unknown).}
}}

6
collects/scribblings/reference/port-procs.scrbl
View File

@ -49,3 +49,9 @@ Returns @scheme[#t] if the given port is a file-stream port (see
@defproc[(terminal-port? [port port?]) boolean?]{
Returns @scheme[#t] if the given port is attached to an interactive
terminal, @scheme[#f] otherwise.}
@defthing[eof eof-object?]{A value (distinct from all other values)
that represents an end-of-file.}
@defproc[(eof-object [a any/c]) boolean?]{Returns @scheme[#t] is
@scheme[v] is @scheme[eof], @scheme[#f] otherwise.}

26
collects/scribblings/reference/ports.scrbl
View File

@ -33,19 +33,29 @@ conversions using UTF-8 or other encodings. See also
obtaining a UTF-8-based port from one that uses a different encoding
of characters.
The global variable @scheme[eof] is bound to the end-of-file
value. The standard predicate @scheme[eof-object?] returns @scheme[#t]
only when applied to this value. Reading from a port produces an
end-of-file result when the port has no more data, but some ports may
also return end-of-file mid-stream. For example, a port connected to a
Unix terminal returns an end-of-file when the user types control-D; if
the user provides more input, the port returns additional bytes after
the end-of-file.
The global variable @scheme[eof] is bound to the end-of-file value,
and @scheme[eof-object?] returns @scheme[#t] only when applied to this
value. Reading from a port produces an end-of-file result when the
port has no more data, but some ports may also return end-of-file
mid-stream. For example, a port connected to a Unix terminal returns
an end-of-file when the user types control-D; if the user provides
more input, the port returns additional bytes after the end-of-file.
Every port has a name, as reported by @scheme[object-name]. The name
can be any value, and it is used mostly for error-reporting
purposes. The @scheme[read-syntax] procedure uses the name of an input
port as the default source location for the @tech{syntax objects} that
it produces.
@;------------------------------------------------------------------------
@local-table-of-contents[]
@include-section["port-procs.scrbl"]
@include-section["port-buffers.scrbl"]
@include-section["port-line-counting.scrbl"]
@include-section["file-ports.scrbl"]
@include-section["string-ports.scrbl"]
@include-section["pipes.scrbl"]
@include-section["prop-port.scrbl"]
@include-section["custom-ports.scrbl"]

35
collects/scribblings/reference/prop-port.scrbl Normal file
View File

@ -0,0 +1,35 @@
#reader(lib "docreader.ss" "scribble")
@require["mz.ss"]
@title[#:tag "mz:portstructs"]{Structures as Ports}
@defthing[prop:input-port struct-type-property?]
@defthing[prop:output-port struct-type-property?]
The @scheme[prop:input-port] and @scheme[prop:output-port] structure type
properties identify structure types whose instances can serve as input
and output ports, respectively.
Each property value can be either of the following:
@itemize{
@item{An input port (for @scheme[prop:input-port]) or output port
(for @scheme[prop:input-port]): In this case, using the structure
as port is equivalent to using the given one.}
@item{An exact, non-negative integer between @scheme[0] (inclusive) and
number of non-automatic fields in the structure type (exclusive, not
counting supertype fields): The integer identifies a field in
the structure, and the field must be designated as immutable. If the
field contains an input port (for @scheme[prop:input-port]) or
output port (for @scheme[prop:input-port]), the port is used.
Otherwise, an empty string input port is used for @scheme[prop:input-port],
and a port that discards all data is used for @scheme[prop:output-port].}
}
Some procedures, such as @scheme[file-position], work on both input
and output ports. When given an instance of a structure type with both
the @scheme[prop:input-port] and @scheme[prop:output-port] properties,
the instance is used as an input port.

2
collects/scribblings/reference/semaphores.scrbl
View File

@ -20,7 +20,7 @@ thread is eventually unblocked.
In addition to its use with semaphore-specific procedures, semaphores
can be used as events; see @secref["mz:sync"].
@defproc[(make-semaphore [init non-negative-exact-integer? 0]) semaphore?]{
@defproc[(make-semaphore [init nonnegative-exact-integer? 0]) semaphore?]{
Creates and returns a new semaphore with the counter initially set to
@scheme[init]. If @scheme[init-k] is larger than a semaphore's maximum

69
collects/scribblings/reference/string-ports.scrbl Normal file
View File

@ -0,0 +1,69 @@
#reader(lib "docreader.ss" "scribble")
@require["mz.ss"]
@title[#:tag "mz:stringport"]{String Ports}
String input and output ports do not need to be explicitly closed. The
@scheme[file-position] procedure works for string ports in
position-setting mode.
@defproc[(open-input-bytes [bstr bytes?][name any/c 'string]) input-port?]{
Creates an input port that reads characters from @scheme[bstr] (see
@secref["mz:bytestrings"]). Modifying @scheme[bstr] afterward does not
affect the byte stream produced by the port. The optional
@scheme[name] argument is used as the name for the returned port.}
@defproc[(open-input-string [str string?][name any/c 'string]) input-port?]{
Creates an input port that reads bytes from the UTF-8 encoding (see
@secref["mz:encodings"]) of @scheme[str]. The optional @scheme[name]
argument is used as the name for the returned port.}
@defproc[(open-output-bytes [name any/c 'string]) output-port?]{
Creates an output port that accumulates the output into a byte
string. The optional @scheme[name] argument is used as the name for
the returned port.}
@defproc[(open-output-string [name any/c 'string]) output-port?]{The
same as @scheme[open-output-bytes].}
@defproc[(get-output-bytes [out output-port?]
[reset? any/c #f]
[start-pos nonnegative-exact-integer? 0]
[end-pos nonnegative-exact-integer? #f])
bytes?]{
Returns the bytes accumulated in @scheme[out] so far in a
freshly-allocated byte string (including any bytes written after the
port's current position, if any). the @scheme[out] port must be a
string output port produced by @scheme[open-output-bytes] (or
@scheme[open-output-string]) or a structure whose
@scheme[prop:output-port] property refers to such an output port
(transitively).
If @scheme[reset?] is true, then all bytes are removed from the port,
and the port's position is reset to @scheme[0]; if @scheme[reset?] is
@scheme[#f], then all bytes remain in the port for further
accumulation (so they are returned for later calls to
@scheme[get-output-bytes] or @scheme[get-output-string]), and the
port's position is unchanged.
The @scheme[start-pos] and @scheme[end-pos] arguments specify the
range of bytes in the port to return; supplying @scheme[start-pos] and
@scheme[end-pos] is the same as using @scheme[subbytes] on the result
of @scheme[get-output-bytes], but supplying them to
@scheme[get-output-bytes] can avoid an allocation. The
@scheme[end-pos] argument can be @scheme[#f], which corresponds to not
passing a second argument to @scheme[subbytes].}
@defproc[(get-output-string [out output-port?]) string?]{
Returns @scheme[(bytes->string/utf-8 (get-output-bytes out) #\?)].}
@examples[
(define i (open-input-string "hello world"))
(define o (open-output-string))
(write (read i) o)
(get-output-string o)
]

8
collects/scribblings/reference/struct.scrbl
View File

@ -61,8 +61,8 @@ depends on the current inspector.)
@defproc[(make-struct-type [name symbol?]
[super-type (or/c struct-type? false/c)]
[init-field-cnt non-negative-exact-integer?]
[auto-field-cnt non-negative-exact-integer?]
[init-field-cnt nonnegative-exact-integer?]
[auto-field-cnt nonnegative-exact-integer?]
[auto-v any/c #f]
[props (listof (cons/c struct-type-property?
any/c))
@ -70,10 +70,10 @@ depends on the current inspector.)
[inspector (or/c inspector? false/c)
(current-inspector)]
[proc-spec (or/c procedure?
non-negative-exact-integer?
nonnegative-exact-integer?
false/c)
#f]
[immutables (listof non-negative-exact-integer?)
[immutables (listof nonnegative-exact-integer?)
null]
[guard (or/c procedure? false/c) #f])
(values struct-type?