From 970f0e381a96e720aa15f5b0d54506909dedaf02 Mon Sep 17 00:00:00 2001 From: Robby Findler Date: Fri, 28 Jun 2013 19:45:37 -0500 Subject: [PATCH] move mzlib docs to the compatility pkg original commit: acce2d27d13a0bb2fffd4a4a5b844a2395b874f0 --- .../mzlib/scribblings/awk.scrbl | 69 +++ .../mzlib/scribblings/cmdline.scrbl | 40 ++ .../mzlib/scribblings/cml.scrbl | 45 ++ .../mzlib/scribblings/common.rkt | 24 + .../mzlib/scribblings/compat.scrbl | 98 ++++ .../mzlib/scribblings/compile.scrbl | 34 ++ .../mzlib/scribblings/contract-label.rkt | 13 + .../mzlib/scribblings/contract.scrbl | 294 ++++++++++++ .../mzlib/scribblings/etc.scrbl | 274 +++++++++++ .../mzlib/scribblings/file.scrbl | 66 +++ .../mzlib/scribblings/for.scrbl | 47 ++ .../mzlib/scribblings/include.scrbl | 70 +++ .../mzlib/scribblings/info.rkt | 3 + .../mzlib/scribblings/integer-set.scrbl | 13 + .../mzlib/scribblings/kw.scrbl | 452 ++++++++++++++++++ .../mzlib/scribblings/list.scrbl | 77 +++ .../mzlib/scribblings/match-grammar.rkt | 49 ++ .../mzlib/scribblings/match.scrbl | 57 +++ .../mzlib/scribblings/math.scrbl | 13 + .../mzlib/scribblings/mzlib.scrbl | 382 +++++++++++++++ .../mzlib/scribblings/os.scrbl | 30 ++ .../mzlib/scribblings/pconvert-prop.scrbl | 49 ++ .../mzlib/scribblings/pconvert.scrbl | 262 ++++++++++ .../mzlib/scribblings/plt-match.scrbl | 18 + .../mzlib/scribblings/port.scrbl | 18 + .../mzlib/scribblings/pregexp.scrbl | 58 +++ .../mzlib/scribblings/restart.scrbl | 69 +++ .../mzlib/scribblings/sandbox.scrbl | 84 ++++ .../mzlib/scribblings/sendevent.scrbl | 29 ++ .../mzlib/scribblings/serialize.scrbl | 39 ++ .../mzlib/scribblings/string.scrbl | 118 +++++ .../mzlib/scribblings/struct.scrbl | 70 +++ .../mzlib/scribblings/thread.scrbl | 99 ++++ .../mzlib/scribblings/traceld.scrbl | 22 + .../mzlib/scribblings/transcr.scrbl | 22 + .../mzlib/scribblings/unit.scrbl | 57 +++ 36 files changed, 3164 insertions(+) create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/awk.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/cmdline.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/cml.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/common.rkt create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/compat.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/compile.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/contract-label.rkt create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/contract.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/etc.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/file.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/for.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/include.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/info.rkt create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/integer-set.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/kw.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/list.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/match-grammar.rkt create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/match.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/math.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/mzlib.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/os.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/pconvert-prop.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/pconvert.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/plt-match.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/port.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/pregexp.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/restart.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/sandbox.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/sendevent.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/serialize.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/string.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/struct.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/thread.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/traceld.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/transcr.scrbl create mode 100644 pkgs/compatibility-lib/mzlib/scribblings/unit.scrbl diff --git a/pkgs/compatibility-lib/mzlib/scribblings/awk.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/awk.scrbl new file mode 100644 index 0000000..aa2f0bc --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/awk.scrbl @@ -0,0 +1,69 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/awk + scheme/contract)) + +@mzlib[#:mode title awk] + +@defform/subs[ +#:literals (after range / => :range range: :range: else) +(awk next-record-expr + (record field-id ...) + maybe-counter + ((state-variable init-expr) ...) + maybe-continue + clause ...) +([maybe-counter code:blank + id] + [maybe-continue code:blank + id] + [clause (test body ...+) + (test => procedure-expr) + (/ regexp-str / (id-or-false ...+) body ...+) + (range excl-start-test excl-stop-test body ...+) + (:range incl-start-test excl-stop-test body ...+) + (range: excl-start-test incl-stop-test body ...+) + (:range: incl-start-test incl-stop-test body ...+) + (else body ...+) + (after body ...+)] + [test integer + regexp-string + expr] + [excl-start-test test] + [excl-stop-test test] + [incl-start-test test] + [incl-stop-test test] + [id-or-false id + #f])]{ + +The @racket[awk] macro from Scsh @cite["Shivers06"]. In addition to +@racket[awk], the Scsh-compatible procedures @racket[match:start], +@racket[match:end], @racket[match:substring], and @racket[regexp-exec] +are defined. These @racketidfont{match:} procedures must be used to +extract match information in a regular expression clause when using +the @racket[=>] form. } + +@deftogether[( +@defproc[(match:start [rec ....] + [which exact-nonnegative-integer? 0]) + exact-nonnegative-integer?] +@defproc[(match:end [rec ....] + [which exact-nonnegative-integer? 0]) + exact-nonnegative-integer?] +@defproc[(match:substring + [rec ....] + [which exact-nonnegative-integer? 0]) + string?] +)]{ + +Extracts a start position, end position, or substring corresponding to +a match. The first argument is the value supplied to the procedure +after @racket[=>] in a @racket[awk] clause or the result of +@racket[regexp-exec].} + + +@defproc[(regexp-exec [re (or/c string? regexp?)] [s string?]) + (or/c .... false/c)]{ + +Matches a regexp to a string, returning a record compatible with +@racket[match:start], etc.} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/cmdline.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/cmdline.scrbl new file mode 100644 index 0000000..622371a --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/cmdline.scrbl @@ -0,0 +1,40 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/cmdline)) + +@(define-syntax-rule (intro id) + (begin + (require (for-label racket/cmdline)) + (define id (racket command-line)))) +@(intro racket-command-line) + +@mzlib[#:mode title cmdline] + +@deprecated[@racketmodname[racket/cmdline]]{} + +Provides a @racket[command-line] from that is similar to the one in +@racketmodname[racket/cmdline], but without using keywords. The +@racket[parse-command-line] procedure from +@racketmodname[racket/cmdline] is re-exported directly. + +@defform/subs[ +#:literals (multi once-each once-any final help-labels args =>) +(command-line program-name-expr argv-expr clause ...) +([clause (multi flag-spec ...) + (once-each flag-spec ...) + (once-any flag-spec ...) + (final flag-spec ...) + (help-labels string ...) + (args arg-formals body-expr ...+) + (=> finish-proc-expr arg-help-expr help-proc-expr + unknown-proc-expr)] + [flag-spec (flags id ... help-str ...+ body-expr ...+) + (flags => handler-expr help-expr)] + [flags flag-string + (flag-string ...+)] + [arg-formals id + (id ...) + (id ...+ . id)])]{ + +Like @racket-command-line from @racket[racket/cmdline], but without +keywords in the syntax.} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/cml.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/cml.scrbl new file mode 100644 index 0000000..fcc46f6 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/cml.scrbl @@ -0,0 +1,45 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/cml)) + +@mzlib[#:mode title cml] + +The @racketmodname[mzlib/cml] library defines a number of procedures +that wrap Racket concurrency procedures. The wrapper procedures +have names and interfaces that more closely match those of Concurrent +ML @cite["Reppy99"]. + + +@defproc[(spawn [thunk (-> any)]) thread?]{ + +Equivalent to @racket[(thread/suspend-to-kill thunk)].} + + +@defproc[(channel) channel?]{ + +Equivalent to @racket[(make-channel)].} + + +@defproc[(channel-recv-evt [ch channel?]) evt?]{ + +Equivalent to @racket[ch].} + + +@defproc[(channel-send-evt [ch channel?][v any/c]) evt?]{ + +Equivalent to @racket[(channel-put-evt ch v)].} + + +@defproc[(thread-done-evt [thd thread?]) any]{ + +Equivalent to @racket[(thread-dead-evt thread)].} + + +@defproc[(current-time) real?]{ + +Equivalent to @racket[(current-inexact-milliseconds)].} + + +@defproc[(time-evt [tm real?]) evt?]{ + +Equivalent to @racket[(alarm-evt tm)].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/common.rkt b/pkgs/compatibility-lib/mzlib/scribblings/common.rkt new file mode 100644 index 0000000..713a2f1 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/common.rkt @@ -0,0 +1,24 @@ +#lang scheme/base + +(require (for-syntax scheme/base) + scribble/manual + (for-label mzscheme + (only-in scheme/base exn:fail exn:fail:unsupported exn:fail:contract))) + +(provide mzlib + (all-from-out scribble/manual) + (for-label (all-from-out mzscheme) + (all-from-out scheme/base))) + +(define-syntax (mzlib stx) + (syntax-case stx () + [(_ #:mode section name #:use-sources (src ...)) + (with-syntax ([lib (string->symbol + (format "mzlib/~a" (syntax-e #'name)))]) + #'(begin + (section #:style 'hidden (racket lib)) + (defmodule lib #:use-sources (src ...))))] + [(_ #:mode section name) + #'(mzlib #:mode section name #:use-sources ())] + [(_ name) + #'(mzlib #:mode section name #:use-sources ())])) diff --git a/pkgs/compatibility-lib/mzlib/scribblings/compat.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/compat.scrbl new file mode 100644 index 0000000..2514dfc --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/compat.scrbl @@ -0,0 +1,98 @@ +#lang scribble/doc +@(require "common.rkt" + scribble/eval + (for-label mzlib/compat)) + +@(define compat-eval (make-base-eval)) + +@interaction-eval[#:eval compat-eval (require mzlib/compat)] + +@mzlib[#:mode title compat] + +The @racketmodname[mzlib/compat] library defines a number of +procedures and syntactic forms that are commonly provided by other +Scheme implementations. Most of the procedures are aliases for +@racketmodname[mzscheme] procedures. + +@deftogether[( +@defproc[(=? [n number?] ...+) boolean?] +@defproc[(? [n real?] ...+) boolean?] +@defproc[(<=? [n real?] ...+) boolean?] +@defproc[(>=? [n real?] ...+) boolean?] +)]{ + +Same as @racket[=], @racket[<], etc.} + +@deftogether[( +@defproc[(1+ [n number?]) number?] +@defproc[(1- [n number?]) number?] +)]{ + +Same as @racket[add1] and @racket[sub1].} + + +@defproc[(gentmp [base (or/c string? symbol?) "g"]) symbol?]{ + +Same as @racket[gensym].} + + +@defproc[(flush-output-port [o output-port? (current-output-port)]) void?]{ + +Same as @racket[flush-output].} + +@defproc[(real-time) exact-integer?]{ + +Same as @racket[current-milliseconds].} + + +@defproc[(atom? [v any/c]) any]{ + +Same as @racket[(not (pair? v))] (which does not actually imply an +atomic value).} + + +@defform*[[(define-structure (name-id field-id ...)) + (define-structure (name-id field-id ...) + ((init-field-id init-expr) ...))]]{ + +Like @racket[define-struct], except that the @racket[name-id] is moved +inside the parenthesis for fields. In addition, +@racket[init-field-id]s can be specified with automatic initial-value +expression. + +The @racket[init-field-id]s do not have corresponding arguments for +the @racketidfont{make-}@racket[name-id] constructor. Instead, each +@racket[init-field-id]'s @racket[init-expr] is evaluated to obtain the +field's value when the constructor is called. The @racket[field-id]s +are bound in @racket[init-expr]s, but not other +@racket[init-field-id]s. + +@examples[ +#:eval compat-eval +(define-structure (add left right) ([sum (+ left right)])) +(add-sum (make-add 3 6)) +]} + +@deftogether[( +@defproc[(getprop [sym symbol?][property symbol?][default any/c #f]) any/c] +@defproc[(putprop [sym symbol?][property symbol?][value any/c]) void?] +)]{ + +The @racket[getprop] function gets a property value associated with +@racket[sym]. The @racket[property] argument names the property to be +found. If the property is not found, @racket[default] is returned. + +The properties obtained with @racket[getprop] are the ones installed +with @racket[putprop].} + + +@defproc[(new-cafe [eval-handler (any/c . -> . any) #f]) any]{ + +Emulates Chez Scheme's @racket[new-cafe] by installing +@racket[eval-handler] into the @racket[current-eval] parameter while +running @racket[read-eval-print]. In addition, @racket[current-exit] +is set to escape from the call to @racket[new-cafe].} + + +@close-eval[compat-eval] diff --git a/pkgs/compatibility-lib/mzlib/scribblings/compile.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/compile.scrbl new file mode 100644 index 0000000..572ba31 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/compile.scrbl @@ -0,0 +1,34 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/compile + compiler/compiler + compiler/cm)) + +@mzlib[#:mode title compile] + +@defproc[(compile-file [src path-string?] + [dest path-string? (let-values ([(base name dir?) (split-path src)]) + (build-path base "compiled" + (path-add-suffix name #".zo")))] + [filter (any/c . -> . any/c) values]) + path?]{ + +Compiles the Scheme file @racket[src] and saves the compiled code to +@racket[dest]. If @racket[dest] is not provided and the +@filepath{compiled} subdirectory does not already exist, the +subdirectory is created. The result of @racket[compile-file] is the +destination file's path. + +If the @racket[filter] procedure is provided, it is applied to each +source expression, and the result is compiled. + +The @racket[compile-file] procedure is designed for compiling modules +files, in that each expression in @racket[src] is compiled +independently. If @racket[src] does not contain a single +@racket[module] expression, then earlier expressions can affect the +compilation of later expressions when @racket[src] is loaded +directly. An appropriate @racket[filter] can make compilation behave +like evaluation, but the problem is also solved (as much as possible) +by the @racket[compile-zos] procedure. + +See also @racket[managed-compile-zo].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/contract-label.rkt b/pkgs/compatibility-lib/mzlib/scribblings/contract-label.rkt new file mode 100644 index 0000000..1e1df76 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/contract-label.rkt @@ -0,0 +1,13 @@ +#lang racket/base +(require (for-label racket/contract) + scribble/manual) +(provide (all-defined-out)) + +;; this file establishes the right for-label +;; bindings so that I can link to racket/contract +;; combinators in the mzlib/contract docs + +(define r:-> (racket ->)) +(define r:->* (racket ->*)) +(define r:->i (racket ->i)) +(define r:->d (racket ->d)) diff --git a/pkgs/compatibility-lib/mzlib/scribblings/contract.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/contract.scrbl new file mode 100644 index 0000000..6709fa6 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/contract.scrbl @@ -0,0 +1,294 @@ +#lang scribble/doc +@(require "common.rkt" + scribble/struct + "contract-label.rkt" + (for-label mzlib/contract) + (for-label (prefix-in r: racket/contract))) + +@(define-syntax-rule (twocolumns id ...) + (*twocolumns (list (racket id) ...))) +@(define (*twocolumns uneven-l) + (let* ([l (if (zero? (modulo (length uneven-l) 2)) uneven-l (append uneven-l (list #f)))] + [len (length l)] + [half (quotient len 2)] + [a (for/list ([i (in-range half)] + [e l]) + e)] + [b (list-tail l half)] + [spacer (hspace 2)] + [to-flow (compose make-flow list make-paragraph list)]) + (make-table #f + (map (lambda (a b) + (list (to-flow spacer) + (to-flow a) + (to-flow spacer) + (to-flow (or b "")))) + a b)))) + +@mzlib[#:mode title contract] + +@deprecated[@racketmodname[racket/contract]]{ + This library is designed as a backwards compatible library + for old uses of contracts. It should not be used for new + libraries. +} + +The main differences: the function contract syntax is more +regular and function contracts now support keywords, and +@tt{union} is now @racket[or/c]. + +The @racketmodname[mzlib/contract] library re-exports many bindings +from @racketmodname[racket/contract]: + +@twocolumns[ + /c + >=/c + and/c + any + any/c + between/c + box-immutable/c + build-compound-type-name + coerce-contract + cons/c + contract + contract-first-order-passes? + contract-violation->string + contract? + define-contract-struct + false/c + flat-contract + flat-contract-predicate + flat-contract? + flat-murec-contract + flat-named-contract + flat-rec-contract + guilty-party + integer-in + list/c + listof + make-none/c + make-proj-contract + natural-number/c + none/c + not/c + one-of/c + or/c + parameter/c + printable/c + promise/c + provide/contract + raise-contract-error + real-in + recursive-contract + string/len + symbols + syntax/c + vector-immutable/c + vector-immutableof] + +It also provides the old version of the following contracts: + +@defform[(define/contract id contract-expr init-value-expr)]{ + +Attaches the contract @racket[contract-expr] to +@racket[init-value-expr] and binds that to @racket[id]. + +The @racket[define/contract] form treats individual definitions as +units of blame. The definition itself is responsible for positive +(co-variant) positions of the contract and each reference to +@racket[id] (including those in the initial value expression) must +meet the negative positions of the contract. + +Error messages with @racket[define/contract] are not as clear as those +provided by @racket[provide/contract], because +@racket[define/contract] cannot detect the name of the definition +where the reference to the defined variable occurs. Instead, it uses +the source location of the reference to the variable as the name of +that definition.} + +@defproc[(box/c [c flat-contract?]) flat-contract?]{ + +Returns a flat contract that recognizes boxes. The content of the box +must match @racket[c].} + +@defproc[(vectorof [c flat-contract?]) flat-contract?]{ + +Accepts a flat contract and returns a flat contract +that checks for vectors whose elements match the original contract.} + +@defproc[(vector/c [c flat-contract?] ...) flat-contract?]{ + +Accepts any number of flat contracts and returns a +flat contract that recognizes vectors. The number of elements in the +vector must match the number of arguments supplied to +@racket[vector/c], and each element of the vector must match the +corresponding flat contract.} + +@defform[(struct/c struct-id flat-contract-expr ...)]{ + +Produces a flat contract that recognizes instances of the structure +type named by @racket[struct-id], and whose field values match the +flat contracts produced by the @racket[flat-contract-expr]s.} + +@defproc[(build-flat-contract [name symbol?] [predicate (-> any/c any)]) flat-contract?]{ + Builds a flat contract out of @racket[predicate], giving it the name + @racket[name]. Nowadays, just using @racket[predicate] directly is preferred. +} + +@defform*[((-> contract-dom-expr ... any) + (-> contract-dom-expr ... contract-rng-expr))]{ +This is a restricted form of @racketmodname[racket/contract]'s + @r:-> contract that does not + handle keyword arguments or multiple + value results. + +} + +@defform*/subs[((->* (contract-dom-expr ...) ->*rng) + (->* (contract-dom-expr ...) contract-rest-expr ->*rng)) + ([->*rng (contract-rng-expr ...) + any])]{ + The @racket[->*] form matches up to + @racketmodname[racket/contract]'s @r:-> and @r:->*, according + to the following rules; each equation on the + left refers to a @racketmodname[mzlib/contract] combinator; + on the right are the @racketmodname[racket/contract] equivalents. + @racketblock[(->* (contract-dom-expr ...) any) = + (#,r:-> contract-dom-expr ... any)] + @racketblock[(->* (contract-dom-expr ...) (contract-rng-expr ...)) = + (#,r:-> contract-dom-expr ... (values contract-rng-expr))] + @racketblock[(->* (contract-expr ...) contract-rest-expr any) = + (#,r:->* (contract-expr ...) #:rest contract-rest-expr any)] + @racketblock[(->* (contract-expr ...) contract-rest-expr (contract-rng-expr ...)) = + (#,r:->* (contract-expr ...) + #:rest contract-rest-expr + (values contract-rng-expr ...))] + +} + +@defform*[((opt-> (contract-req-expr ...) (contact-opt-expr ...) any) + (opt-> (contract-req-expr ...) (contact-opt-expr ...) contract-rng-expr))]{ + + The @racket[opt->] form is a simplified verison of @racketmodname[racket/contract]'s + @|r:->*| and appearances of @racket[opt->] can be simply replaced with @|r:->*|. + +} + +@defform*[((opt->* (contract-req-expr ...) (contact-opt-expr ...) any) + (opt->* (contract-req-expr ...) (contact-opt-expr ...) (contract-rng-expr ...)))]{ + + The @racket[opt->*] form matches up to + @racketmodname[racket/contract]'s @r:->*, according + to the following rules; each equation on the + left refers to a @racketmodname[mzlib/contract] combinator; + on the right are the @racketmodname[racket/contract] equivalents. + + @racketblock[(opt->* (contract-req-expr ...) (contract-opt-expr ...) any) = + (#,r:->* (contract-req-expr ...) (contract-opt-expr ...) any)] + + @racketblock[(opt->* (contract-req-expr ...) + (contract-opt-expr ...) + (contract-rng-expr ...)) = + (#,r:->* (contract-req-expr ...) + (contract-opt-expr ...) + (values contract-rng-expr ...))] +} + +@defform[(->d contract-dom-expr ... contract-rng-fun-expr)]{ + The @racket[->d] contract constructor is just like @racket[->], + except that the range position is expected to be a function + that accepts the actual arguments passed to the function, + and returns a contract for the range. For example, this + is one contract for @racket[sqrt]: + @racketblock[(->d real? + (λ (in) + (and/c real? + (λ (out) + (< (abs (- (sqr out) in)) + 0.01)))))] + It says that the input must be a real number, and so must the + result, and that the square of the result is within + @racket[0.01] of input. + +} + +@defform*[((->d* (contract-dom-expr ...) contract-rng-fun-expr) + (->d* (contract-dom-expr ...) contract-rest-expr contract-rng-fun-expr))]{ + The @racket[->d*] contract constructor is a generalization of + @racket[->d] to support multiple values and rest arguments. + + In the two sub-expression case, the first sequence of contracts + are contracts on the domain of the function and the second + subexpression is expected to evaluate to a function that accepts + as many arguments as there are expressions in the first position. + It should return multiple values: one contract for each result + of the function. + + In the three sub-expression case, the first and last subexpressions + are just like the sub-expressions in the two sub-expression case; + the middle sub-expression si expected to evaluate to a contract on + the rest argument. + +} + +@defform*/subs[((->r ([dom-x contract-dom-expr] ...) rng) + (->r ([dom-x contract-dom-expr] ...) rest-x contract-rest-expr rng)) + ((rng any + (values contract-expr ...) + contract-expr))]{ + + The @racket[->r] form is a simplified version of @racketmodname[racket/contract]'s @|r:->i|, where + each @racket[contract-dom-expr] is parameterized over all of the @racket[dom-x] variables + (and does lax checking; see @r:->d for details). + +} + +@defform*[((->pp ([dom-x contract-dom-expr] ...) pre-cond-expr any) + (->pp ([dom-x contract-dom-expr] ...) + pre-cond-expr + (values [rng-x contract-rng-expr] ...) + post-cond-expr) + (->pp ([dom-x contract-dom-expr] ...) + pre-cond-expr + contract-rng-expr + rng-x + post-cond-expr))]{ + + The @racket[->pp] form, like @racket[->r] is a simplified version of @racketmodname[racket/contract]'s @|r:->i|, where + each @racket[contract-dom-expr] is parameterized over all of the @racket[dom-x] variables + (and does lax checking; see @racketmodname[racket/contract]'s @r:->d for details). Unlike @racket[->r], it also has pre- and post-condition + expressions; these expressions are also implicitly parameterized over all of the @racket[dom-x] + variables and the post-condition is also paramterized over @racket[rng-x], which is bound to the result + of the function. + +} + +@defform*[((->pp-rest ([dom-x contract-dom-expr] ...) rest-x rest-contract-expr pre-cond-expr any) + (->pp-rest ([dom-x contract-dom-expr] ...) + rest-x rest-contract-expr + pre-cond-expr + (values [rng-x contract-rng-expr] ...) + post-cond-expr) + (->pp-rest ([dom-x contract-dom-expr] ...) + rest-x rest-contract-expr + pre-cond-expr + contract-rng-expr + rng-x + post-cond-expr))]{ + Like @racket[->pp], but with an additional contract for the rest arguments of the function. +} + +@defform[(case-> mzlib/contract-arrow-contract-expr ...)]{ + Builds a contract analogous to @racket[case-lambda], + where each case comes from one of the contract expression arguments + (tried in order). +} + +@defform[(object-contract [id mzlib/contract-arrow-contract-expr] ...)]{ + Builds a contract for objects where each @racket[id] is expected to be + a method on the object living up to the corresponding contract +} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/etc.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/etc.scrbl new file mode 100644 index 0000000..704eb7f --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/etc.scrbl @@ -0,0 +1,274 @@ +#lang scribble/doc +@(require "common.rkt" + scribble/eval + (for-label mzlib/etc + scheme/bool + scheme/local + setup/dirs + racket/block + (only-in scheme build-list build-string build-vector + symbol=?))) + +@(define etc-eval (make-base-eval)) +@interaction-eval[#:eval etc-eval (require mzlib/etc)] + +@(begin + (define-syntax-rule (bind id else-id) + (begin + (require (for-label scheme/base)) + (define id (racket lambda)) + (define else-id (racket else)))) + (bind base-lambda base-else)) + +@mzlib[#:mode title etc] + +The @racketmodname[mzlib/etc] library re-exports the following from +@racketmodname[scheme/base] and other libraries: + +@racketblock[ + boolean=? + true + false + build-list + build-string + build-vector + compose + local + symbol=? + nand + nor +] + +@defform[(begin-lifted expr ...+)] + +Lifts the @racket[expr]s so that they are evaluated once at the ``top +level'' of the current context, and the result of the last +@racket[expr] is used for every evaluation of the +@racket[begin-lifted] form. + +When this form is used as a run-time expression within a module, the +``top level'' corresponds to the module's top level, so that each +@racket[expr] is evaluated once for each invocation of the +module. When it is used as a run-time expression outside of a module, +the ``top level'' corresponds to the true top level. When this form is +used in a @racket[define-syntax], @racket[letrec-syntax], +etc. binding, the ``top level'' corresponds to the beginning of the +binding's right-hand side. Other forms may redefine ``top level'' +(using @racket[local-expand/capture-lifts]) for the expressions that +they enclose. + +@defform[(begin-with-definitions defn-or-expr ...)]{ + +The same as @racket[(block defn-or-expr ...)].} + +@defform[(define-syntax-set (id ...) defn ...)]{ + +Similar to @racket[define-syntaxes], but instead of a single body +expression, a sequence of definitions follows the sequence of defined +identifiers. For each @racket[identifier], the @racket[defn]s should +include a definition for @racket[id]@racketidfont{/proc}. The value +for @racket[id]@racketidfont{/proc} is used as the (expansion-time) +value for @racket[id]. + +The @racket[define-syntax-set] form is useful for defining a set of +syntax transformers that share helper functions, though +@racket[begin-for-syntax] now serves essentially the same purposes. + +@as-examples[ +@racketblock[ +(define-syntax-set (let-current-continuation + let-current-escape-continuation) + (define (mk call-id) + (lambda (stx) + (syntax-case stx () + [(_ id body1 body ...) + (with-syntax ([call call-id]) + (syntax (call (lambda (id) body1 body ...))))]))) + (define let-current-continuation/proc + (mk (quote-syntax call/cc))) + (define let-current-escape-continuation/proc + (mk (quote-syntax call/ec)))) +]]} + + +@defform*[#:literals (else) + [(evcase key-expr (value-expr body-expr ...) ...+) + (evcase key-expr (value-expr body-expr ...) ... [else body-expr ...])]]{ + +The @racket[evcase] form is similar to @racket[case], except that +expressions are provided in each clause instead of a sequence of +data. After @racket[key-expr] is evaluated, each @racket[value-expr] +is evaluated until a value is found that is @racket[eqv?] to the key +value; when a matching value is found, the corresponding +@racket[body-expr]s are evaluated and the value(s) for the last is the +result of the entire @racket[evcase] expression. + +The @racket[else] literal is recognized either as unbound (like in the +@racketmodname[mzscheme] language) or bound as @|base-else| from +@racketmodname[scheme/base].} + + +@defproc[(identity [v any/c]) any/c]{ + +Returns @racket[v].} + + +@defform/subs[#:literals (val rec vals recs _ values) + (let+ clause body-expr ...+) + ([clause (val target expr) + (rec target expr) + (vals (target ...) expr) + (recs (target expr) ...) + (_ expr ...)] + [target id + (values id ...)])]{ + +A binding construct that specifies scoping on a per-binding basis +instead of a per-expression basis. It helps eliminate rightward-drift +in programs. It looks similar to @racket[let], except each clause has +an additional keyword tag before the binding variables. + +Each @racket[clause] has one of the following forms: + +@itemize[ + + @item{@racket[(val target expr)] : Binds @racket[target] + non-recursively to @racket[expr].} + + @item{@racket[(rec target expr)] : Binds @racket[target] recursively to + @racket[expr].} + + @item{@racket[(vals (target expr) ...)] : The @racket[target]s are + bound to the @racket[expr]s. The environment of the @racket[expr]s is + the environment active before this clause.} + + @item{@racket[(recs (target expr) ...)] : The @racket[targets]s are + bound to the @racket[expr]s. The environment of the @racket[expr]s + includes all of the @racket[targets]s.} + + @item{@racket[(_ expr ...)] : Evaluates the @racket[expr]s without + binding any variables.} + +] + +The clauses bind left-to-right. When a @racket[target] is +@racket[(values id ...)], multiple values returned by the +corresponding expression are bound to the multiple variables. + +@examples[ +#:eval etc-eval +(let+ ([val (values x y) (values 1 2)]) + (list x y)) + +(let ([x 1]) + (let+ ([val x 3] + [val y x]) + y)) +]} + + +@defproc[(loop-until [start any/c] [done? (any/c . -> . any)] + [next (any/c . -> . any/c)] + [f (any/c . -> . any)]) + void?]{ + +Repeatedly invokes the @racket[f] procedure until the @racket[done?] +procedure returns @racket[#t]: + +@racketblock[ + (define (loop-until start done? next f) + (let loop ([i start]) + (unless (done? i) + (f i) + (loop (next i))))) +]} + + +@defproc[(namespace-defined? [sym symbol?]) boolean?]{ + +Returns @racket[#t] if @racket[namespace-variable-value] would return +a value for @racket[sym], @racket[#f] otherwise.} + + +@defform[(nand expr ...)]{ + +Same as @racket[(not (and expr ...))].} + + +@defform[(nor expr ...)]{ + +Same as @racket[(not (or expr ...))].} + + +@defform[(opt-lambda formals body ...+)]{ + +Supports optional (but not keyword) arguments like @base-lambda from +@racket[scheme/base].} + + +@defform[(recur id bindings body ...+)]{ + +Equivalent to @racket[(let id bindings body ...+)].} + + +@defform*[[(rec id value-expr) + (rec (id arg-id ...) expr) + (rec (id arg-id ... . rest-id) expr)]]{ + +Equivalent, respectively, to + +@racketblock[ + (letrec ([id value-expr]) id) + (letrec ([id (lambda (arg-id ...) value-expr)]) id) + (letrec ([id (lambda (arg-id ... . rest-id) value-expr)]) id) +]} + + +@defform*[[(this-expression-source-directory) + (this-expression-source-directory datum)]]{ + +@margin-note{See @racketmodname[scheme/runtime-path] for a definition form +that works better when creating executables.} + +Expands to an expression that evaluates to the directory of the file +containing the source @racket[datum]. If @racket[datum] is not +supplied, then the entire @racket[(this-expression-source-directory)] +expression is used as @racket[datum]. + +If @racket[datum] has a source module, then the expansion attempts to +determine the module's run-time location. This location is determined +by preserving the lexical context of @racket[datum] in a syntax +object, extracting its source module path at run time, and then +resolving the module path. + +Otherwise, @racket[datum]'s source file is determined through source +location information associated with @racket[datum], if it is +present. As a last resort, @racket[current-load-relative-directory] is +used if it is not @racket[#f], and @racket[current-directory] is used +if all else fails. + +A directory path derived from source location is always stored in +bytes in the expanded code, unless the file is within the result of +@racket[find-collects-dir], in which case the expansion records the +path relative to @racket[(find-collects-dir)] and then reconstructs it +using @racket[(find-collects-dir)] at run time.} + + +@defform*[[(this-expression-file-name) + (this-expression-file-name datum)]]{ + +Similar to @racket[this-expression-source-directory], except that only +source information associated with @racket[datum] or +@racket[(this-expression-file-name)] is used to extract a filename. If +no filename is available, the result is @racket[#f].} + + +@defform[#:literals (quote unsyntax scheme) + (hash-table (#,(racket quote) flag) ... (key-expr val-expr) ...)]{ + +Creates a new hash-table providing the quoted flags (if any) to +@racket[make-hash-table], and then mapping each key to the +corresponding values.} + + +@close-eval[etc-eval] diff --git a/pkgs/compatibility-lib/mzlib/scribblings/file.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/file.scrbl new file mode 100644 index 0000000..847df9f --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/file.scrbl @@ -0,0 +1,66 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/file + scheme/contract)) + + +@mzlib[#:mode title file] + +@deprecated[@racketmodname[racket/file]]{} + +The @racketmodname[mzlib/file] library mostly re-exports from +@racketmodname[scheme/file]: + +@racketblock[ +find-relative-path +explode-path +normalize-path +filename-extension +file-name-from-path +path-only +delete-directory/files +copy-directory/files +make-directory* +make-temporary-file +get-preference +put-preferences +fold-files +find-files +pathlist-closure +] + +@deftogether[( +@defproc[(call-with-input-file* [file path-string?] + [proc (input-port? -> any)] + [mode (one-of/c 'text 'binary) 'binary]) + any] +@defproc[(call-with-output-file* [file path-string?] + [proc (output-port? -> any)] + [mode (one-of/c 'text 'binary) 'binary] + [exists (one-of/c 'error 'append 'update + 'replace 'truncate 'truncate/replace) 'error]) + any] +)]{ + +Like @racket[call-with-input-file]and @racket[call-with-output-file], +except that the opened port is closed if control escapes from the body +of @racket[proc].} + +@deftogether[( +@defproc[(build-relative-path [base (or/c path-string? + (one-of/c 'up 'same))] + [sub (or/c (and/c path-string? + relative-path?) + (one-of/c 'up 'same))] ...) + (and/c path? relative-path?)] +@defproc[(build-absolute-path [base (or/c (and/c path-string? + (not/c relative-path?)) + (one-of/c 'up 'same))] + [sub (or/c (and/c path-string? + (not/c complete-path?)) + (one-of/c 'up 'same))] ...) + (and/c path? absolute-path?)] +)]{ + +Like @racket[build-path], but with extra constraints to ensure a +relative or absolute result.} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/for.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/for.scrbl new file mode 100644 index 0000000..5f6500e --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/for.scrbl @@ -0,0 +1,47 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/for)) + +@mzlib[#:mode title for] + +@deprecated[@racketmodname[racket/base]]{} + +The @racketmodname[mzlib/for] library re-exports from +@racketmodname[scheme/base]: + +@racketblock[ +for/fold for*/fold +for for* +for/list for*/list +for/lists for*/lists +for/and for*/and +for/or for*/or +for/first for*/first +for/last for*/last + +for/fold/derived for*/fold/derived + +in-range +in-naturals +in-list +in-vector +in-string +in-bytes +in-input-port-bytes +in-input-port-chars +in-hash-table +in-hash-table-keys +in-hash-table-values +in-hash-table-pairs + +in-parallel +stop-before +stop-after +in-indexed + +sequence? +sequence-generate + +define-sequence-syntax +make-do-sequence +:do-in] diff --git a/pkgs/compatibility-lib/mzlib/scribblings/include.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/include.scrbl new file mode 100644 index 0000000..631d067 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/include.scrbl @@ -0,0 +1,70 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/include)) + +@mzlib[#:mode title include] + +@deprecated[@racketmodname[racket/include]]{} + +Similar to @racketmodname[scheme/include], but with a different syntax +for paths. + +@defform/subs[#:literals (build-path lib up same) + (include path-spec) + ([path-spec string + (build-path elem ...+) + (lib file-string collection-string ...)] + [elem string + up + same])]{ + +Inlines the syntax in the designated file in place of the +@racket[include] expression. The @racket[path-spec] can be any of the +following: + +@itemize[ + + @item{A literal string that specifies a path to include, parsed + according to the platform's conventions (which means that it is + not portable).} + + @item{A path construction of the form @racket[(build-path elem + ...+)], where @racket[build-path] is + @racket[module-identifier=?] either to the @racket[build-path] + export from @racket[mzscheme] or to the top-level + @racket[build-path], and where each @racket[elem] is a path + string, @racket[up] (unquoted), or @racket[same] (unquoted). + The @racket[elem]s are combined in the same way as for the + @racket[build-path] function to obtain the path to include.} + + @item{A path construction of the form @racket[(lib file-string + collection-string ...)], where @racket[lib] is free or refers + to a top-level @racket[lib] variable. The + @racket[collection-string]s are passed to + @racket[collection-path] to obtain a directory; if no + @racket[collection-strings]s are supplied, @racket["mzlib"] is + used. The @racket[file-string] is then appended to the + directory using @racket[build-path] to obtain the path to + include.} + +] + +If @racket[path-spec] specifies a relative path to include, the path +is resolved relative to the source for the @racket[include] +expression, if that source is a complete path string. If the source is +not a complete path string, then @racket[path-spec] is resolved +relative to the current load relative directory if one is available, +or to the current directory otherwise. + +The included syntax is given the lexical context of the +@racket[include] expression.} + +@deftogether[( +@defform[(include-at/relative-to context source path-spec)] +@defform[(include-at/relative-to/reader context source path-spec reader-expr)] +@defform[(include/reader path-spec reader-expr)] +)]{ + +Variants of @racket[include] analogous to the variants of +@racketmodname[scheme/include].} + diff --git a/pkgs/compatibility-lib/mzlib/scribblings/info.rkt b/pkgs/compatibility-lib/mzlib/scribblings/info.rkt new file mode 100644 index 0000000..8391d74 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/info.rkt @@ -0,0 +1,3 @@ +#lang setup/infotab + +(define scribblings '(("mzlib.scrbl" (multi-page) (legacy)))) diff --git a/pkgs/compatibility-lib/mzlib/scribblings/integer-set.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/integer-set.scrbl new file mode 100644 index 0000000..c569f3b --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/integer-set.scrbl @@ -0,0 +1,13 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label data/integer-set + mzlib/integer-set)) + +@mzlib[#:mode title integer-set] + +@deprecated[@racketmodname[data/integer-set]]{} + +The @racketmodname[mzlib/integer-set] library re-exports bindings +from @racketmodname[data/integer-set] except that it renames +@racket[symmetric-difference] to @racket[xor], @racket[subtract] +to @racket[difference], and @racket[count] to @racket[card]. diff --git a/pkgs/compatibility-lib/mzlib/scribblings/kw.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/kw.scrbl new file mode 100644 index 0000000..f72cf73 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/kw.scrbl @@ -0,0 +1,452 @@ +#lang scribble/doc +@(require "common.rkt" + scribble/eval + (for-label mzlib/kw + mzlib/etc)) + +@(define kw-eval (make-base-eval)) + +@interaction-eval[#:eval kw-eval (require mzscheme)] +@interaction-eval[#:eval kw-eval (require mzlib/kw)] + +@(begin + (define-syntax-rule (bind id) + (begin + (require (for-label scheme/base)) + (define id (racket lambda)))) + (bind base-lambda)) + +@mzlib[#:mode title kw] + +@deprecated[@racketmodname[racket/base]]{The Racket base language +supports keyword arguments. Using the built-in keyword arguments +in Racket is highly recommended.} + +@margin-note{The @base-lambda and procedure-application forms of + @racket[scheme/base] support keyword arguments, and it is + @emph{not} compatible with the @racket[mzlib/kw] + library.} + +@deftogether[( +@defform[(lambda/kw kw-formals body ...+)] +@defform/subs[ +(define/kw (head args) body ...+) +([kw-formals id + (id ... [#:optional optional-spec ...] + [#:key key-spec ...] + [rest/mode-spec ...]) + (id ... . id)] + [optional-spec id + (id default-expr)] + [key-spec id + (id default-expr) + (id keyword default-expr)] + [rest/mode-spec (code:line #:rest id) + (code:line #:other-keys id) + (code:line #:other-keys+body id) + (code:line #:all-keys id) + (code:line #:body kw-formals) + (code:line #:allow-other-keys) + (code:line #:forbid-other-keys) + (code:line #:allow-duplicate-keys) + (code:line #:forbid-duplicate-keys) + (code:line #:allow-body) + (code:line #:forbid-body) + (code:line #:allow-anything) + (code:line #:forbid-anything)] + [head id + (head . kw-formals)]) +])]{ + +Like @racket[lambda], but with optional and keyword-based argument +processing. This form is similar to an extended version of Common +Lisp procedure arguments (but note the differences below). When used +with plain variable names, @racket[lambda/kw] expands to a plain +@racket[lambda], so @racket[lambda/kw] is suitable for a language +module that will use it to replace @racket[lambda]. Also, when used +with only optionals, the resulting procedure is similar to +@racket[opt-lambda] (but a bit faster). + +In addition to @racket[lambda/kw], @racket[define/kw] is similar to +@racket[define], except that the @racket[formals] are as in +@racket[lambda/kw]. Like @racket[define], this form can be used with +nested parenthesis for curried functions (the MIT-style generalization +of @racket[define]). + +The syntax of @racket[lambda/kw] is the same as @racket[lambda], +except for the list of formal argument specifications. These +specifications can hold (zero or more) plain argument names, then an +optionals (and defaults) section that begins after an +@racket[#:optional] marker, then a keyword section that is marked by +@racket[#:keyword], and finally a section holding rest and +``rest''-like arguments which are described below, together with +argument processing flag directives. Each section is optional, but +the order of the sections must be as listed. Of course, all binding +@racket[id]s must be unique. + +The following sections describe each part of the @racket[kw-formals].} + +@; ---------------------------------------- + +@section{Required Arguments} + +Required arguments correspond to @racket[id]s that appear before any +keyword marker in the argument list. They determine the minimum arity +of the resulting procedure. + +@; ---------------------------------------- + +@section{Optional Arguments} + +The optional-arguments section follows an +@as-index{@racket[#:optional]} marker in the @racket[_kw-formals]. +Each optional argument can take the form of a parenthesized variable +and a default expression; the latter is used if a value is not given +at the call site. The default expression can be omitted (along with +the parentheses), in which case @racket[#f] is the default. + +The default expression's environment includes all previous arguments, +both required and optional names. With @math{k} optionals after +@math{n} required arguments, and with no keyword arguments or +rest-like arguments, the resulting procedure accept between @math{n} +and @math{n+k} arguments, inclusive. + +The treatment of optionals is efficient, with an important caveat: +default expressions appear multiple times in the resulting +@racket[case-lambda]. For example, the default expression for the last +optional argument appears @math{k-1} times (but no expression is ever +evaluated more than once in a procedure call). This expansion risks +exponential blow-up is if @racket[lambda/kw] is used in a default +expression of a @racket[lambda/kw], etc. The bottom line, however, is +that @racket[lambda/kw] is a sensible choice, due to its enhanced +efficiency, even when you need only optional arguments. + +Using both optional and keyword arguments is possible, but note that +the resulting behavior differs from traditional keyword facilities +(including the one in Common Lisp). See the following section for +details. + +@; ---------------------------------------- + +@section{Keyword Arguments} + +A keyword argument section is marked by a @as-index{@racket[#:key]}. +If it is used with optional arguments, then the keyword specifications +must follow the optional arguments (which mirrors the use in call +sites; where optionals are given before keywords). + +When a procedure accepts both optional and keyword arguments, the +argument-handling convention is slightly different than in traditional +keyword-argument facilities: a keyword after required arguments marks +the beginning of keyword arguments, no matter how many optional +arguments have been provided before the keyword. This convention +restricts the procedure's non-keyword optional arguments to +non-keyword values, but it also avoids confusion when mixing optional +arguments and keywords. For example, when a procedure that takes two +optional arguments and a keyword argument @racket[#:x] is called with +@racket[#:x 1], then the optional arguments get their default values +and the keyword argument is bound to @racket[1]. (The traditional +behavior would bind @racket[#:x] and @racket[1] to the two optional +arguments.) When the same procedure is called with @racket[1 #:x 2], +the first optional argument is bound to @racket[1], the second +optional argument is bound to its default, and the keyword argument is +bound to @racket[2]. (The traditional behavior would report an error, +because @racket[2] is provided where @racket[#:x] is expected.) + +Like optional arguments, each keyword argument is specified as a +parenthesized variable name and a default expression. The default +expression can be omitted (with the parentheses), in which case +@racket[#f] is the default value. The keyword used at a call site for +the corresponding variable has the same name as the variable; a third +form of keyword arguments has three parts---a variable name, a +keyword, and a default expression---to allow the name of the locally +bound variable to differ from the keyword used at call sites. + +When calling a procedure with keyword arguments, the required argument +(and all optional arguments, if specified) must be followed by an even +number of arguments, where the first argument is a keyword that +determines which variable should get the following value, etc. If the +same keyword appears multiple times (and if multiple instances of the +keyword are allowed; see @secref["mode-keywords"]), the value after +the first occurrence is used for the variable: + +@examples[ +#:eval kw-eval +((lambda/kw (#:key x [y 2] [z #:zz 3] #:allow-duplicate-keys) + (list x y z)) + #:x 'x #:zz 'z #:x "foo") +] + +Default expressions are evaluated only for keyword arguments that do +not receive a value for a particular call. Like optional arguments, +each default expression is evaluated in an environment that includes +all previous bindings (required, optional, and keywords that were +specified on its left). + +See @secref["mode-keywords"] for information on when duplicate or +unknown keywords are allowed at a call site. + +@; ---------------------------------------- + +@section{Rest and Rest-like Arguments} + +The last @racket[_kw-formals] section---after the required, optional, +and keyword arguments---may contain specifications for rest-like +arguments and/or mode keywords. Up to five rest-like arguments can be +declared, each with an @racket[_id] to bind: + +@itemize[ + + @item{@as-index{@racket[#:rest]} --- The variable is bound to the + list of ``rest'' arguments, which is the list of all values after + the required and the optional values. This list includes all + keyword-value pairs, exactly as they are specified at the call site. + + Scheme's usual dot-notation is accepted in @racket[_kw-formals] only + if no other meta-keywords are specified, since it is not clear + whether it should specify the same binding as a @racket[#:rest] or + as a @racket[#:body]. The dot notation is allowed without + meta-keywords to make the @racket[lambda/kw] syntax compatible with + @racket[lambda].} + + @item{@as-index{@racket[#:body]} --- The variable is bound to all + arguments after keyword--value pairs. (This is different from + Common Lisp's @racket[&body], which is a synonym for + @racket[&rest].) More generally, a @racket[#:body] specification + can be followed by another @racket[_kw-formals], not just a single + @racket[_id]; see @secref["kw-body"] for more information.} + + @item{@as-index{@racket[#:all-keys]} --- the variable is bound to the + list of all keyword-values from the call site, which is always a + proper prefix of a @racket[#:rest] argument. (If no @racket[#:body] + arguments are declared, then @racket[#:all-keys] binds the same as + @racket[#:rest].) See also @racket[keyword-get].} + + @item{@racket[#:other-keys] --- The variable is bound like an + @racket[#:all-keys] variable, except that all keywords specified in + the @racket[kw-formals] are removed from the list. When a keyword + is used multiple times at a call cite (and this is allowed), only + the first instances is removed for the @racket[#:other-keys] + binding.} + + @item{@racket[#:other-keys+body] --- the variable is bound like a + @racket[#:rest] variable, except that all keywords specified in the + @racket[_kw-formals] are removed from the list. When a keyword is + used multiple times at a call site (and this is allowed), only the + first instance us removed for the @racket[#:other-keys+body] + binding. (When no @racket[#:body] variables are specified, then + @racket[#:other-keys+body] is the same as @racket[#:other-keys].)} + +] + +In the following example, all rest-like arguments are used and have different +bindings: + +@examples[ +#:eval kw-eval +((lambda/kw (#:key x y + #:rest r + #:other-keys+body rk + #:all-keys ak + #:other-keys ok + #:body b) + (list r rk b ak ok)) + #:z 1 #:x 2 2 3 4) +] + +Note that the following invariants always hold: + +@itemize[ +@item{@racket[_rest] = @racket[(append _all-keys _body)]} +@item{@racket[_other-keys+body] = @racket[(append _other-keys _body)]} +] + +To write a procedure that uses a few keyword argument values, and that +also calls another procedure with the same list of arguments +(including all keywords), use @racket[#:other-keys] (or +@racket[#:other-keys+body]). The Common Lisp approach is to specify +@racket[:allow-other-keys], so that the second procedure call will not +cause an error due to unknown keywords, but the +@racket[:allow-other-keys] approach risks confusing the two layers of +keywords. + +@; ---------------------------------------- + +@section[#:tag "kw-body"]{Body Argument} + +The most notable divergence from Common Lisp in @racket[lambda/kw] is +the @racket[#:body] argument, and the fact that it is possible at a +call site to pass plain values after the keyword-value pairs. The +@racket[#:body] binding is useful for procedure calls that use +keyword-value pairs as sort of an attribute list before the actual +arguments to the procedure. For example, consider a procedure that +accepts any number of numeric arguments and will apply a procedure to +them, but the procedure can be specified as an optional keyword +argument. It is easily implemented with a @racket[#:body] argument: + +@examples[ +#:eval kw-eval +(define/kw (mathop #:key [op +] #:body b) + (apply op b)) +(mathop 1 2 3) +(mathop #:op max 1 2 3) +] + +(Note that the first body value cannot itself be a keyword.) + +A @racket[#:body] declaration works as an arbitrary +@racket[kw-formals], not just a single variable like @racket[b] in the +above example. For example, to make the above @racket[mathop] work +only on three arguments that follow the keyword, use @racket[(x y z)] +instead of @racket[b]: + +@examples[ +#:eval kw-eval +(define/kw (mathop #:key [op +] #:body (x y z)) + (op x y z)) +] + +In general, @racket[#:body] handling is compiled to a sub procedure +using @racket[lambda/kw], so that a procedure can use more then one +level of keyword arguments. For example: + +@examples[ +#:eval kw-eval +(define/kw (mathop #:key [op +] + #:body (x y z #:key [convert values])) + (op (convert x) (convert y) (convert z))) +(mathop #:op * 2 4 6 #:convert exact->inexact) +] + +Obviously, nested keyword arguments works only when non-keyword +arguments separate the sets. + +Run-time errors during such calls report a mismatch for a procedure +with a name that is based on the original name plus a @racketidfont{~body} +suffix: + +@examples[ +#:eval kw-eval +(mathop #:op * 2 4) +] + +@; ---------------------------------------- + +@section[#:tag "mode-keywords"]{Mode Keywords} + +Finally, the argument list of a @racket[lambda/kw] can contain +keywords that serve as mode flags to control error reporting. + +@itemize[ + + @item{@as-index{@racket[#:allow-other-keys]} --- The keyword-value + sequence at the call site @italic{can} include keywords that are not + listed in the keyword part of the @racket[lambda/kw] form.} + + @item{@as-index{@racket[#:forbid-other-keys]} --- The keyword-value + sequence at the call site @italic{cannot} include keywords that are + not listed in the keyword part of the @racket[lambda/kw] form, + otherwise the @racket[exn:fail:contract] exception is raised.} + + @item{@as-index{@racket[#:allow-duplicate-keys]} --- The + keyword-value list at the call site @emph{can} include duplicate + values associated with same keyword, the first one is used.} + + @item{@as-index{@racket[#:forbid-duplicate-keys]} --- The + keyword-value list at the call site @italic{cannot} include + duplicate values for keywords, otherwise the + @racket[exn:fail:contract] exception is raised. This restriction + applies only to keywords that are listed in the keyword part of the + @racket[lambda/kw] form --- if other keys are allowed, this + restriction does not apply to them.} + + @item{@as-index{@racket[#:allow-body]} --- Body arguments + @italic{can} be specified at the call site after all keyword-value + pairs.} + + @item{@as-index{@racket[#:forbid-body]} --- Body arguments + @italic{cannot} be specified at the call site after all + keyword-value pairs.} + + @item{@as-index{@racket[#:allow-anything]} --- Allows all of the + above, and treat a single keyword at the end of an argument list as + a @racket[#:body], a situation that is usually an error. When this + is used and no rest-like arguments are used except @racket[#:rest], + an extra loop is saved and calling the procedures is faster (around + 20%).} + + @item{@as-index{@racket[#:forbid-anything]} --- Forbids all of the + above, ensuring that calls are as restricted as possible.} + +] + +These above mode markers are rarely needed, because the default modes +are determined by the declared rest-like arguments: + +@itemize[ + + @item{The default is to allow other keys if a @racket[#:rest], + @racket[#:other-keys+body], @racket[#:all-keys], or + @racket[#:other-keys] variable is declared (and an + @racket[#:other-keys] declaration requires allowing other keys).} + + @item{The default is to allow duplicate keys if a @racket[#:rest] or + @racket[#:all-keys] variable is declared.} + + @item{The default is to allow body arguments if a @racket[#:rest], + @racket[#:body], or @racket[#:other-keys+body] variable is declared + (and a @racket[#:body] argument requires allowing them).} + +] + +Here's an alternate specification, which maps rest-like arguments to +the behavior that they imply: + +@itemize[ + + @item{@racket[#:rest]: Everything is allowed (a body, other keys, + and duplicate keys);} + + @item{@racket[#:other-keys+body]: Other keys and body are allowed, + but duplicates are not;} + + @item{@racket[#:all-keys]: Other keys and duplicate keys are allowed, + but a body is not;} + + @item{@racket[#:other-keys]: Other keys must be allowed (on by + default, cannot use with @racket[#:forbid-other-keys]), and + duplicate keys and body are not allowed;} + + @item{@racket[#:body]: Body must be allowed (on by default, cannot use + with @racket[#:forbid-body]) and other keys and duplicate keys and + body are not allowed;} + + @item{Except for the previous two ``must''s, defaults can be + overridden by an explicit @racket[#:allow-...] or a + @racket[#:forbid-...] mode.} + +] + +@; ---------------------------------------- + +@section[#:tag "keyword-get"]{Property Lists} + +@defproc[(keyword-get [args (listof (cons/c keyword? any/c))] [kw keyword?] + [not-found (-> any)]) + any]{ + +Searches a list of keyword arguments (a ``property list'' or ``plist'' +in Lisp jargon) for the given keyword, and returns the associated +value. It is the facility that is used by @racket[lambda/kw] to +search for keyword values. + +The @racket[args] list is scanned from left to right, if the keyword +is found, then the next value is returned. If the @racket[kw] was not +found, then the @racket[not-found] thunk is used to produce a value by +applying it. If the @racket[kw] was not found, and @racket[not-found] +thunk is not given, @racket[#f] is returned. (No exception is raised +if the @racket[args] list is imbalanced, and the search stops at a +non-keyword value.)} + + +@close-eval[kw-eval] diff --git a/pkgs/compatibility-lib/mzlib/scribblings/list.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/list.scrbl new file mode 100644 index 0000000..fe30696 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/list.scrbl @@ -0,0 +1,77 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/list)) + +@mzlib[#:mode title list] + +@deprecated[@racketmodname[racket/list]]{} + +The @racketmodname[mzlib/list] library re-exports several functions +from @racketmodname[scheme/base] and @racketmodname[scheme/list]: + +@racketblock[ +cons? +empty? +empty +foldl +foldr +remv +remq +remove +remv* +remq* +remove* +findf +memf +assf +filter +sort +] + +@deftogether[( +@defproc[(first [v pair?]) any/c] +@defproc[(second [v (and/c pair? ....)]) any/c] +@defproc[(third [v (and/c pair? ....)]) any/c] +@defproc[(fourth [v (and/c pair? ....)]) any/c] +@defproc[(fifth [v (and/c pair? ....)]) any/c] +@defproc[(sixth [v (and/c pair? ....)]) any/c] +@defproc[(seventh [v (and/c pair? ....)]) any/c] +@defproc[(eighth [v (and/c pair? ....)]) any/c] +)]{ + +Accesses the first, second, @|etc| elment of ``list'' @racket[v]. The +argument need not actually be a list; it is inspected only as far as +necessary to obtain an element (unlike the same-named functions from +@racketmodname[scheme/list], which do require the argument to be a +list).} + + +@defproc[(rest [v pair?]) any/c]{ + +The same as @racket[cdr].} + + +@defproc[(last-pair [v pair?]) pair?]{ + +Returns the last pair in @racket[v], raising an error if @racket[v] is +not a pair (but @racket[v] does not have to be a proper list).} + + + +@defproc[(merge-sorted-lists [lst1 list?][lst2 lst?] + [less-than? (any/c any/c . -> . any/c)]) + list?]{ + +Merges the two sorted input lists, creating a new sorted list. The +merged result is stable: equal items in both lists stay in the same +order, and these in @racket[lst1] precede @racket[lst2].} + +@defproc[(mergesort [lst list?] [less-than? (any/c any/c . -> . any/c)]) + list?]{ + +The same as @racket[sort].} + +@defproc[(quicksort [lst list?] [less-than? (any/c any/c . -> . any/c)]) + list?]{ + +The same as @racket[sort].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/match-grammar.rkt b/pkgs/compatibility-lib/mzlib/scribblings/match-grammar.rkt new file mode 100644 index 0000000..3d3993e --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/match-grammar.rkt @@ -0,0 +1,49 @@ +#lang scheme/base +(require scribblings/reference/match-parse) + +(provide match-grammar) + +(define grammar " +pat ::= id @match anything, bind identifier + | _ @match anything + | literal @match literal + | 'datum @match equal% datum + | (lvp ...) @match sequence of lvps + | (lvp ... . pat) @match lvps consed onto a pat + | #(lvp ...) @match vector of pats + | #&pat @match boxed pat + | ($ struct-id pat ...) @match struct-id instance + | (AND pat ...) @match when all pats match + | (OR pat ...) @match when any pat match + | (NOT pat ...) @match when no pat match + | (= expr pat) @match (expr value) to pat + | (? pred-expr pat ...) @match if (expr value) and pats + | `qp @match quasipattern +literal ::= #t @match true + | #f @match false + | string @match equal% string + | number @match equal% number + | character @match equal% character + | bytes @match equal% byte string + | keyword @match equal% keyword + | regexp literal @match equal% regexp literal + | pregexp literal @match equal% pregexp literal +lvp ::= pat ooo @greedily match pat instances + | pat @match pat +ooo ::= *** @zero or more; *** is literal + | ___ @zero or more + | ..K @K or more + | __K @K or more +qp ::= literal @match literal + | id @match equal% symbol + | (qp ...) @match sequences of qps + | (qp ... . qp) @match sequence of qps consed onto a qp + | (qp ... qp ooo) @match qps consed onto a repeated qp + | #(qp ...) @match vector of qps + | #&qp @match boxed qp + | ,pat @match pat + | ,@pat @match pat, spliced +") + +(define match-grammar + (parse-match-grammar grammar)) diff --git a/pkgs/compatibility-lib/mzlib/scribblings/match.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/match.scrbl new file mode 100644 index 0000000..3919fd6 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/match.scrbl @@ -0,0 +1,57 @@ +#lang scribble/doc +@(require "common.rkt" + "match-grammar.rkt" + (for-label mzlib/match)) + +@(begin + (define-syntax-rule (bind id) + (begin + (require racket/match) + (define id (racket match)))) + (bind racket-match)) + +@mzlib[#:mode title match] + +@deprecated[@racketmodname[racket/match]]{} + +The @racketmodname[mzlib/match] library provides a @racket[match] form +similar to that of @racketmodname[racket/match], but with an different +(older and less extensible) syntax of patterns. + +@defform/subs[(match val-expr clause ...) + ([clause [pat expr ...+] + [pat (=> id) expr ...+]])]{ + +See @racket-match from @racketmodname[racket/match] for a description +of matching. The grammar of @racket[pat] for this @racket[match] is as +follows: + +@|match-grammar|} + +@; ------------------------------------------------------------ + +@deftogether[( +@defform[(define/match (head args) match*-clause ...)] +@defform[(match-lambda clause ...)] +@defform[(match-lambda* clause ...)] +@defform[(match-let ([pat expr] ...) body ...+)] +@defform[(match-let* ([pat expr] ...) body ...+)] +@defform[(match-letrec ([pat expr] ...) body ...+)] +@defform[(match-define pat expr)] +)]{ + +Analogous to the combined forms from @racket[racket/match].} + +@; ------------------------------------------------------------ + +@deftogether[( +@defform*[((define-match-expander id proc-expr) + (define-match-expander id proc-expr proc-expr) + (define-match-expander id proc-expr proc-expr proc-expr))] +@defparam[match-equality-test comp-proc (any/c any/c . -> . any)] +)]{ + +Analogous to the form and parameter from @racket[racket/match]. The +@racket[define-match-expander] form, however, supports an extra +@racket[proc-expr] as the middle one: an expander for use with +@racket[match] from @racketmodname[mzlib/match].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/math.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/math.scrbl new file mode 100644 index 0000000..17791b2 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/math.scrbl @@ -0,0 +1,13 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/math)) + +@mzlib[#:mode title math] + +@deprecated[@racketmodname[racket/math]]{} + +Re-exports @racketmodname[scheme/math], and also exports @racket[e]. + +@defthing[e real?]{ + +An approximation to Euler's constant: @number->string[(exp 1)].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/mzlib.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/mzlib.scrbl new file mode 100644 index 0000000..8fc9b1c --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/mzlib.scrbl @@ -0,0 +1,382 @@ +#lang scribble/doc +@(require "common.rkt") + +@title{MzLib: Legacy Libraries} + +The @filepath{mzlib} collection contains wrappers and libraries for +compatibility with older versions of Racket. In many ways, the +libraries of the @filepath{mzlib} collection go with the +@racketmodname[mzscheme] legacy language. Newer variants of many +libraries reside in the @filepath{scheme} collection. + +@table-of-contents[] + +@; ---------------------------------------------------------------------- + +@mzlib[a-signature] + +@deprecated[@racketmodname[racket/signature]]{} + +Like @racketmodname[scheme/signature] in @hash-lang[] form for +defining a single signature within a module, but based on +@racketmodname[mzscheme] instead of @racketmodname[scheme/base]. + +@; ---------------------------------------------------------------------- + +@mzlib[a-unit] + +@deprecated[@racketmodname[racket/unit]]{} + +Like @racketmodname[scheme/unit] in @hash-lang[] form for defining a +single unit within a module, but based on @racketmodname[mzscheme] +instead of @racketmodname[scheme/base]. + +@; ---------------------------------------------------------------------- + +@mzlib[async-channel] + +@deprecated[@racketmodname[racket/async-channel]]{} + +Re-exports @racketmodname[scheme/async-channel]. + +@; ---------------------------------------------------------------------- + +@include-section["awk.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[class] + +@deprecated[@racketmodname[racket/class]]{} + +Re-exports @racketmodname[scheme/class], except for the contract +constructors. + +@; ---------------------------------------------------------------------- + +@include-section["class100.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[cm] + +@deprecated[@racketmodname[compiler/cm]]{} + +Re-exports @racketmodname[compiler/cm]. + +@; ---------------------------------------------------------------------- + +@mzlib[cm-accomplice] + +@deprecated[@racketmodname[compiler/cm-accomplice]]{} + +Re-exports @racketmodname[compiler/cm-accomplice]. + +@; ---------------------------------------------------------------------- + +@include-section["cmdline.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["cml.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["compat.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["compile.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["contract.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[control] + +@deprecated[@racketmodname[racket/control]]{} + +Re-exports @racketmodname[scheme/control]. + +@; ---------------------------------------------------------------------- + +@mzlib[date] + +@deprecated[@racketmodname[racket/date]]{} + +Re-exports @racketmodname[scheme/date]. + +@; ---------------------------------------------------------------------- + +@mzlib[deflate] + +@deprecated[@racketmodname[file/gzip]]{} + +Re-exports @racketmodname[file/gzip]. + +@; ---------------------------------------------------------------------- + +@mzlib[defmacro] + +@deprecated[@racketmodname[compatibility/defmacro]]{} + +Re-exports @racketmodname[compatibility/defmacro]. + +@; ---------------------------------------------------------------------- + +@include-section["etc.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["file.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["for.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[foreign] + +@deprecated[@racketmodname[ffi/unsafe]]{} + +Re-exports @racketmodname[scheme/foreign]. + +@; ---------------------------------------------------------------------- + +@include-section["include.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[inflate] + +@deprecated[@racketmodname[file/gunzip]]{} + +Re-exports @racketmodname[file/gunzip]. + +@; ---------------------------------------------------------------------- + +@include-section["integer-set.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["kw.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["list.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["match.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["math.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[md5] + +@deprecated[@racketmodname[file/md5]]{} + +Re-exports @racketmodname[file/md5]. + +@; ---------------------------------------------------------------------- + +@include-section["os.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["pconvert.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["pconvert-prop.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["plt-match.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["port.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["pregexp.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[pretty] + +@deprecated[@racketmodname[racket/pretty]]{} + +Re-exports @racketmodname[scheme/pretty]. + +@; ---------------------------------------------------------------------- + +@mzlib[process] + +@deprecated[@racketmodname[racket/system]]{} + +Re-exports @racketmodname[scheme/system]. + +@; ---------------------------------------------------------------------- + +@include-section["restart.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[runtime-path] + +@deprecated[@racketmodname[racket/runtime-path]]{} + +Re-exports @racketmodname[scheme/runtime-path]. + +@; ---------------------------------------------------------------------- + +@include-section["sandbox.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["sendevent.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["serialize.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[shared] + +@deprecated[@racketmodname[racket/shared]]{} + +Re-exports @racketmodname[scheme/shared]. + +@; ---------------------------------------------------------------------- + +@include-section["string.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["struct.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[stxparam] + +@deprecated[@racketmodname[racket/stxparam]]{ +Also see @racketmodname[racket/stxparam-exptime]. +} + +Re-exports @racketmodname[scheme/stxparam] and +@racketmodname[scheme/stxparam-exptime] (both at phase level 0). + +@; ---------------------------------------------------------------------- + +@mzlib[surrogate] + +@deprecated[@racketmodname[racket/surrogate]]{} + +Re-exports @racketmodname[scheme/surrogate]. + +@; ---------------------------------------------------------------------- + +@mzlib[tar] + +@deprecated[@racketmodname[file/tar]]{} + +Re-exports @racketmodname[file/tar]. + +@; ---------------------------------------------------------------------- + +@include-section["thread.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[trace] + +@deprecated[@racketmodname[racket/trace]]{} + +Re-exports @racketmodname[racket/trace]. + +@; ---------------------------------------------------------------------- + +@include-section["traceld.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[trait] + +@deprecated[@racketmodname[racket/trait]]{} + +Re-exports @racketmodname[scheme/trait]. + +@; ---------------------------------------------------------------------- + +@include-section["transcr.scrbl"] + +@; ---------------------------------------------------------------------- + +@include-section["unit.scrbl"] + +@; ---------------------------------------------------------------------- + +@mzlib[unit-exptime] + +@deprecated[@racketmodname[racket/unit-exptime]]{} + +Re-exports @racketmodname[scheme/unit-exptime]. + +@; ---------------------------------------- + +@mzlib[unit200] + +@deprecated[@racketmodname[racket/unit]]{} + +The @racketmodname[mzlib/unit200] library provides an old +implementation of units. See archived version 360 documentation on the +@filepath{unit.ss} library of the @filepath{mzlib} collection for +information about this library. + +@; ---------------------------------------- + +@mzlib[unitsig200] + +@deprecated[@racketmodname[racket/unit]]{} + +The @racketmodname[mzlib/unit200] library provides an old +implementation of units. See archived version 360 documentation on the +@filepath{unitsig.ss} library of the @filepath{mzlib} collection for +information about this library. + +@; ---------------------------------------- + +@mzlib[zip] + +@deprecated[@racketmodname[file/zip]]{} + +Re-exports @racketmodname[file/zip]. + +@; ---------------------------------------------------------------------- + +@(bibliography + + (bib-entry #:key "Shivers06" + #:title "Scsh Reference Manual" + #:author "Olin Shivers, Brian D. Carlstrom, Martin Gasbichler, and Mike Sperber" + #:date "2006") + + (bib-entry #:key "Reppy99" + #:title @italic{Concurrent Programming in ML} + #:author "John H. Reppy" + #:date "1999") + + ) + +@;------------------------------------------------------------------------ + +@index-section[] diff --git a/pkgs/compatibility-lib/mzlib/scribblings/os.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/os.scrbl new file mode 100644 index 0000000..896cd24 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/os.scrbl @@ -0,0 +1,30 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/os)) + +@mzlib[#:mode title os] + +@defproc[(gethostname) string?]{ + +Returns a string for the current machine's hostname (including its +domain).} + + +@defproc[(getpid) exact-integer?]{ + +Returns an integer identifying the current process within the +operating system.} + + +@defproc[(truncate-file [file path-string?][n-bytes exact-nonnegative-integer? 0]) + void?]{ + +Truncates or extends the given @racket[file] so that it is +@racket[n-bytes] long. If the file does not exist, or if the process +does not have sufficient privilege to truncate the file, the +@racket[exn:fail] exception is raised. + +The @racket[truncate-file] function is implemented in terms of +@racketmodname[racket/base]'s @racket[file-truncate].} + + diff --git a/pkgs/compatibility-lib/mzlib/scribblings/pconvert-prop.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/pconvert-prop.scrbl new file mode 100644 index 0000000..ad875fc --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/pconvert-prop.scrbl @@ -0,0 +1,49 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/pconvert + mzlib/pconvert-prop)) + +@mzlib[#:mode title pconvert-prop] + + +@deftogether[( +@defthing[prop:print-converter property?] +@defproc[(print-converter? [v any/c]) any] +@defproc[(print-converter-proc [v print-converter?]) (any/c (any/c . -> . any/c) . -> . any/c)] +)]{ + +The @racket[prop:print-converter] property can be given a procedure +value for a structure type. In that case, for constructor-style print +conversion via @racket[print-convert], instances of the structure are +converted by calling the procedure that is the property's value. The +procedure is called with the value to convert and a procedure to +recursively convert nested values. The result should be an +S-expression for the converted value. + +The @racket[print-converter?] predicate recognizes instances of +structure types that have the @racket[prop:print-converter] property, +and @racket[print-converter-proc] extracts the property value.} + + +@deftogether[( +@defthing[prop:print-convert-constructor-name property?] +@defproc[(print-convert-named-constructor? [v any/c]) any] +@defproc[(print-convert-constructor-name [v print-convert-named-constructor?]) any] +)]{ + +The @racket[prop:print-convert-constructor-name] property can be given +a symbol value for a structure type. In that case, for +constructor-style print conversion via @racket[print-convert], +instances of the structure are shown using the symbol as the +constructor name. + +The @racket[prop:print-converter] property takes precedence over +@racket[prop:print-convert-constructor-name]. If neither is attached +to a structure type, its instances are converted using a constructor +name that is @racketidfont{make-} prefixed onto the result of +@racket[object-name]. + +The @racket[print-convert-named-constructor?] predicate recognizes +instances of structure types that have the +@racket[prop:print-convert-constructor-name] property, and +@racket[print-convert-constructor-name] extracts the property value.} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/pconvert.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/pconvert.scrbl new file mode 100644 index 0000000..00a3c63 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/pconvert.scrbl @@ -0,0 +1,262 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/pconvert + mzlib/pconvert-prop + scheme/pretty)) + +@mzlib[#:mode title pconvert] + +The @racketmodname[mzlib/pconvert] library defines routines for +printing Racket values as @racket[eval]uable S-expressions. Racket's +default printing mode also prints values as expressions (in contrast +to the Lisp and Racket tradition of printing @racket[read]able +S-expressions), but @racketmodname[mzlib/pconvert] is more +configurable and approximates expressions for a wider range of +values. For example, procedures print using @racketresultfont{lambda} +instead of @racketresultfont{#}. + +The @racket[print-convert] procedure does not print values; rather, it +converts a Racket value into another Racket value such that the new +value @racket[pretty-write]s as a Racket expression that evaluates to +the original value. For example, @racket[(pretty-write (print-convert +`(9 ,(box 5) #(6 7))))] prints the literal expression +@racketresult[(list 9 (box 5) (vector 6 7))] to the current output +port. + +To install print converting into the read-eval-print loop, require +@racket[mzlib/pconvert] and call the procedure +@racket[install-converting-printer]. + +In addition to @racket[print-convert], this library provides +@racket[print-convert], @racket[build-share], @racket[get-shared], +and @racket[print-convert-expr]. The last three are used to convert +sub-expressions of a larger expression (potentially with shared +structure). + +See also @racket[prop:print-convert-constructor-name]. + +@defboolparam[abbreviate-cons-as-list abbreviate?]{ + +A parameter that controls how lists are represented with +constructor-style conversion. If the parameter's value is @racket[#t], +lists are represented using @racket[list]. Otherwise, lists are +represented using @racket[cons]. The initial value of the parameter is +@racket[#t].} + + +@defboolparam[booleans-as-true/false use-name?]{ + +A parameter that controls how @racket[#t] and @racket[#f] are +represented. If the parameter's value is @racket[#t], then @racket[#t] +is represented as @racket[true] and @racket[#f] is represented as +@racket[false]. The initial value of the parameter is @racket[#t].} + + +@defparam[use-named/undefined-handler use-handler (any/c . -> . any/c)]{ + +A parameter that controls how values that have inferred names are +represented. The procedure is passed a value. If the procedure returns +true, the procedure associated with @racket[named/undefined-handler] +is invoked to render that value. Only values that have inferred names +but are not defined at the top-level are used with this handler. + +The initial value of the parameter is @racket[(lambda (x) #f)].} + + +@defparam[named/undefined-handler use-handler (any/c . -> . any/c)]{ + +Parameter for a procedure that controls how values that have inferred +names are represented. The procedure is called only if +@racket[use-named/undefined-handler] returns true for some value. In +that case, the procedure is passed that same value, and the result of +the parameter is used as the representation for the value. + +The initial value of the parameter is @racket[(lambda (x) #f)].} + + +@defboolparam[add-make-prefix-to-constructor add-prefix?]{ + +A parameter that controls whether a @racketidfont{make-} prefix is +added to a constructor name for a structure instance. The initial +value of the parameter is @racket[#f].} + + + +@defproc[(build-share [v any/c]) ....]{ + +Takes a value and computes sharing information used for representing +the value as an expression. The return value is an opaque structure +that can be passed back into @racket[get-shared] or +@racket[print-convert-expr].} + + +@defboolparam[constructor-style-printing use-constructors?]{ + +Parameter that controls how values are represented after conversion. +If this parameter's value is @racket[#t], then constructors are used; +e.g., pair containing @racket[1] and @racket[2] is represented as +@racket[(cons 1 2)]. Otherwise, @racket[quasiquote]-style syntax is +used; e.g., the pair containing @racket[1] and @racket[2] is +represented as @racket[`(1 . 2)]. The initial value of the parameter +is @racket[#f]. + +The constructor used for mutable pairs is @racketidfont{mcons}, unless +@racket[print-mpair-curly-braces] is set to @racket[#f], in which case +@racketidfont{cons} and @racketidfont{list} are used. Similarly, when +using @racket[quasiquote] style and @racket[print-mpair-curly-braces] +is set to @racket[#f], mutable pair constructions are represented +using @racketidfont{quote}, @racketidfont{quasiquote}, etc. + +See also @racket[quasi-read-style-printing] and +@racket[prop:print-convert-constructor-name].} + + +@defparam[current-build-share-hook + hook + (any/c (any/c . -> . void?) + (any/c . -> . void?) . -> . any)]{ + +Parameter that sets a procedure used by @racket[print-convert] and +@racket[build-share] to assemble sharing information. The procedure +@racket[hook] takes three arguments: a value @racket[_v], a procedure +@racket[_basic-share], and a procedure @racket[_sub-share]; the return +value is ignored. The @racket[basic-share] procedure takes @racket[_v] +and performs the built-in sharing analysis, while the +@racket[_sub-share] procedure takes a component of @racket[_v] ands +analyzes it. Sharing information is accumulated as values are passed +to @racket[basic-share] and @racket[sub-share]. + +A @racket[current-build-share-hook] procedure usually works together +with a @racket[current-print-convert-hook] procedure.} + + +@defparam[current-build-share-name-hook hook (any/c . -> . (or/c symbol? false/c))]{ + +Parameter that sets a procedure used by @racket[print-convert] and +@racket[build-share] to generate a new name for a shared value. The +@racket[hook] procedure takes a single value and returns a symbol for +the value's name. If @racket[hook] returns @racket[#f], a name is +generated using the form +``@racketidfont{-}@racket[_n]@racketidfont{-}, where @racket[n] is an +integer.} + + +@defparam[current-print-convert-hook + hook + (any/c (any/c . -> . any/c) + (any/c . -> . any/c) + . -> . any/c)]{ + +Parameter that sets a procedure used by @racket[print-convert] and +@racket[print-convert-expr] to convert values. The procedure +@racket[hook] takes three arguments---a value @racket[_v], a procedure +@racket[_basic-convert], and a procedure @racket[_sub-convert]---and +returns the converted representation of @racket[_v]. The +@racket[_basic-convert] procedure takes @racket[_v] and returns the +default conversion, while the @racket[_sub-convert] procedure takes a +component of @racket[_v] and returns its conversion. + +A @racket[current-print-convert-hook] procedure usually works together +with a @racket[current-build-share-hook] procedure.} + + +@defparam[current-read-eval-convert-print-prompt str string?]{ + +Parameter that sets the prompt used by +@racket[install-converting-printer]. +The initial value is @racket["|- "].} + + +@defproc[(get-shared [share-info ....] + [cycles-only? any/c #f]) + (list-of (cons/c symbol? any/c))]{ + +The @racket[shared-info] value must be a result from @racket[build-share]. +The procedure returns a list matching variables to shared values +within the value passed to @racket[build-share]. + +The default value for @racket[cycles-only?] is @racket[#f]; +if it is not @racket[#f], @racket[get-shared] returns only information +about cycles. + +For example, + +@racketblock[ +(get-shared (build-share (shared ([a (cons 1 b)] + [b (cons 2 a)]) + a))) +] + +might return the list + +@racketblock[ +'((-1- (cons 1 -2-)) (-2- (cons 2 -1-))) +]} + + +@defproc[(install-converting-printer) void?]{ + +Sets the current print handler to print values using +@racket[print-convert] and sets @racket[print-as-expression] to +@racket[#f] (since the conversion of a value is meant to be printed in +@racket[read]able form rather than @racket[eval]uable form). The +current read handler is also set to use the prompt returned by +@racket[current-read-eval-convert-print-prompt].} + + +@defproc[(print-convert [v any/c][cycles-only? any/c (show-sharing)]) any/c]{ + +Converts the value @racket[v]. If @racket[cycles-only?] is not +@racket[#f], then only circular objects are included in the +output.} + + +@defproc[(print-convert-expr [share-info ....] + [v any/c] + [unroll-once? any/c]) any/c]{ + +Converts the value @racket[v] using sharing information +@racket[share-info], which was previously returned by +@racket[build-share] for a value containing @racket[v]. If the most +recent call to @racket[get-shared] with @racket[share-info] requested +information only for cycles, then @racket[print-convert-expr] will +only display sharing among values for cycles, rather than showing all +value sharing. + +The @racket[unroll-once?] argument is used if @racket[v] is a shared +value in @racket[share-info]. In this case, if @racket[unroll-once?] +is @racket[#f], then the return value will be a shared-value +identifier; otherwise, the returned value shows the internal structure +of @racket[v] (using shared value identifiers within @racket[v]'s +immediate structure as appropriate).} + + +@defboolparam[quasi-read-style-printing on?]{ + +Parameter that controls how vectors and boxes are represented after +conversion when the value of @racket[constructor-style-printing] is +@racket[#f]. If @racket[quasi-read-style-printing] is set to +@racket[#f], then boxes and vectors are unquoted and represented using +constructors. For example, the list of a box containing the number 1 +and a vector containing the number 1 is represented as @racketresult[`(,(box +1) ,(vector 1))]. If the parameter's value is @racket[#t], then +@racket[#&....] and @racket[#(....)] are used, e.g., @racket[`(#&1 +#(1))]. The initial value of the parameter is @racket[#t].} + + +@defboolparam[show-sharing show?]{ + +Parameter that determines whether sub-value sharing is conserved (and +shown) in the converted output by default. The initial value of the +parameter is @racket[#t].} + + +@defboolparam[whole/fractional-exact-numbers whole-frac?]{ + +Parameter that controls how exact, non-integer numbers are converted +when the numerator is greater than the denominator. If the parameter's +value is @racket[#t], the number is converted to the form @racket[(+ +_integer _fraction)] (i.e., a list containing @racket['+], an exact +integer, and an exact rational less than @racket[1] and greater than +@racket[-1]). The initial value of the parameter is @racket[#f].} + diff --git a/pkgs/compatibility-lib/mzlib/scribblings/plt-match.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/plt-match.scrbl new file mode 100644 index 0000000..4c85ed5 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/plt-match.scrbl @@ -0,0 +1,18 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/plt-match)) + +@mzlib[#:mode title plt-match] + +@deprecated[@racketmodname[racket/match]]{} + +The @racketmodname[mzlib/plt-match] library mostly re-provides +@racket[scheme/match]. + +@deftogether[( +@defform*[((define-match-expander id proc-expr) + (define-match-expander id proc-expr proc-expr) + (define-match-expander id proc-expr proc-expr proc-expr))] +)]{ + +The same as the form from @racketmodname[mzlib/match].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/port.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/port.scrbl new file mode 100644 index 0000000..a172c07 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/port.scrbl @@ -0,0 +1,18 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/port)) + +@mzlib[#:mode title port] + +@deprecated[@racketmodname[racket/port]]{} + +The @racketmodname[mzlib/port] library mostly re-provides +@racketmodname[racket/port]. + +@defproc[(strip-shell-command-start [in input-port?]) void?]{ + +Reads and discards a leading @litchar{#!} in @racket[in] (plus +continuing lines if the line ends with a backslash). Since +@litchar{#!} followed by a forward slash or space is a comment, this +procedure is not needed before reading Scheme expressions.} + diff --git a/pkgs/compatibility-lib/mzlib/scribblings/pregexp.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/pregexp.scrbl new file mode 100644 index 0000000..b988a7c --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/pregexp.scrbl @@ -0,0 +1,58 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/pregexp + (only-in scheme/base regexp-quote))) + +@mzlib[#:mode title pregexp] + +@deprecated[@racketmodname[racket/base]]{} + +The @racketmodname[mzlib/pregexp] library provides wrappers around +@racket[regexp-match], @|etc| that coerce string and byte-string +arguments to @racket[pregexp] matchers instead of @racket[regexp] +matchers. + +The library also re-exports: @racket[pregexp], and it re-exports +@racket[regexp-quote] as @racket[pregexp-quote]. + +@deftogether[( +@defproc[(pregexp-match [pattern (or/c string? bytes? regexp? byte-regexp?)] + [input (or/c string? bytes? input-port?)] + [start-pos exact-nonnegative-integer? 0] + [end-pos (or/c exact-nonnegative-integer? false/c) #f] + [output-port (or/c output-port? false/c) #f]) + (or/c (listof (or/c (cons (or/c string? bytes?) + (or/c string? bytes?)) + false/c)) + false/c)] +@defproc[(pregexp-match-positions [pattern (or/c string? bytes? regexp? byte-regexp?)] + [input (or/c string? bytes? input-port?)] + [start-pos exact-nonnegative-integer? 0] + [end-pos (or/c exact-nonnegative-integer? false/c) #f] + [output-port (or/c output-port? false/c) #f]) + (or/c (listof (or/c (cons exact-nonnegative-integer? + exact-nonnegative-integer?) + false/c)) + false/c)] +@defproc[(pregexp-split [pattern (or/c string? bytes? regexp? byte-regexp?)] + [input (or/c string? bytes? input-port?)] + [start-pos exact-nonnegative-integer? 0] + [end-pos (or/c exact-nonnegative-integer? false/c) #f]) + (listof (or/c string? bytes?))] +@defproc[(pregexp-replace [pattern (or/c string? bytes? regexp? byte-regexp?)] + [input (or/c string? bytes?)] + [insert (or/c string? bytes? + (string? . -> . string?) + (bytes? . -> . bytes?))]) + (or/c string? bytes?)] +@defproc[(pregexp-replace* [pattern (or/c string? bytes? regexp? byte-regexp?)] + [input (or/c string? bytes?)] + [insert (or/c string? bytes? + (string? . -> . string?) + (bytes? . -> . bytes?))]) + (or/c string? bytes?)] +)]{ + +Like @racket[regexp-match], @|etc|, but a string @racket[pattern] +argument is compiled via @racket[pregexp], and a byte string +@racket[pattern] argument is compiled via @racket[byte-pregexp].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/restart.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/restart.scrbl new file mode 100644 index 0000000..610a500 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/restart.scrbl @@ -0,0 +1,69 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/restart + mzlib/cmdline)) + +@mzlib[#:mode title restart] + +@deprecated[@racketmodname[racket/sandbox]]{ +The @racket[racket/sandbox] library provides a more general way to +simulate running a new Racket process. +} + +@defproc[(restart-mzscheme [init-argv (vectorof string?)] + [adjust-flag-table (any/c . -> . any/c)] + [argv (vectorof string?)] + [init-namespace (-> any)]) + boolean?]{ + +Simulates starting Racket with the vector of command-line strings +@racket[argv]. The @racket[init-argv], @racket[adjust-flag-table], and +@racket[init-namespace] arguments are used to modify the default +settings for command-line flags, adjust the parsing of command-line +flags, and customize the initial namespace, respectively. + +The vector of strings @racket[init-argv] is read first with the +standard Racket command-line parsing. Flags that load files or +evaluate expressions (e.g., @Flag{f} and @Flag{e}) are ignored, but +flags that set Racket's modes (e.g., @Flag{c} or @Flag{j}) +effectively set the default mode before @racket[argv] is parsed. + +Before @racket[argv] is parsed, the procedure +@racket[adjust-flag-table] is called with a command-line flag table as +accepted by @racket[parse-command-line]. The return value must also be +a table of command-line flags, and this table is used to parse +@racket[argv]. The intent is to allow @racket[adjust-flag-table] to +add or remove flags from the standard set. + +After @racket[argv] is parsed, a new thread and a namespace are +created for the ``restarted'' Racket. (The new namespace is +installed as the current namespace in the new thread.) In the new +thread, restarting performs the following actions: + +@itemize[ + + @item{The @racket[init-namespace] procedure is called with no + arguments. The return value is ignored.} + + @item{Expressions and files specified by @racket[argv] are evaluated + and loaded. If an error occurs, the remaining expressions and + files are ignored, and the return value for + @racket[restart-mzscheme] is set to @racket[#f].} + + @item{The @racket[read-eval-print-loop] procedure is called, unless a + flag in @racket[init-argv] or @racket[argv] disables it. When + @racket[read-eval-print-loop] returns, the return value for + @racket[restart-mzscheme] is set to @racket[#t].} + +] + +Before evaluating command-line arguments, an exit handler is installed +that immediately returns from @racket[restart-mzscheme] with the value +supplied to the handler. This exit handler remains in effect when +@racket[read-eval-print-loop] is called (unless a command-line +argument changes it). If @racket[restart-mzscheme] returns normally, +the return value is determined as described above. + +Note that an error in a command-line expression followed by +@racket[read-eval-print-loop] produces a @racket[#t] result. This is +consistent with Racket's stand-alone behavior.} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/sandbox.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/sandbox.scrbl new file mode 100644 index 0000000..b71eda9 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/sandbox.scrbl @@ -0,0 +1,84 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/sandbox + (only-in racket/sandbox make-module-evaluator))) + +@(begin + (define-syntax-rule (bind id) + (begin + (require (for-label racket/sandbox)) + (define id (racket make-evaluator)))) + (bind racket-make-evaluator)) + +@mzlib[#:mode title sandbox] + +@deprecated[@racketmodname[racket/sandbox]]{} + +The @racketmodname[mzlib/sandbox] library mostly re-exports +@racketmodname[racket/sandbox], but it provides a slightly different +@racket[make-evaluator] function. + +The library re-exports the following bindings: + +@racketblock[ +sandbox-init-hook +sandbox-reader +sandbox-input +sandbox-output +sandbox-error-output +sandbox-propagate-breaks +sandbox-coverage-enabled +sandbox-namespace-specs +sandbox-override-collection-paths +sandbox-security-guard +sandbox-path-permissions +sandbox-network-guard +sandbox-make-inspector +sandbox-eval-limits +kill-evaluator +break-evaluator +set-eval-limits +put-input +get-output +get-error-output +get-uncovered-expressions +call-with-limits +with-limits +exn:fail:resource? +exn:fail:resource-resource +] + +@defproc*[([(make-evaluator [language (or/c module-path? + (one-of/c 'r5rs 'beginner 'beginner-abbr + 'intermediate 'intermediate-lambda 'advanced) + (list/c (one-of/c 'special) symbol?) + (list/c (one-of/c 'special) symbol?) + (cons/c (one-of/c 'begin) list?))] + [requires (or/c (cons/c 'begin list?) + (listof (or/c module-path? path?)))] + [input-program any/c] ...) + (any/c . -> . any)] + [(make-evaluator [module-decl (or/c syntax? pair?)]) + (any/c . -> . any)])]{ + +Like @racket-make-evaluator or @racket[make-module-evaluator], but +with several differences: + +@itemize[ + + @item{The @racket[language] argument can be one of a fixed set of + symbols: @racket['r5rs], etc. They are converted by adding a + @racket[(list 'special ....)] wrapper.} + + @item{If @racket[requires] starts with @racket['begin], then each + element in the remainder of the list is effectively evaluated + as a prefix to the program. Otherwise, it corresponds to the + @racket[#:requires] argument of @|racket-make-evaluator|.} + + @item{For each of @racket[language] and @racket[requires] that starts + with @racket['begin], the expressions are inspected to find + top-level @racket[require] forms (using symbolic equality to + detect @racket[require]), and the @racket[require]d modules are + added to the @racket[#:allow] list for @|racket-make-evaluator|.} + +]} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/sendevent.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/sendevent.scrbl new file mode 100644 index 0000000..818453b --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/sendevent.scrbl @@ -0,0 +1,29 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/sendevent)) + +@(begin + (define-syntax-rule (bind id) + (begin + (require (for-label scheme/gui/base)) + (define id (racket send-event)))) + (bind mred-send-event)) + +@mzlib[#:mode title sendevent] + +The @racketmodname[mzlib/sendevent] library provides a +@racket[send-event] function that works only on Mac OS X, and only +when running in GRacket (though the library can be loaded in Racket). + +@defproc[(send-event [receiver-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [event-class-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [event-id-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [direct-arg-v any/c (void)] + [argument-list list? null]) + any/c]{ + +Calls @|mred-send-event| @racketmodname[scheme/gui/base], if +available, otherwise raises @racket[exn:fail:unsupported].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/serialize.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/serialize.scrbl new file mode 100644 index 0000000..126213b --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/serialize.scrbl @@ -0,0 +1,39 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/serialize)) + +@(begin + (define-syntax-rule (bind id id2) + (begin + (require (for-label racket/serialize)) + (define id (racket define-serializable-struct)) + (define id2 (racket define-serializable-struct/versions)))) + (bind racket-define-serializable-struct + racket-define-serializable-struct/versions)) + +@mzlib[#:mode title serialize] + +@deprecated[@racketmodname[racket/serialize]]{} + +The @racketmodname[mzlib/serialize] library provides the same bindings +as @racketmodname[racket/serialize], except that +@racket[define-serializable-struct] and +@racket[define-serializable-struct/versions] are based on the syntax +of @racket[define-struct] from @racketmodname[mzscheme]. + +@deftogether[( +@defform[(define-serializable-struct id-maybe-super (field-id ...) maybe-inspector-expr)] +@defform/subs[(define-serializable-struct/versions id-maybe-super vers-num (field-id ...) + (other-version-clause ...) + maybe-inspector-expr) + ([id-maybe-super id + (id super-id)] + [maybe-inspector-expr code:blank + inspector-expr] + [other-version-clause (other-vers make-proc-expr + cycle-make-proc-expr)])] +)]{ + +Like @racket-define-serializable-struct and +@racket-define-serializable-struct/versions, but with the syntax of +closer to @racket[define-struct] of @racketmodname[mzscheme].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/string.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/string.scrbl new file mode 100644 index 0000000..509bfc0 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/string.scrbl @@ -0,0 +1,118 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/string + scheme/contract + (only-in scheme/base + regexp-try-match))) + +@mzlib[#:mode title string] + +@deprecated[@racketmodname[racket/base]]{ +Also see @racketmodname[racket/string] +} + +The @racketmodname[mzlib/string] library re-exports several functions +from @racketmodname[scheme/base]: + +@racketblock[ +real->decimal-string +regexp-quote +regexp-replace-quote +regexp-match* +regexp-match-positions* +regexp-match-peek-positions* +regexp-split +regexp-match-exact? +] + +It also re-exports @racket[regexp-try-match] as +@racket[regexp-match/fail-without-reading]. + + +@defproc[(glob->regexp [str (or/c string bytes?)?] + [hide-dots? any/c #t] + [case-sensitive? any/c (eq? (system-path-convention-type)'unix)] + [simple? any/c #f]) + (or/c regexp? byte-regexp?)]{ + +Produces a regexp for a an input ``glob pattern'' @racket[str]. A +glob pattern is one that matches @litchar{*} with any string, +@litchar{?} with a single character, and character ranges are the same +as in regexps (unless @racket[simple?] is true). In addition, the +resulting regexp does not match strings that begin with @litchar{.}, +unless @racket[str] begins with @litchar{.} or @racket[hide-dots?] is +@racket[#f]. The resulting regexp can be used with string file names +to check the glob pattern. If the glob pattern is provided as a byte +string, the result is a byte regexp. + +The @racket[case-sensitive?] argument determines whether the resulting +regexp is case-sensitive. + +If @racket[simple?] is true, then ranges with +@litchar{[}...@litchar{]} in @racket[str] are treated as literal +character sequences.} + + +@defproc[(string-lowercase! [str (and/c string? (not/c immutable?))]) void?]{ + +Destructively changes @racket[str] to contain only lowercase +characters.} + + +@defproc[(string-uppercase! [str (and/c string? (not/c immutable?))]) void?]{ + +Destructively changes @racket[str] to contain only uppercase +characters.} + + + +@defproc[(eval-string [str (or/c string? bytes?)] + [err-handler (or/c false/c + (any/c . -> . any/c) + (-> any/c)) + #f]) + list?]{ + +Reads and evaluates S-expressions from @racket[str], returning results +for all of the expressions in the string. If any expression produces +multiple results, the results are spliced into the resulting list. If +@racket[str] contains only whitespace and comments, an empty list is +returned, and if @racket[str] contains multiple expressions, the +result will be contain multiple values from all subexpressions. + +The @racket[err-handler] argument can be: +@itemize[ +@item{@racket[#f] (the default) which means that errors are not + caught;} +@item{a one-argument procedure, which will be used with an exception + (when an error occurs) and its result will be returned} +@item{a thunk, which will be used to produce a result.} +]} + + +@defproc[(expr->string [expr any/c]) string?]{ + +Prints @racket[expr] into a string and returns the string.} + + +@defproc[(read-from-string [str (or/c string? bytes?)] + [err-handler (or/c false/c + (any/c . -> . any/c) + (-> any/c)) + #f]) + any/c]{ + +Reads the first S-expression from @racket[str] and returns it. The +@racket[err-handler] is as in @racket[eval-string].} + + +@defproc[(read-from-string-all [str (or/c string? bytes?)] + [err-handler (or/c false/c + (any/c . -> . any/c) + (-> any/c)) + #f]) + list?]{ + +Reads all S-expressions from the string (or byte string) @racket[str] +and returns them in a list. The @racket[err-handler] is as in +@racket[eval-string].} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/struct.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/struct.scrbl new file mode 100644 index 0000000..98a96f7 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/struct.scrbl @@ -0,0 +1,70 @@ +#lang scribble/doc +@(require "common.rkt" + scribble/eval + (for-label mzlib/struct + scheme/contract + (only-in scheme/base + regexp-try-match))) + +@(define struct-eval (make-base-eval)) +@interaction-eval[#:eval struct-eval (require mzscheme)] +@interaction-eval[#:eval struct-eval (require mzlib/struct)] + +@mzlib[#:mode title struct] + +@defform[(copy-struct struct-id struct-expr + (accessor-id field-expr) ...)]{ + +``Functional update'' for structure instances. The result of +evaluating @racket[struct-expr] must be an instance of the structure +type named by @racket[struct-id]. The result of the +@racket[copy-struct] expression is a fresh instance of +@racket[struct-id] with the same field values as the result of +@racket[struct-expr], except that the value for the field accessed by +each @racket[accessor-id] is replaced by the result of +@racket[field-expr]. + +The result of @racket[struct-expr] might be an instance of a sub-type +of @racket[struct-id], but the result of the @racket[copy-struct] +expression is an immediate instance of @racket[struct-id]. If +@racket[struct-expr] does not produce an instance of +@racket[struct-id], the @racket[exn:fail:contract] exception is +raised. + +If any @racket[accessor-id] is not bound to an accessor of +@racket[struct-id] (according to the expansion-time information +associated with @racket[struct-id]), or if the same +@racket[accessor-id] is used twice, then a syntax error is raised.} + + +@defform/subs[(define-struct/properties id (field-id ...) + ((prop-expr val-expr) ...) + maybe-inspector-expr) + ([maybe-inspector-expr code:blank + expr])]{ + +Like @racket[define-struct] from @racketmodname[mzscheme], but +properties can be attached to the structure type. Each +@racket[prop-expr] should produce a structure-type property value, and +each @racket[val-expr] produces the corresponding value for the +property. + +@examples[ +#:eval struct-eval +(define-struct/properties point (x y) + ([prop:custom-write (lambda (p port write?) + (fprintf port "(~a, ~a)" + (point-x p) + (point-y p)))])) +(display (make-point 1 2)) +]} + + +@defform[(make-->vector struct-id)]{ + +Builds a function that accepts a structure type instance (matching +@racket[struct-id]) and provides a vector of the fields of the +structure type instance.} + + +@close-eval[struct-eval] diff --git a/pkgs/compatibility-lib/mzlib/scribblings/thread.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/thread.scrbl new file mode 100644 index 0000000..8ebd38b --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/thread.scrbl @@ -0,0 +1,99 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/thread + racket/engine + scheme/contract + scheme/tcp)) + +@mzlib[#:mode title thread] + +@deprecated[@racketmodname[racket/engine]]{} + +Re-exports the bindings from @racketmodname[racket/engine] under +different names and also provides two extra bindings. The renamings +are: + +@itemlist[ + @item{@racket[engine] as @racket[coroutine]} + @item{@racket[engine?] as @racket[coroutine?]} + @item{@racket[engine-run] as @racket[coroutine-run]} + @item{@racket[engine-result] as @racket[coroutine-result]} + @item{@racket[engine-kill] as @racket[coroutine-kill]} +] + +@defproc[(consumer-thread [f procedure?][init (-> any) void]) + (values thread? procedure?)]{ + +Returns two values: a thread descriptor for a new thread, and a +procedure with the same arity as @racket[f]. + +When the returned procedure is applied, its arguments are queued to be +passed on to @racket[f], and @|void-const| is immediately returned. +The thread created by @racket[consumer-thread] dequeues arguments and +applies @racket[f] to them, removing a new set of arguments from the +queue only when the previous application of @racket[f] has completed; +if @racket[f] escapes from a normal return (via an exception or a +continuation), the @racket[f]-applying thread terminates. + +The @racket[init] argument is a procedure of no arguments; if it is +provided, @racket[init] is called in the new thread immediately after the +thread is created.} + + +@defproc[(run-server [port-no (integer-in 1 65535)] + [conn-proc (input-port? output-port? . -> . any)] + [conn-timeout (and/c real? (not/c negative?))] + [handler (exn? . -> . any/c) void] + [listen ((integer-in 1 65535) (one-of/c 5) (one-of/c #t) + . -> . listener?) + tcp-listen] + [close (listener? . -> . any) tcp-close] + [accept (listener? . ->* . (input-port? output-port?)) tcp-accept] + [accept/break (listener? . ->* . (input-port? output-port?)) tcp-accept/enable-break]) + void?]{ + +Executes a TCP server on the port indicated by @racket[port-no]. When +a connection is made by a client, @racket[conn] is called with two +values: an input port to receive from the client, and an output port +to send to the client. + +Each client connection is managed by a new custodian, and each call to +@racket[conn] occurs in a new thread (managed by the connection's +custodian). If the thread executing @racket[conn] terminates for any +reason (e.g., @racket[conn] returns), the connection's custodian is +shut down. Consequently, @racket[conn] need not close the ports +provided to it. Breaks are enabled in the connection thread if breaks +are enabled when @racket[run-server] is called. + +To facilitate capturing a continuation in one connection thread and +invoking it in another, the parameterization of the +@racket[run-server] call is used for every call to +@racket[handler]. In this parameterization and for the connection's +thread, the @racket[current-custodian] parameter is assigned to the +connection's custodian. + +If @racket[conn-timeout] is not @racket[#f], then it must be a +non-negative number specifying the time in seconds that a connection +thread is allowed to run before it is sent a break signal. Then, if +the thread runs longer than @racket[(* conn-timeout 2)] seconds, then +the connection's custodian is shut down. If @racket[conn-timeout] is +@racket[#f], a connection thread can run indefinitely. + +If @racket[handler] is provided, it is passed exceptions related +to connections (i.e., exceptions not caught by @racket[conn-proc], or +exceptions that occur when trying to accept a connection). The default +handler ignores the exception and returns @|void-const|. + +The @racket[run-server] function uses @racket[listen], @racket[close], +@racket[accept] and @racket[accept/break] in the same way as it might +use @racket[tcp-listen], @racket[tcp-close], @racket[tcp-accept], and +@racket[tcp-accept/enable-break] to accept connections. Provide +alternate procedures to use an alternate communication protocol (such +as SSL) or to supply optional arguments in the use of +@racket[tcp-listen]. The @racket[listener?] part of the contract +indicates that the procedures must all work on the same kind of +listener value. + +The @racket[run-server] procedure loops to serve client connections, +so it never returns. If a break occurs, the loop will cleanly shut +down the server, but it will not terminate active connections.} diff --git a/pkgs/compatibility-lib/mzlib/scribblings/traceld.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/traceld.scrbl new file mode 100644 index 0000000..bda84bb --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/traceld.scrbl @@ -0,0 +1,22 @@ +#lang scribble/doc +@(require "common.rkt") + +@mzlib[#:mode title traceld] + +The @racketmodname[mzlib/traceld] library does not provide any +bindings. Instead, @racketmodname[mzlib/traceld] is @racket[require]d +for its side-effects. + +The @racketmodname[mzlib/traceld] library installs a new load handler +(see @racket[current-load]) and load-extension handler (see +@racket[current-load-extension]) to print information about the files +that are loaded. These handlers chain to the current handlers to +perform the actual loads. Trace output is printed to the port that is +the current error port (see @racket[current-error-port]) when the +library is instantiated. + +Before a file is loaded, the tracer prints the file name and ``time'' +(as reported by the procedure @racket[current-process-milliseconds]) +when the load starts. Trace information for nested loads is printed +with indentation. After the file is loaded, the file name is printed +with the ``time'' that the load completed. diff --git a/pkgs/compatibility-lib/mzlib/scribblings/transcr.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/transcr.scrbl new file mode 100644 index 0000000..1d8cd9e --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/transcr.scrbl @@ -0,0 +1,22 @@ +#lang scribble/doc +@(require "common.rkt") + +@mzlib[#:mode title transcr] + +The @racket[transcript-on] and @racket[transcript-off] procedures of +@racketmodname[mzscheme] always raise +@racket[exn:fail:unsupported]. The @racketmodname[mzlib/transcr] +library provides working versions of @racket[transcript-on] and +@racket[transcript-off]. + +@(define-syntax-rule (go) + (begin + (require (for-label mzlib/transcr)) + + @deftogether[( + @defproc[(transcript-on [filename any/c]) any] + @defproc[(transcript-off) any] + )]{ + + Starts/stops recording a transcript at @racket[filename].})) +@(go) diff --git a/pkgs/compatibility-lib/mzlib/scribblings/unit.scrbl b/pkgs/compatibility-lib/mzlib/scribblings/unit.scrbl new file mode 100644 index 0000000..ce5afd6 --- /dev/null +++ b/pkgs/compatibility-lib/mzlib/scribblings/unit.scrbl @@ -0,0 +1,57 @@ +#lang scribble/doc +@(require "common.rkt" + (for-label mzlib/unit)) + +@(begin + (define-syntax-rule (bind id) + (begin + (require (for-label racket/base)) + (define id (racket struct)))) + (bind racket-struct) + (define-syntax-rule (bindc id) + (begin + (require (for-label racket/unit)) + (define id (racket struct/ctc)))) + (bindc racket-struct/ctc)) + +@mzlib[#:mode title unit #:use-sources ((submod racket/unit compat))] + +@deprecated[@racketmodname[racket/unit]]{} + +The @racketmodname[mzlib/unit] library mostly re-provides +@racketmodname[racket/unit], except for @racket-struct and +@racket-struct/ctc from @racketmodname[racket/unit]. + +@defform/subs[(struct id (field-id ...) omit-decl ...) + ([omit-decl -type + -selectors + -setters + -constructor])]{ + +A signature form like @racket-struct from @racketmodname[racket/base], +but with a different syntax for options that limit exports.} + +@defform/subs[(struct/ctc id ([field-id contract-expr] ...) omit-decl ...) + ([omit-decl -type + -selectors + -setters + -constructor])]{ + +A signature form like @racket-struct/ctc from @racketmodname[racket/unit], +but with a different syntax for the options that limit exports.} + +@deftogether[( +@defidform[struct~r] +@defidform[struct~r/ctc] +)]{ + +The same as @|racket-struct| from @racketmodname[racket/base] and @|racket-struct/ctc| from +@racketmodname[racket/unit].} + +@deftogether[( +@defidform[struct~s] +@defidform[struct~s/ctc] +)]{ + +Like @racket[struct~r] and @racket[struct~r/ctc], but the constructor is +named the same as the type, instead of with @racketidfont{make-} prefix.}