doc work, especially ports in reference

svn: r6795

collects/scribble/comment-reader.ss

@@ -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))]))))))))
+                    

collects/scribble/eval.ss

@@ -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)]))
 

collects/scribble/manual.ss

@@ -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))

collects/scribble/scheme.ss

@@ -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)
+                  (map (lambda (v) 
-                                       (out v comment-color)
+                         (let ([v (no-fancy-chars v)])
-                                       (out v #f)))
+                           (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!)

collects/scribblings/reference/custodians.scrbl

@@ -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

collects/scribblings/reference/exns.scrbl

@@ -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

collects/scribblings/reference/file-ports.scrbl

@@ -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]

collects/scribblings/reference/pipes.scrbl

@@ -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]
+                    [input-name any/c 'pipe]
-                    [output-name-v any/c #f])
+                    [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
+The optional @scheme[input-name] and @scheme[output-name] are used
-as the names for the returned input and out ports, respectively, if
+as the names for the returned input and out ports, respectively.}
-they are supplied. (See also @scheme[object-name].) Otherwise, the
-name of each port is @scheme['pipe].}
 
 @defproc[(pipe-content-length [pipe-port port?]) any]{
 

collects/scribblings/reference/port-line-counting.scrbl

@@ -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).}
+
+}}

collects/scribblings/reference/port-procs.scrbl

@@ -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.}

collects/scribblings/reference/ports.scrbl

@@ -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
+The global variable @scheme[eof] is bound to the end-of-file value,
-value. The standard predicate @scheme[eof-object?] returns @scheme[#t]
+and @scheme[eof-object?] returns @scheme[#t] only when applied to this
-only when applied to this value. Reading from a port produces an
+value. Reading from a port produces an end-of-file result when the
-end-of-file result when the port has no more data, but some ports may
+port has no more data, but some ports may also return end-of-file
-also return end-of-file mid-stream. For example, a port connected to a
+mid-stream. For example, a port connected to a Unix terminal returns
-Unix terminal returns an end-of-file when the user types control-D; if
+an end-of-file when the user types control-D; if the user provides
-the user provides more input, the port returns additional bytes after
+more input, the port returns additional bytes after the end-of-file.
-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"]

collects/scribblings/reference/prop-port.scrbl

@@ -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.

collects/scribblings/reference/semaphores.scrbl

@@ -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

collects/scribblings/reference/string-ports.scrbl

@@ -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)
+]

collects/scribblings/reference/struct.scrbl

@@ -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?]
+                           [init-field-cnt nonnegative-exact-integer?]
-                           [auto-field-cnt non-negative-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?