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

add documentation for racket/contract/base (also trim some

Browse Source 
of the longer lines in the file)

closes PR 12311
This commit is contained in:
Robby Findler 2011-10-25 14:50:55 -05:00
parent 41b8b8142a
commit 48f9b8895c
1 changed files with 43 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
collects/scribblings/reference/contracts.scrbl
View File

@ -57,7 +57,9 @@ that recognize themselves using @racket[equal?], }
@item{@tech{numbers}, which are treated as contracts
that recognize themselves using @racket[=],}
@item{@tech{regular expressions}, which are treated as contracts that recognize @tech{byte strings} and @tech{strings} that match the regular expression, and }
@item{@tech{regular expressions}, which are treated as contracts
that recognize @tech{byte strings} and @tech{strings} that
match the regular expression, and }
@item{predicates: any procedure of arity 1 is treated as a
predicate. During contract checking, it is applied to the values that
@ -70,7 +72,7 @@ failed, and anything else to indicate it passed.}
@; ----------------------------------------
@section{Data-structure Contracts}
@section[#:tag "data-structure-contracts"]{Data-structure Contracts}
@declare-exporting-ctc[racket/contract/base]
A @deftech{flat contract} can be fully checked immediately for
@ -82,7 +84,8 @@ Constructs a @tech{flat contract} from @racket[predicate]. A value
satisfies the contract if the predicate returns a true value.}
@defproc[(flat-named-contract [type-name any/c] [predicate (or/c flat-contract? (any/c . -> . any))])
@defproc[(flat-named-contract [type-name any/c]
[predicate (or/c flat-contract? (any/c . -> . any))])
flat-contract?]{
On predicates like @racket[flat-contract], but the first argument must be the
@ -234,7 +237,8 @@ read back in with @racket[write] and @racket[read].}
Accepts any number of atomic values and returns a flat contract that
recognizes those values, using @racket[eqv?] as the comparison
predicate. For the purposes of @racket[one-of/c], atomic values are
defined to be: @tech{characters}, @tech{symbols}, @tech{booleans}, @racket[null], @tech{keywords}, @tech{numbers},
defined to be: @tech{characters}, @tech{symbols}, @tech{booleans},
@racket[null], @tech{keywords}, @tech{numbers},
@|void-const|, and @|undefined-const|.}
@ -447,8 +451,7 @@ result value meets the contract produced by @racket[expr].}
@; ------------------------------------------------------------------------
@section{Function Contracts}
@section[#:tag "function-contracts"]{Function Contracts}
@declare-exporting-ctc[racket/contract/base]
A @deftech{function contract} wraps a procedure to delay
@ -812,8 +815,8 @@ if they do not, a contract violation is signaled.
Universal contracts accept all values when in negative positions (e.g., function
inputs) and wrap them in an opaque struct, hiding the precise value.
In positive positions (e.g. function returns),
a universal contract accepts only values that were previously accepted in negative positions (by checking
for the wrappers).
a universal contract accepts only values that were previously accepted
in negative positions (by checking for the wrappers).
The name is used to identify the contract in error messages.
@ -897,8 +900,8 @@ indicate which fields it depends on; these dependencies can only be to
earlier fields.}}
@defform[(define-contract-struct id (field-id ...))]{
Like @racket[contract-struct], but where the constructor's name is @racketidfont["make-"]@racket[id],
much like @racket[define-struct].
Like @racket[contract-struct], but where the constructor's name is
@racketidfont["make-"]@racket[id], much like @racket[define-struct].
}
As an example of lazy contract checking, consider the following module:
@ -950,7 +953,7 @@ lazy contract.
@; ------------------------------------------------------------------------
@section{Attaching Contracts to Values}
@section[#:tag "attaching-contracts-to-values"]{Attaching Contracts to Values}
@declare-exporting-ctc[racket/contract/base]
@defform/subs[
@ -1439,7 +1442,8 @@ contracts. The error messages assume that the function named by
to be a chaperone contract, not an arbitrary contract.
}
@defproc[(coerce-chaperone-contracts [id symbol?] [x (listof any/c)]) (listof/c chaperone-contract?)]{
@defproc[(coerce-chaperone-contracts [id symbol?] [x (listof any/c)])
(listof/c chaperone-contract?)]{
Like @racket[coerce-contracts], but requires the results
to be chaperone contracts, not arbitrary contracts.
}
@ -1701,9 +1705,10 @@ which produces a description to @racket[write] as part of a contract violation;
@racket[contract-first-order-passes?]; @racket[get-projection], which
produces a blame-tracking projection defining the behavior of the contract;
@racket[stronger], which is a predicate that determines whether this contract
(passed in the first argument) is stronger than some other contract (passed in the second argument);
and @racket[generator], which makes a random value that matches the contract,
given a size bound and an environment from which to draw interesting values.
(passed in the first argument) is stronger than some other contract (passed
in the second argument); and @racket[generator], which makes a random value
that matches the contract, given a size bound and an environment from which
to draw interesting values.
These accessors are passed as (optional) keyword arguments to
@racket[build-contract-property], and are applied to instances of the
@ -1873,7 +1878,7 @@ Produces the first-order test used by @racket[or/c] to match values to
higher-order contracts.
}
@section{Contract Utilities}
@section[#:tag "contract-utilities"]{Contract Utilities}
@declare-exporting-ctc[racket/contract/base]
@ -1982,6 +1987,25 @@ search tree invariant. Removing the @racket[-opt/c] also
makes a binary search tree contract, but one that is
(approximately) 20 times slower.}
@section{@racketmodname[racket/contract/base]}
@defmodule[racket/contract/base]
The @racketmodname[racket/contract/base] module provides a subset
of the exports of @racketmodname[racket/contract] module. In
particular, it contains everything in the
@itemize[@item{@secref["data-structure-contracts"]}
@item{@secref["function-contracts"]}
@item{@secref["attaching-contracts-to-values"] and}
@item{@secref["contract-utilities"] sections.}]
Unfortunately, using @racketmodname[racket/contract/base] does not
yield a significantly smaller memory footprint than
@racketmodname[racket/contract], but it can still be useful to
add contracts to libraries that @racketmodname[racket/contract]
uses to implement some of the more sophisticated
parts of the contract system.
@section{Legacy Contracts}
@defproc[(make-proj-contract [name any/c]
@ -2022,7 +2046,9 @@ makes a binary search tree contract, but one that is
(blame-contract blame)))]))]
}
@defproc[(raise-contract-error [val any/c] [src any/c] [pos any/c] [name any/c] [fmt string?] [arg any/c] ...)
@defproc[(raise-contract-error [val any/c] [src any/c]
[pos any/c] [name any/c]
[fmt string?] [arg any/c] ...)
any/c]{
Calls @racket[raise-blame-error] after building a @racket[blame] struct from
the @racket[val], @racket[src], @racket[pos], and @racket[name] arguments.