From 3856d9e6a4c64579a7149ec386e087bfba1ed907 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 6 Jun 2007 06:08:46 +0000 Subject: [PATCH] reference work, and also change ...0 and ...1 to ... and ...+ svn: r6498 --- collects/scribble/html-render.ss | 1 + collects/scribble/manual.ss | 170 ++++++++++------- collects/scribble/scheme.ss | 14 +- collects/scribblings/guide/guide.scrbl | 2 +- collects/scribblings/reference/bytes.scrbl | 10 +- collects/scribblings/reference/data.scrbl | 13 +- collects/scribblings/reference/numbers.scrbl | 32 ++-- .../scribblings/reference/reference.scrbl | 2 +- .../scribblings/reference/sequences.scrbl | 174 ++++++++++++++++++ collects/scribblings/reference/strings.scrbl | 40 ++-- collects/scribblings/scribble/basic.scrbl | 16 +- collects/scribblings/scribble/manual.scrbl | 51 ++--- .../docs/reference/configuration.scrbl | 2 +- .../docs/reference/dispatchers.scrbl | 2 +- 14 files changed, 380 insertions(+), 149 deletions(-) create mode 100644 collects/scribblings/reference/sequences.scrbl diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss index 35f12ed3f3..79abaefc89 100644 --- a/collects/scribble/html-render.ss +++ b/collects/scribble/html-render.ss @@ -206,6 +206,7 @@ ,@(case va [(#f) null] [(top) '((valign "top"))] + [(baseline) '((valign "baseline"))] [(bottom) '((valign "bottom"))])) ,@(render-flow d part ht))) flows diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 6b8a9f31b2..49e7ab19bc 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -160,14 +160,47 @@ (define dots1 (make-element #f (list "..." (superscript "+")))) + (define-syntax (arg-contract stx) + (syntax-case stx (... ...+) + [(_ [id contract]) + (identifier? #'id) + #'(schemeblock0 contract)] + [(_ [id contract val]) + (identifier? #'id) + #'(schemeblock0 contract)] + [(_ [kw id contract]) + (and (keyword? (syntax-e #'kw)) + (identifier? #'id)) + #'(schemeblock0 contract)] + [(_ [kw id contract val]) + (and (keyword? (syntax-e #'kw)) + (identifier? #'id)) + #'(schemeblock0 contract)] + [(_ (... ...)) + #'#f] + [(_ (... ...+)) + #'#f] + [(_ arg) + (raise-syntax-error + 'defproc + "bad argument form" + #'arg)])) + + (define-syntax defproc (syntax-rules () - [(_ s-exp result desc ...) - (*defproc '[s-exp] '[result] (lambda () (list desc ...)))])) + [(_ (id arg ...) result desc ...) + (*defproc '[(id arg ...)] + (list (list (lambda () (arg-contract arg)) ...)) + (list (lambda () (schemeblock0 result))) + (lambda () (list desc ...)))])) (define-syntax defproc* (syntax-rules () - [(_ [[s-exp result] ...] desc ...) - (*defproc '[s-exp ...] '[result ...] (lambda () (list desc ...)))])) + [(_ [[(id arg ...) result] ...] desc ...) + (*defproc '[(id arg ...) ...] + (list (list (lambda () (arg-contract arg)) ...) ...) + (list (lambda () (schemeblock0 result)) ...) + (lambda () (list desc ...)))])) (define-syntax defstruct (syntax-rules () [(_ name fields desc ...) @@ -219,13 +252,15 @@ (syntax-rules () [(_ id) (*var 'id)])) - (define (*defproc prototypes results content-thunk) + (define (*defproc prototypes arg-contractss result-contracts content-thunk) (let ([spacer (hspace 1)] [has-optional? (lambda (arg) (and (pair? arg) ((length arg) . > . (if (keyword? (car arg)) 3 2))))] + [to-flow (lambda (e) + (make-flow (list (make-paragraph (list e)))))] [arg->elem (lambda (v) (cond [(pair? v) @@ -234,9 +269,9 @@ (hspace 1) (to-element (cadr v)))) (to-element (car v)))] - [(eq? v '...1) + [(eq? v '...+) dots1] - [(eq? v '...0) + [(eq? v '...) dots0] [else v]))]) (parameterize ([current-variable-list @@ -253,75 +288,86 @@ (apply append (map - (lambda (prototype result first?) + (lambda (prototype arg-contracts result-contract first?) (append (list (list (make-flow (list - (make-paragraph + (make-table + '((valignment top top top top top)) (list - (let-values ([(required optional more-required) - (let loop ([a (cdr prototype)][r-accum null]) - (if (or (null? a) - (and (has-optional? (car a)))) - (let ([req (reverse r-accum)]) - (let loop ([a a][o-accum null]) - (if (or (null? a) - (not (has-optional? (car a)))) - (values req (reverse o-accum) a) - (loop (cdr a) (cons (car a) o-accum))))) - (loop (cdr a) (cons (car a) r-accum))))]) - (to-element (append - (list (if first? - (make-target-element - #f - (list (to-element (car prototype))) - (register-scheme-definition (car prototype))) - (to-element (car prototype)))) - (map arg->elem required) - (if (null? optional) - null - (list - (to-element - (syntax-property - (syntax-ize (map arg->elem optional) 0) - 'paren-shape - #\?)))) - (map arg->elem more-required)))) - (hspace 2) - 'rarr - (hspace 2) - (to-element result))))))) + (list + (to-flow + (let-values ([(required optional more-required) + (let loop ([a (cdr prototype)][r-accum null]) + (if (or (null? a) + (and (has-optional? (car a)))) + (let ([req (reverse r-accum)]) + (let loop ([a a][o-accum null]) + (if (or (null? a) + (not (has-optional? (car a)))) + (values req (reverse o-accum) a) + (loop (cdr a) (cons (car a) o-accum))))) + (loop (cdr a) (cons (car a) r-accum))))]) + (to-element (append + (list (if first? + (make-target-element + #f + (list (to-element (car prototype))) + (register-scheme-definition (car prototype))) + (to-element (car prototype)))) + (map arg->elem required) + (if (null? optional) + null + (list + (to-element + (syntax-property + (syntax-ize (map arg->elem optional) 0) + 'paren-shape + #\?)))) + (map arg->elem more-required))))) + (to-flow spacer) + (to-flow 'rarr) + (to-flow spacer) + (make-flow (list (result-contract)))))))))) (apply append - (map (lambda (v) + (map (lambda (v arg-contract) (cond [(pair? v) (list (list (make-flow (list - (let ([v (if (keyword? (car v)) - (cdr v) - v)]) - (make-paragraph (append - (list - (hspace 2) - (arg->elem v)) - (list - spacer - ":" - spacer - (to-element (cadr v))) - (if (has-optional? v) - (list spacer - "=" - spacer - (to-element (caddr v))) - null))))))))] + (make-table + `((valignment baseline baseline baseline baseline + baseline baseline + ,@(if (has-optional? v) + '(baseline baseline baseline baseline) + null))) + (list + (let ([v (if (keyword? (car v)) + (cdr v) + v)]) + (append + (list + (to-flow (hspace 2)) + (to-flow (arg->elem v)) + (to-flow spacer) + (to-flow ":") + (to-flow spacer) + (make-flow (list (arg-contract)))) + (if (has-optional? v) + (list (to-flow spacer) + (to-flow "=") + (to-flow spacer) + (to-flow (to-element (caddr v)))) + null)))))))))] [else null])) - (cdr prototype))))) + (cdr prototype) + arg-contracts)))) prototypes - results + arg-contractss + result-contracts (cons #t (map (lambda (x) #f) (cdr prototypes)))))) (content-thunk)))))) diff --git a/collects/scribble/scheme.ss b/collects/scribble/scheme.ss index 523be3619e..7b2789545a 100644 --- a/collects/scribble/scheme.ss +++ b/collects/scribble/scheme.ss @@ -64,10 +64,14 @@ (define out (case-lambda [(v cls) - (out v cls (cond - [(string? v) (string-length v)] - [(sized-element? v) (sized-element-length v)] - [else 1]))] + (out v cls (let sz-loop ([v v]) + (cond + [(string? v) (string-length v)] + [(sized-element? v) (sized-element-length v)] + [(and (element? v) + (= 1 (length (element-content v)))) + (sz-loop (car (element-content v)))] + [else 1])))] [(v cls len) (unless (equal? v "") (if (equal? v "\n") @@ -378,7 +382,7 @@ (finish-line!)) (if multi-line? (make-table #f (map list (reverse docs))) - (make-element #f (reverse content))))) + (make-sized-element #f (reverse content) dest-col)))) (define (to-element c) (typeset c #f "" "" #t)) diff --git a/collects/scribblings/guide/guide.scrbl b/collects/scribblings/guide/guide.scrbl index 7127417f0d..be486e1b99 100644 --- a/collects/scribblings/guide/guide.scrbl +++ b/collects/scribblings/guide/guide.scrbl @@ -6,7 +6,7 @@ @title{A Guide to PLT Scheme} This guide is intended for programmers who are new to Scheme, new to PLT -Scheme, or new to some part of PLT Scheme. It assumes some +Scheme, or new to some part of PLT Scheme. It assumes programming experience, so if you are new to programming, consider instead reading @|HtDP|. If you want a quick and pretty overview of PLT Scheme, start with @|Quick|. diff --git a/collects/scribblings/reference/bytes.scrbl b/collects/scribblings/reference/bytes.scrbl index 2dda82a72e..2753d19b4d 100644 --- a/collects/scribblings/reference/bytes.scrbl +++ b/collects/scribblings/reference/bytes.scrbl @@ -31,7 +31,7 @@ position in the byte string is initialized with the byte @scheme[b]. @examples[(make-bytes 5 65)]} -@defproc[(bytes [b byte?] ...0) bytes?]{ Returns a new mutable byte +@defproc[(bytes [b byte?] ...) bytes?]{ Returns a new mutable byte string whose length is the number of provided @scheme[b]s, and whose positions are initialized with the given @scheme[b]s. @@ -133,7 +133,7 @@ positions are initialized with the given @scheme[b]s. s]} -@defproc[(bytes-append [bstr bytes?] ...0) bytes?]{ Returns a new +@defproc[(bytes-append [bstr bytes?] ...) bytes?]{ Returns a new mutable byte string that is as long as the sum of the given @scheme[bstr]s' lengths, and that contains the concatenated bytes of the given @scheme[bstr]s. If no @scheme[bstr]s are provided, the result is a zero-length @@ -164,7 +164,7 @@ positions are initialized with the given @scheme[b]s. @section{Byte String Comparisons} -@defproc[(bytes=? [bstr1 bytes?] [bstr2 bytes?] ...1) boolean?]{ Returns +@defproc[(bytes=? [bstr1 bytes?] [bstr2 bytes?] ...+) boolean?]{ Returns @scheme[#t] if all of the arguments are @scheme[eqv?].} @examples[(bytes=? #"Apple" #"apple") @@ -173,7 +173,7 @@ positions are initialized with the given @scheme[b]s. @define[(bytes-sort direction) @elem{Like @scheme[bytes? [bstr1 bytes?] [bstr2 bytes?] ...1) boolean?]{ +@defproc[(bytes>? [bstr1 bytes?] [bstr2 bytes?] ...+) boolean?]{ @bytes-sort["decreasing"] @examples[(bytes>? #"Apple" #"apple") diff --git a/collects/scribblings/reference/data.scrbl b/collects/scribblings/reference/data.scrbl index 1cf901d834..402120de95 100644 --- a/collects/scribblings/reference/data.scrbl +++ b/collects/scribblings/reference/data.scrbl @@ -123,10 +123,10 @@ the empty list, @scheme[#f] otherwise.} @defproc[(empty? [v any/c]) boolean?]{The same as @scheme[(null? v)].} -@defproc[(list [v any/c] ...0) list?]{Returns a newly allocated list +@defproc[(list [v any/c] ...) list?]{Returns a newly allocated list containing the @scheme[v]s as its elements.} -@defproc[(map [proc procedure?] [lst (listof any/c)] ...1) (listof +@defproc[(map [proc procedure?] [lst (listof any/c)] ...+) (listof any/c)]{Applies @scheme[proc] to the elements of the @scheme[lst]s from the first elements to the last, returning @scheme[#f] as soon as any application returns @scheme[#f]. The @scheme[proc] argument must accept @@ -134,7 +134,7 @@ containing the @scheme[v]s as its elements.} and all @scheme[lst]s must have the same number of elements. The result is a list containing each result of @scheme[proc].} -@defproc[(andmap [proc procedure?] [lst (listof any/c)] ...1) +@defproc[(andmap [proc procedure?] [lst (listof any/c)] ...+) any]{Similar to @scheme[map], except that @itemize{ @@ -159,7 +159,7 @@ If the @scheme[lst]s are empty, then @scheme[#t] is returned.} (andmap + '(1 2 3) '(4 5 6)) ] -@defproc[(ormap [proc procedure?] [lst (listof any/c)] ...1) +@defproc[(ormap [proc procedure?] [lst (listof any/c)] ...+) any]{Similar to @scheme[map], except that @itemize{ @@ -184,7 +184,7 @@ If the @scheme[lst]s are empty, then @scheme[#f] is returned.} (ormap + '(1 2 3) '(4 5 6)) ] -@defproc[(for-each [proc procedure?] [lst (listof any/c)] ...1) +@defproc[(for-each [proc procedure?] [lst (listof any/c)] ...+) void?]{Similar to @scheme[map], but @scheme[proc] is called only for its effect, and its result (which can be any number of values) is ignored.} @@ -193,6 +193,9 @@ If the @scheme[lst]s are empty, then @scheme[#f] is returned.} @; ---------------------------------------------------------------------- @section[#:tag "hashtables"]{Hash Tables} +@; ---------------------------------------------------------------------- +@include-section["sequences.scrbl"] + @section[#:tag "procedures"]{Procedures} @; ---------------------------------------------------------------------- diff --git a/collects/scribblings/reference/numbers.scrbl b/collects/scribblings/reference/numbers.scrbl index 0edb55664e..1ede33e0ba 100644 --- a/collects/scribblings/reference/numbers.scrbl +++ b/collects/scribblings/reference/numbers.scrbl @@ -156,7 +156,7 @@ noted above). Two numbers are @scheme[equal?] when they are @; ---------------------------------------- @section{Arithmetic} -@defproc[(+ [z number?] ...0) number?]{ Returns the sum of the +@defproc[(+ [z number?] ...) number?]{ Returns the sum of the @scheme[z]s, adding pairwise from left to right. If no arguments are provided, the result is @scheme[0]. @@ -164,7 +164,7 @@ noted above). Two numbers are @scheme[equal?] when they are @defproc*[([(- [z number?]) number?] - [(- [z number?] [w number?] ...1) number?])]{ + [(- [z number?] [w number?] ...+) number?])]{ When no @scheme[w]s are supplied, returns @scheme[(- 0 #, @scheme[z])]. Otherwise, returns the subtraction of the @scheme[w]s from @scheme[z] working pairwise from left to right.} @@ -172,7 +172,7 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(- 5 3.0) (- 1) (- 2+7i 1 3)] -@defproc[(* [z number?] ...0) number?]{ Returns the product of the +@defproc[(* [z number?] ...) number?]{ Returns the product of the @scheme[z]s, multiplying pairwise from left to right. If no arguments are provided, the result is @scheme[1].} @@ -180,7 +180,7 @@ noted above). Two numbers are @scheme[equal?] when they are @defproc*[([(/ [z number?]) number?] - [(/ [z number?] [w number?] ...1) number?])] { + [(/ [z number?] [w number?] ...+) number?])] { When no @scheme[w]s are supplied, returns @scheme[(/ 1 #, @scheme[z])]. Otherwise, returns the division @scheme[z] by the var[w]s working pairwise from left to right.} @@ -231,28 +231,28 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(abs 1.0) (abs -1)]} -@defproc[(max [x real?] ...1) boolean?]{ Returns the largest of the +@defproc[(max [x real?] ...+) boolean?]{ Returns the largest of the @scheme[x]s, or @scheme[+nan.0] if any @scheme[x] is @scheme[+nan.0]. If any @scheme[x] is inexact, the result is coerced to inexact. @examples[(max 1 3 2) (max 1 3 2.0)]} -@defproc[(min [x real?] ...1) boolean?]{ Returns the smallest of the +@defproc[(min [x real?] ...+) boolean?]{ Returns the smallest of the @scheme[x]s, or @scheme[+nan.0] if any @scheme[x] is @scheme[+nan.0]. If any @scheme[x] is inexact, the result is coerced to inexact. @examples[(min 1 3 2) (min 1 3 2.0)]} -@defproc[(gcd [n integer?] ...0) integer?]{ Returns the greatest common +@defproc[(gcd [n integer?] ...) integer?]{ Returns the greatest common divisor of the @scheme[n]s. If no arguments are provided, the result is @scheme[0]. @examples[(gcd 10) (gcd 12 81.0)]} -@defproc[(lcm [n integer?] ...0) integer?]{ Returns the least common +@defproc[(lcm [n integer?] ...) integer?]{ Returns the least common multiple of the @scheme[n]s. If no arguments are provided, the result is @scheme[1]. @@ -307,7 +307,7 @@ noted above). Two numbers are @scheme[equal?] when they are @; ---------------------------------------- @section{Number Comparison} -@defproc[(= [z number?] [w number?] ...1) boolean?]{ Returns +@defproc[(= [z number?] [w number?] ...+) boolean?]{ Returns @scheme[#t] if all of the arguments are numerically equal, @scheme[#f] otherwise. An inexact number is numerically equal to an exact number when the exact coercion of the inexact number is the @@ -317,28 +317,28 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(= 1 1.0) (= 1 2) (= 2+3i 2+3i 2+3i)]} -@defproc[(< [x real?] [y real?] ...1) boolean?]{ Returns @scheme[#t] if +@defproc[(< [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] if the arguments in the given order are in strictly increasing, @scheme[#f] otherwise. @examples[(< 1 1) (< 1 2 3) (< 1 +inf.0) (< 1 +nan.0)]} -@defproc[(<= [x real?] [y real?] ...1) boolean?]{ Returns @scheme[#t] +@defproc[(<= [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] if the arguments in the given order are in non-decreasing, @scheme[#f] otherwise. @examples[(<= 1 1) (<= 1 2 1)]} -@defproc[(> [x real?] [y real?] ...1) boolean?]{ Returns @scheme[#t] if +@defproc[(> [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] if the arguments in the given order are in strictly decreasing, @scheme[#f] otherwise. @examples[(> 1 1) (> 3 2 1) (> +inf.0 1) (< +nan.0 1)]} -@defproc[(>= [x real?] [y real?] ...1) boolean?]{ Returns @scheme[#t] +@defproc[(>= [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] if the arguments in the given order are in non-increasing, @scheme[#f] otherwise. @@ -469,7 +469,7 @@ noted above). Two numbers are @scheme[equal?] when they are @; ------------------------------------------------------------------------ @section{Bitwise Operations} -@defproc[(bitwise-ior [n exact-integer?] ...0) exact-integer?]{ Returns +@defproc[(bitwise-ior [n exact-integer?] ...) exact-integer?]{ Returns the bitwise ``inclusive or'' of the @scheme[n]s in their (semi-infinite) two's complement representation. If no arguments are provided, the result is @scheme[0]. @@ -477,7 +477,7 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(bitwise-ior 1 2) (bitwise-ior -32 1)]} -@defproc[(bitwise-and [n exact-integer?] ...0) exact-integer?]{ Returns +@defproc[(bitwise-and [n exact-integer?] ...) exact-integer?]{ Returns the bitwise ``and'' of the @scheme[n]s in their (semi-infinite) two's complement representation. If no arguments are provided, the result is @scheme[-1]. @@ -485,7 +485,7 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(bitwise-and 1 2) (bitwise-and -32 -1)]} -@defproc[(bitwise-xor [n exact-integer?] ...0) exact-integer?]{ Returns +@defproc[(bitwise-xor [n exact-integer?] ...) exact-integer?]{ Returns the bitwise ``exclusive or'' of the @scheme[n]s in their (semi-infinite) two's complement representation. If no arguments are provided, the result is @scheme[0]. diff --git a/collects/scribblings/reference/reference.scrbl b/collects/scribblings/reference/reference.scrbl index 6709834523..66a50a2e1b 100644 --- a/collects/scribblings/reference/reference.scrbl +++ b/collects/scribblings/reference/reference.scrbl @@ -6,7 +6,7 @@ This manual defines the core PLT Scheme language and describes its most prominent libraries. The companion manual @italic{@link["../guide/index.html"]{A Guide to PLT Scheme}} provides -a friendlier (though less precise and complete) overview of the +a friendlier (though less precise and less complete) overview of the language. @table-of-contents[] diff --git a/collects/scribblings/reference/sequences.scrbl b/collects/scribblings/reference/sequences.scrbl new file mode 100644 index 0000000000..0c2f81aa75 --- /dev/null +++ b/collects/scribblings/reference/sequences.scrbl @@ -0,0 +1,174 @@ +#reader(lib "docreader.ss" "scribble") +@require["mz.ss"] + +@title[#:tag "mz:sequences"]{Sequences} + +A @pidefterm{sequence} encapsulates an ordered stream of values. The +elements of a sequence can be extracted with one of the @scheme[for] +syntactic forms or with the procedures returned by +@scheme[generate-sequence]. + +The datatype overlaps with many other datatypes, because it includes +the following: + +@itemize{ + + @item{lists; see @secref["mz:pairs"]} + + @item{vectors; see @secref["mz:vectors"]} + + @item{hash tables; see @secref["mz:hashtables"]} + + @item{strings; see @secref["mz:strings"]} + + @item{byte strings; see @secref["mz:bytestrings"]} + + @item{input ports; see @secref["mz:input-ports"]} + +} + +In addition, @scheme[make-do-sequence] creates a sequence given a +thunk that returns procedures to implement a generator. + +For most sequence types, extracting elements from a sequence has no +side-effect on the original sequence value; for example, extracting the +sequence of elements from a list does not change the list. For other +sequence types, each extraction implies a side effect; for example, +extracting the sequence of bytes from a port cause the bytes to be +read from the port. + +Inidvidual elements of a sequence typically correspond to single +values, but an element may also correspond to multiple values. For +example, a hash table generates two values---a key and its value---for +each element in the sequence. + +@section{Sequence Predicate and Constructors} + +@defproc[(sequence? [v any/c]) boolean?]{ Return @scheme[#t] if +@scheme[v] can be used as a sequence, @scheme[#f] otherwise.} + +@defproc*[([(in-range [end number?]) sequence?] + [(in-range [start number?] [end number?] [step number? 1]) sequence?])]{ +Returns a sequence whose elements are numbers. The single-argument +case @scheme[(in-range end)] is equivalent to @scheme[(in-range 0 end +1)]. The first number in the sequence is @scheme[start], and each +successive element is generated by adding @scheme[step] to the +previous element. The sequence starts before an element that would be +greater or equal to @scheme[end] if @scheme[step] is non-negative, or +less or equal to @scheme[end] if @scheme[step] is negative.} + +@defproc[(in-naturals [start exact-nonnegative-integer? 0]) sequence?]{ +Returns an infinite sequence of exact integers starting with +@scheme[start], where each element is one more than the preceeding +element.} + +@defproc[(in-list [lst list?]) sequence?]{ +Returns a sequence equivalent to @scheme[lst].} + +@defproc[(in-vector [vec vector?]) sequence?]{ +Returns a sequence equivalent to @scheme[vec].} + +@defproc[(in-string [str string?]) sequence?]{ +Returns a sequence equivalent to @scheme[str].} + +@defproc[(in-bytes [bstr bytes?]) sequence?]{ +Returns a sequence equivalent to @scheme[bstr].} + +@defproc[(in-input-port-bytes [inp input-port?]) sequence?]{ +Returns a sequence equivalent to @scheme[inp].} + +@defproc[(in-input-port-chars [inp input-port?]) sequence?]{ Returns a +sequence whose elements are read as characters form @scheme[inp] (as +opposed to using @scheme[inp] directly as a sequence to get bytes).} + +@defproc[(in-hash-table [ht hash-table?]) sequence?]{ +Returns a sequence equivalent to @scheme[ht].} + +@defproc[(in-hash-table-keys [ht hash-table?]) sequence?]{ +Returns a sequence whose elements are the keys of @scheme[ht].} + +@defproc[(in-hash-table-values [ht hash-table?]) sequence?]{ +Returns a sequence whose elements are the values of @scheme[ht].} + +@defproc[(in-hash-table-pairs [ht hash-table?]) sequence?]{ +Returns a sequence whose elements are pairs, each containing a key and +its value from @scheme[ht] (as opposed to using @scheme[ht] directly +as a sequence to get the key and value as separate values for each +element).} + +@defproc[(in-indexed [seq sequence?]) sequence?]{Returns a sequence +where each element has two values: the value produced by @scheme[seq], +and a non-negative exact integer starting with @scheme[0]. The +elements of @scheme[seq] must be single-valued.} + +@defproc[(in-parallel [seq sequence?] ...) sequence?]{Returns a +sequence where each element has as many values as the number of +supplied @scheme[seq]s; the values, in order, are the values of each +@scheme[seq]. The elements of each @scheme[seq] must be single-valued.} + +@defproc[(stop-before [seq sequence?] [pred (any/c . -> . any)]) +sequence?]{ Returns a sequence that contains the elements of +@scheme[seq] (which must be single-valued), but only until the last +element for which applying @scheme[pred] to the element produces +@scheme[#t], after whcih the sequence ends.} + +@defproc[(stop-after [seq sequence?] [pred (any/c . -> . any)]) +sequence?]{ Returns a sequence that contains the elements of +@scheme[seq] (which must be single-valued), but only until the element +(inclusive) for which applying @scheme[pred] to the element produces +@scheme[#t], after whcih the sequence ends.} + +@defproc[(make-do-sequence [thunk (->* () + ((any/c . -> . any/c) + (any/c . -> . any) + any/c + (() list? . ->* . any/c) + (() list? . ->* . any/c) + ((any/c) any/c . ->* . any/c)))]) + sequence?]{ + +Returns a sequence whose elements are generated by the procedures and +initial value returned by the thunk. The enerator is defined in terms +of a @defterm{position}, which is initialized to the third result of +the thunk, and the @defterm{element}, which may consist of multiple +values. + +The @scheme[thunk] results define the generated elements as follows: + +@itemize{ + + @item{The first result is a @scheme[_next-pos] procedure that takes + the current position and returns the next position.} + + @item{The second result is a @scheme[_pos->element] procedure that takes + the current position and returns the value(s) for the current element. + It is called only once per position.} + + @item{The third result is the initial position.} + + @item{The fourth result takes the current element value(s) and + returns a true result if the sequence includes the value, and + false result if the sequenec should insteda end insteda of + including the value.} + + @item{The fifth result is like the fourth result, but it determines a + sequence end @italic{after} the current element is already + included in the sequence.} + + @item{The sixth result is like the fourth result, but it takes both + the current position and the current element value(s).} + +} + +} + +@section{Sequence Generators} + +@defproc[(generate-sequence [seq sequence?]) (values (-> boolean?) + (-> any))]{ +Returns two thunks to extract elements from the sequence. The first +returns @scheme[#t] if more values are available for the sequence. The +second returns the next element (hich may be multiple values) from the +sequence; if no more elements are available, the +@exnraise[exn:fail:contract].} + diff --git a/collects/scribblings/reference/strings.scrbl b/collects/scribblings/reference/strings.scrbl index 229bde42b9..2d51d1b833 100644 --- a/collects/scribblings/reference/strings.scrbl +++ b/collects/scribblings/reference/strings.scrbl @@ -33,15 +33,15 @@ each position in the string is initialized with the character @examples[(make-string 5 #\z)]} -@defproc[(string [char char?] ...0) string?]{ Returns a new +@defproc[(string [char char?] ...) string?]{ Returns a new mutable string whose length is the number of provided @scheme[char]s, and whose positions are initialized with the given @scheme[char]s. @examples[(string #\A #\p #\p #\l #\e)]} -@defproc[(string->immutable-string [str string?]) (and/c string? - immutable?)]{ Returns an immutable string with the same content as +@defproc[(string->immutable-string [str string?]) (and/c string? immutable?)]{ +Returns an immutable string with the same content as @scheme[str], returning @scheme[str] itself if @scheme[str] is immutable.} @@ -128,7 +128,7 @@ whose positions are initialized with the given @scheme[char]s. s]} -@defproc[(string-append [str string?] ...0) string?]{ Returns a new +@defproc[(string-append [str string?] ...) string?]{ Returns a new mutable string that is as long as the sum of the given @scheme[str]s' lengths, and that contains the concatenated characters of the given @scheme[str]s. If no @scheme[str]s are provided, the result is a zero-length @@ -159,7 +159,7 @@ whose positions are initialized with the given @scheme[char]s. @section{String Comparisons} -@defproc[(string=? [str1 string?] [str2 string?] ...1) boolean?]{ Returns +@defproc[(string=? [str1 string?] [str2 string?] ...+) boolean?]{ Returns @scheme[#t] if all of the arguments are @scheme[eqv?].} @examples[(string=? "Apple" "apple") @@ -170,7 +170,7 @@ whose positions are initialized with the given @scheme[char]s. @elem{Like @scheme[string-ci? [str1 string?] [str2 string?] ...1) boolean?]{ +@defproc[(string>? [str1 string?] [str2 string?] ...+) boolean?]{ @string-sort["decreasing" #f] @examples[(string>? "Apple" "apple") (string>? "apple" "Apple") (string>? "c" "b" "a")]} -@defproc[(string>=? [str1 string?] [str2 string?] ...1) boolean?]{ +@defproc[(string>=? [str1 string?] [str2 string?] ...+) boolean?]{ @string-sort["nonincreasing" #f] @examples[(string>=? "Apple" "apple") @@ -201,14 +201,14 @@ whose positions are initialized with the given @scheme[char]s. (string>=? "c" "b" "b")]} -@defproc[(string-ci=? [str1 string?] [str2 string?] ...1) boolean?]{ +@defproc[(string-ci=? [str1 string?] [str2 string?] ...+) boolean?]{ Returns @scheme[#t] if all of the arguments are @scheme[eqv?] after locale-insensitive case-folding via @scheme[string-foldcase]. @examples[(string-ci=? "Apple" "apple") (string-ci=? "a" "a" "a")]} -@defproc[(string-ci? [str1 string?] [str2 string?] ...1) boolean?]{ +@defproc[(string-ci>? [str1 string?] [str2 string?] ...+) boolean?]{ @string-sort["decreasing" #t] @examples[(string-ci>? "Apple" "apple") (string-ci>? "banana" "Apple") (string-ci>? "c" "b" "a")]} -@defproc[(string-ci>=? [str1 string?] [str2 string?] ...1) boolean?]{ +@defproc[(string-ci>=? [str1 string?] [str2 string?] ...+) boolean?]{ @string-sort["nonincreasing" #t] @examples[(string-ci>=? "Apple" "apple") @@ -304,32 +304,32 @@ allocated string).} @; ---------------------------------------- @section{Locale-Specific String Operations} -@defproc[(string-locale=? [str1 string?] [str2 string?] ...1) +@defproc[(string-locale=? [str1 string?] [str2 string?] ...+) boolean?]{ Like @scheme[string=?], but the strings are compared in a locale-specific way, based the value of @scheme[current-locale]. See @secref["locales"] for more information on locales.} -@defproc[(string-locale? [str1 string?] [str2 string?] ...1) +@defproc[(string-locale>? [str1 string?] [str2 string?] ...+) boolean?]{ Like @scheme[string>?], but locale-specific like @scheme[string-locale? [str1 string?] [str2 string?] ...1) +@defproc[(string-locale-ci>? [str1 string?] [str2 string?] ...+) boolean?]{ Like @scheme[string>?], but both locale-sensitive and case-insensitive like @scheme[string-locale-ci=?].} diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl index 40f3f98127..eae16ed355 100644 --- a/collects/scribblings/scribble/basic.scrbl +++ b/collects/scribblings/scribble/basic.scrbl @@ -6,13 +6,13 @@ @define-syntax[def-title-like (syntax-rules () [(_ id result/c x ...) (defproc (id [#:tag tag (or/c false/c string?) #f] - [pre-content any/c] ...0) + [pre-content any/c] (... ...+)) result/c x ...)])] @define-syntax[def-elem-proc (syntax-rules () - [(_ id x ...) (defproc (id [pre-content any/c] ...0) + [(_ id x ...) (defproc (id [pre-content any/c] (... ...)) element? x ...)])] @define-syntax[def-style-proc @@ -66,7 +66,7 @@ have Scribble's @file{scheme.ss} and @file{manual.ss}). unnumbered section heading (for when the nesting gets too deep to include in a table of contents).} -@defproc[(itemize [itm (or/c whitespace? an-item?)] ...0) itemization?]{ +@defproc[(itemize [itm (or/c whitespace? an-item?)] ...) itemization?]{ Constructs an itemization given a sequence of items constructed by @scheme[item]. Whitespace strings among the @scheme[itm]s are @@ -74,7 +74,7 @@ have Scribble's @file{scheme.ss} and @file{manual.ss}). } -@defproc[(item pre-flow ...0) item?]{ +@defproc[(item [pre-flow any/c] ...) item?]{ Creates an item for use with @scheme[itemize]. The @scheme[pre-flow] list is parsed with @scheme[decode-flow]. } @@ -100,7 +100,7 @@ style @scheme[#f].} Produces an element containing @scheme[n] spaces and style @scheme['hspace]. } -@defproc[(span-class [style-name string?] [pre-content any/c] ...0) +@defproc[(span-class [style-name string?] [pre-content any/c] ...) element?]{ Parses the @scheme[pre-content] list using @scheme[decode-content], @@ -111,7 +111,7 @@ and produces an element with style @scheme[style-name]. @section{Indexing} @defproc[(index [words (or/c string? (listof string?))] - [pre-content any/c] ...0) + [pre-content any/c] ...) index-element?] { Creates an index element given a plain-text string---or list of @@ -126,14 +126,14 @@ refers. @defproc[(index* [words (listof string?)] [word-contents (listof list?)] - [pre-content any/c] ...0) + [pre-content any/c] ...) index-element?] { Like @scheme[index], except that @scheme[words] must be a list, and the list of contents render in the index (in parallel to @scheme[words]) is supplied as @scheme[word-contents]. } -@defproc[(as-index [pre-content any/c] ...0) +@defproc[(as-index [pre-content any/c] ...) index-element?] { Like @scheme[index], but the word to index is determined by applying diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index 364d50148f..5efabab02b 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -107,10 +107,10 @@ a single line and wrapped with its enclosing paragraph, independent of the formatting of @scheme[datum].} @defform[(schemeresult datum ...)]{Like @scheme[scheme], but typeset -as a REPL value (i.e., a single color with no hperlinks).} +as a REPL value (i.e., a single color with no hyperlinks).} @defform[(schemeid datum ...)]{Like @scheme[scheme], but typeset -as an unbound identifier (i.e., no coloring or hyperlink).} +as an unbound identifier (i.e., no coloring or hyperlinks).} @defform[(schememodname datum ...)]{Like @scheme[scheme], but typeset as a @schemefont{#module} language name.} @@ -125,24 +125,24 @@ as a table/paragraph in typewriter font with the linebreaks specified by newline characters in @scheme[str]. ``Here strings'' are often useful with @scheme[verbatim].} -@defproc[(schemefont [pre-content any/c] ...0) element?]{Typesets the given +@defproc[(schemefont [pre-content any/c] ...) element?]{Typesets the given content as uncolored, unhyperlinked Scheme. This procedure is useful for typesetting thngs like @scheme{#module}, which are not @scheme[read]able by themselves.} -@defproc[(schemevalfont [pre-content any/c] ...0) element?]{Like +@defproc[(schemevalfont [pre-content any/c] ...) element?]{Like @scheme[schemefont], but colored as a value.} -@defproc[(schemeresultfont [pre-content any/c] ...0) element?]{Like +@defproc[(schemeresultfont [pre-content any/c] ...) element?]{Like @scheme[schemefont], but colored as a REPL result.} -@defproc[(schemeidfont [pre-content any/c] ...0) element?]{Like +@defproc[(schemeidfont [pre-content any/c] ...) element?]{Like @scheme[schemefont], but colored as an identifier.} -@defproc[(schemekeywordfont [pre-content any/c] ...0) element?]{Like +@defproc[(schemekeywordfont [pre-content any/c] ...) element?]{Like @scheme[schemefont], but colored as a syntactic form name.} -@defproc[(procedure [pre-content any/c] ...0) element?]{Typesets the given +@defproc[(procedure [pre-content any/c] ...) element?]{Typesets the given content as a procedure name in a REPL result (e.g., in typewrite font with a @schemefont{#} suffix.).} @@ -173,7 +173,7 @@ Each @scheme[arg-spec] must have one of the following forms: @specsubform[(arg-id contract-expr-datum)]{ An argument whose contract is specified by @scheme[contract-expr-datum] which is typeset via - @scheme[scheme].} + @scheme[schemeblock0].} @specsubform[(arg-id contract-expr-datum default-expr)]{ Like the previous case, but with a default value. All arguments @@ -187,14 +187,14 @@ Each @scheme[arg-spec] must have one of the following forms: Like the previous case, but with a default value.} -@specsubform[#, @schemeidfont{...0}]{ Any number of the preceding argument +@specsubform[#, @schemeidfont{...}]{ Any number of the preceding argument (normally at the end).} -@specsubform[#, @schemeidfont{...1}]{One or more of the preceding argument +@specsubform[#, @schemeidfont{...+}]{One or more of the preceding argument (normally at the end).} The @scheme[result-contract-expr-datum] is typeset via -@scheme[scheme], and it represents a contract on the procedure's +@scheme[schemeblock0], and it represents a contract on the procedure's result. The @scheme[pre-flow]s list is parsed as a flow that documents the @@ -205,7 +205,7 @@ The typesetting of all data before the @scheme[pre-flow]s ignores the source layout.} -@defform[(defproc* ([(id arg-spec ...) +@defform[(defproc* ([(id arg-spec ...) result-contract-expr-datum] ...) pre-flow ...)]{ @@ -224,8 +224,11 @@ procedure. In this description, a reference to any identifier in @scheme[datum] is typeset as a sub-form non-terminal. The typesetting of @scheme[(id . datum)] preserves the source -layout, like @scheme[scheme], and unlike @scheme[defproc].} +layout, like @scheme[schemeblock], and unlike @scheme[defproc].} +@defform[(specform (id . datum) pre-flow ...)]{Like @scheme[defform], +with without registering a definition, and with indenting on the left +for both the specification and the @scheme[pre-flow]s.} @defform[(specsubform datum pre-flow ...)]{Similar to @scheme[defform], but without any specific identifier being defined, @@ -260,20 +263,20 @@ The @scheme[struct-name] can be either of the following: @; ------------------------------------------------------------------------ @section{Various String Forms} -@defproc[(defterm [pre-content any/c] ...0) element?]{Typesets the given +@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the given content as a defined term (e.g., in italic).} -@defproc[(onscreen [pre-content any/c] ...0) element?]{ Typesets the given +@defproc[(onscreen [pre-content any/c] ...) element?]{ Typesets the given content as a string that appears in a GUI, such as the name of a button.} @defproc[(menuitem [menu-name string?] [item-name string?]) element?]{ Typesets the given combination of a GUI's menu and item name.} -@defproc[(file [pre-content any/c] ...0) element?]{Typesets the given content +@defproc[(file [pre-content any/c] ...) element?]{Typesets the given content as a file name (e.g., in typewriter font and in in quotes).} -@defproc[(exec [pre-content any/c] ...0) element?]{Typesets the given content +@defproc[(exec [pre-content any/c] ...) element?]{Typesets the given content as a command line (e.g., in typewriter font).} @; ------------------------------------------------------------------------ @@ -282,10 +285,10 @@ as a command line (e.g., in typewriter font).} @defproc[(secref [tag string?]) element?]{Inserts the hyperlinked title of the section tagged @scheme[tag].} -@defproc[(seclink [tag string?] [pre-content any/c] ...0) element?]{The content from +@defproc[(seclink [tag string?] [pre-content any/c] ...) element?]{The content from @scheme[pre-content] is hyperlinked to the section tagged @scheme[tag].} -@defproc[(schemelink [id symbol?] [pre-content any/c] ...0) element?]{The content from +@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{The content from @scheme[pre-content] is hyperlinked to the definition of @scheme[id].} @@ -293,11 +296,11 @@ title of the section tagged @scheme[tag].} @; ------------------------------------------------------------------------ @section{Indexing} -@defproc[(idefterm [pre-content any/c] ...0) element?]{Combines +@defproc[(idefterm [pre-content any/c] ...) element?]{Combines @scheme[as-index] and @scheme[defterm]. The content normally should be plurarl, rather than singular.} -@defproc[(pidefterm [pre-content any/c] ...0) element?]{Like +@defproc[(pidefterm [pre-content any/c] ...) element?]{Like @scheme[idefterm], but plural: adds an ``s'' on the end of the content for the index entry.} @@ -311,9 +314,9 @@ the letters in the right case).} @defthing[undefined-const element?]{Returns an element for @|undefined-const|.} -@defproc[(centerline [pre-flow any/c] ...0) table?]{Produces a +@defproc[(centerline [pre-flow any/c] ...) table?]{Produces a centered table with the @scheme[pre-flow] parsed by @scheme[decode-flow].} -@defproc[(commandline [pre-content any/c] ...0) paragraph?]{Produces a +@defproc[(commandline [pre-content any/c] ...) paragraph?]{Produces an inset command-line example (e.g., in typewriter font).} diff --git a/collects/web-server/docs/reference/configuration.scrbl b/collects/web-server/docs/reference/configuration.scrbl index da6be15495..fe7cde6943 100644 --- a/collects/web-server/docs/reference/configuration.scrbl +++ b/collects/web-server/docs/reference/configuration.scrbl @@ -197,7 +197,7 @@ turn the paths given in the @scheme[configuration-table] into responders for the @; XXX Include response/full @; XXX Rename error-response -@defproc[(error-response (http-code natural-number/c) (short-version string?) (text-file string?) (extra-header (cons/c symbol? string?)) ...0) +@defproc[(error-response (http-code natural-number/c) (short-version string?) (text-file string?) (extra-header (cons/c symbol? string?)) ...) response?]{ Generates a @scheme[response/full] with the given @scheme[http-code] and @scheme[short-version] as the corresponding fields; with the content of the @scheme[text-file] as the body; and, with diff --git a/collects/web-server/docs/reference/dispatchers.scrbl b/collects/web-server/docs/reference/dispatchers.scrbl index 5675f41cb2..5ca6741377 100644 --- a/collects/web-server/docs/reference/dispatchers.scrbl +++ b/collects/web-server/docs/reference/dispatchers.scrbl @@ -79,7 +79,7 @@ URLs to paths on the filesystem. @file{dispatchers/dispatch-sequencer.ss} defines a dispatcher constructor that invokes a sequence of dispatchers until one applies. -@defproc[(make (dispatcher dispatcher?) ...0) +@defproc[(make (dispatcher dispatcher?) ...) dispatcher?]{ Invokes each @scheme[dispatcher], invoking the next if the first calls @scheme[next-dispatcher]. If no @scheme[dispatcher] applies,