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

add some @tech{}s

Browse Source
This commit is contained in:
Robby Findler 2016-02-20 19:22:54 -06:00
parent e32e1383fe
commit c4ebd771bb
1 changed files with 98 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
pkgs/racket-doc/scribblings/reference/contracts.scrbl
View File

@ -80,8 +80,8 @@ failed, and anything else to indicate it passed.}
Contracts in Racket are subdivided into three different categories: Contracts in Racket are subdivided into three different categories:
@; @;
@itemlist[@item{@deftech{Flat contract}s can be fully checked immediately for @itemlist[@item{@deftech{Flat @tech{contracts}} can be fully checked immediately for
a given value. These kinds of contracts are essentially a given value. These kinds of @tech{contracts} are essentially
predicate functions. Using @racket[flat-contract-predicate], predicate functions. Using @racket[flat-contract-predicate],
you can extract the predicate from an arbitrary flat contract; some you can extract the predicate from an arbitrary flat contract; some
flat contracts can be applied like functions, in which case flat contracts can be applied like functions, in which case
@ -93,7 +93,7 @@ Contracts in Racket are subdivided into three different categories:
cannot. cannot.
The function @racket[flat-contract?] recognizes a flat contract.} The function @racket[flat-contract?] recognizes a flat contract.}
@item{@deftech{Chaperone contracts} are not always immediately @item{@deftech{Chaperone @tech{contracts}} are not always immediately
checkable, but are guaranteed to not change any properties checkable, but are guaranteed to not change any properties
of any values that they check. That is, they may wrap of any values that they check. That is, they may wrap
a value in such a way that it signals contract violations a value in such a way that it signals contract violations
@ -103,9 +103,9 @@ Contracts in Racket are subdivided into three different categories:
that the value had before being wrapped by the contract that the value had before being wrapped by the contract
are preserved by the contract wrapper. are preserved by the contract wrapper.
All flat contracts are also chaperone contracts (but All @tech{flat contracts} are also @tech{chaperone contracts} (but
not vice-versa).} not vice-versa).}
@item{@deftech{Impersonator contracts} do not provide any @item{@deftech{Impersonator @tech{contracts}} do not provide any
guarantees about values they check. Impersonator contracts guarantees about values they check. Impersonator contracts
may hide properties of values, or even make them completely may hide properties of values, or even make them completely
opaque (e.g, @racket[new-∀/c]). opaque (e.g, @racket[new-∀/c]).
@ -130,7 +130,7 @@ implement contracts @cite{Strickland12}.
[flat-contract flat-contract?] [flat-contract flat-contract?]
[generator (or/c #f (-> contract (-> int? any))) #f]) [generator (or/c #f (-> contract (-> int? any))) #f])
flat-contract?]{ flat-contract?]{
Produces a contract like @racket[flat-contract], but with the name @racket[name]. Produces a @tech{flat contract} like @racket[flat-contract], but with the name @racket[name].
For example, For example,
@racketblock[(define/contract i @racketblock[(define/contract i
@ -145,7 +145,7 @@ The generator argument adds a generator for the flat-named-contract. See
@defthing[any/c flat-contract?]{ @defthing[any/c flat-contract?]{
A flat contract that accepts any value. A @tech{flat contract} that accepts any value.
When using this contract as the result portion of a function contract, When using this contract as the result portion of a function contract,
consider using @racket[any] instead; using @racket[any] leads to consider using @racket[any] instead; using @racket[any] leads to
@ -160,8 +160,8 @@ A @tech{flat contract} that accepts no values.}
@defproc[(or/c [contract contract?] ...) @defproc[(or/c [contract contract?] ...)
contract?]{ contract?]{
Takes any number of contracts and returns Takes any number of @tech{contracts} and returns
a contract that accepts any value that any one of the contracts a @tech{contract} that accepts any value that any one of the contracts
accepts individually. accepts individually.
The @racket[or/c] result tests any value by applying the contracts in The @racket[or/c] result tests any value by applying the contracts in
@ -202,7 +202,7 @@ returns a @racket[list-contract?].
@defproc[(first-or/c [contract contract?] ...) @defproc[(first-or/c [contract contract?] ...)
contract?]{ contract?]{
Takes any number of contracts and returns a contract that Takes any number of @tech{contracts} and returns a @tech{contract} that
accepts any value that any one of the contracts accepts accepts any value that any one of the contracts accepts
individually. individually.
@ -243,7 +243,7 @@ returns a @racket[list-contract?].
@defproc[(and/c [contract contract?] ...) contract?]{ @defproc[(and/c [contract contract?] ...) contract?]{
Takes any number of contracts and returns a contract that Takes any number of @tech{contracts} and returns a @tech{contract} that
accepts any value that satisfies all of the contracts simultaneously. accepts any value that satisfies all of the contracts simultaneously.
If all of the arguments are procedures or @tech{flat contracts}, If all of the arguments are procedures or @tech{flat contracts},
@ -255,19 +255,19 @@ the contracts in order, from left to right.}
@defproc[(not/c [flat-contract flat-contract?]) flat-contract?]{ @defproc[(not/c [flat-contract flat-contract?]) flat-contract?]{
Accepts a flat contract or a predicate and returns a flat contract Accepts a @tech{flat contract} or a predicate and returns a @tech{flat contract}
that checks the inverse of the argument.} that checks the inverse of the argument.}
@defproc[(=/c [z real?]) flat-contract?]{ @defproc[(=/c [z real?]) flat-contract?]{
Returns a flat contract that requires the input to be a number and Returns a @tech{flat contract} that requires the input to be a number and
@racket[=] to @racket[z].} @racket[=] to @racket[z].}
@defproc[(</c [n real?]) flat-contract?]{ @defproc[(</c [n real?]) flat-contract?]{
Returns a flat contract that requires the input to be a number and Returns a @tech{flat contract} that requires the input to be a number and
@racket[<] than @racket[n].} @racket[<] than @racket[n].}
@ -283,7 +283,7 @@ Like @racket[</c], but for @racket[<=].}
Like @racket[</c], but for @racket[>=].} Like @racket[</c], but for @racket[>=].}
@defproc[(between/c [n real?] [m real?]) @defproc[(between/c [n real?] [m real?])
flat-contract?]{ Returns a flat contract that requires the flat-contract?]{ Returns a @tech{flat contract} that requires the
input to be a real number between @racket[n] and @racket[m] or equal to input to be a real number between @racket[n] and @racket[m] or equal to
one of them.} one of them.}
@ -292,41 +292,41 @@ An alias for @racket[between/c].}
@defproc[(integer-in [j exact-integer?] [k exact-integer?]) flat-contract?]{ @defproc[(integer-in [j exact-integer?] [k exact-integer?]) flat-contract?]{
Returns a flat contract that requires the input to be an exact integer Returns a @tech{flat contract} that requires the input to be an exact integer
between @racket[j] and @racket[k], inclusive.} between @racket[j] and @racket[k], inclusive.}
@defproc[(char-in [a char?] [b char?]) flat-contract?]{ @defproc[(char-in [a char?] [b char?]) flat-contract?]{
Returns a flat contract that requires the input to be a character whose Returns a @tech{flat contract} that requires the input to be a character whose
code point number is between the code point numbers of @racket[a] and code point number is between the code point numbers of @racket[a] and
@racket[b], inclusive.} @racket[b], inclusive.}
@defthing[natural-number/c flat-contract?]{ @defthing[natural-number/c flat-contract?]{
A flat contract that requires the input to be an exact non-negative integer.} A @tech{flat contract} that requires the input to be an exact non-negative integer.}
@defproc[(string-len/c [len real?]) flat-contract?]{ @defproc[(string-len/c [len real?]) flat-contract?]{
Returns a flat contract that recognizes strings that have fewer than Returns a @tech{flat contract} that recognizes strings that have fewer than
@racket[len] characters.} @racket[len] characters.}
@defthing[false/c flat-contract?]{ @defthing[false/c flat-contract?]{
An alias @racket[#f] for backwards compatibility.} An alias for @racket[#f] for backwards compatibility.}
@defthing[printable/c flat-contract?]{ @defthing[printable/c flat-contract?]{
A flat contract that recognizes values that can be written out and A @tech{flat contract} that recognizes values that can be written out and
read back in with @racket[write] and @racket[read].} read back in with @racket[write] and @racket[read].}
@defproc[(one-of/c [v any/c] ...+) flat-contract?]{ @defproc[(one-of/c [v any/c] ...+) flat-contract?]{
Accepts any number of atomic values and returns a flat contract that Accepts any number of atomic values and returns a @tech{flat contract} that
recognizes those values, using @racket[eqv?] as the comparison recognizes those values, using @racket[eqv?] as the comparison
predicate. For the purposes of @racket[one-of/c], atomic values are predicate. For the purposes of @racket[one-of/c], atomic values are
defined to be: @tech{characters}, @tech{symbols}, @tech{booleans}, defined to be: @tech{characters}, @tech{symbols}, @tech{booleans},
@ -341,7 +341,7 @@ it simply passes its arguments to @racket[or/c].
@defproc[(symbols [sym symbol?] ...+) flat-contract?]{ @defproc[(symbols [sym symbol?] ...+) flat-contract?]{
Accepts any number of symbols and returns a flat contract that Accepts any number of symbols and returns a @tech{flat contract} that
recognizes those symbols. recognizes those symbols.
This is a backwards compatibility constructor; it merely This is a backwards compatibility constructor; it merely
@ -352,22 +352,22 @@ passes its arguments to @racket[or/c].
[#:immutable immutable (or/c #t #f 'dont-care) 'dont-care] [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care]
[#:flat? flat? boolean? #f]) [#:flat? flat? boolean? #f])
contract?]{ contract?]{
Returns a contract that recognizes vectors. The elements of the vector must Returns a @tech{contract} that recognizes vectors. The elements of the vector must
match @racket[c]. match @racket[c].
If the @racket[flat?] argument is @racket[#t], then the resulting contract is If the @racket[flat?] argument is @racket[#t], then the resulting contract is
a flat contract, and the @racket[c] argument must also be a flat contract. Such a @tech{flat contract}, and the @racket[c] argument must also be a @tech{flat contract}. Such
flat contracts will be unsound if applied to mutable vectors, as they will not @tech{flat contracts} will be unsound if applied to mutable vectors, as they will not
check future operations on the vector. check future operations on the vector.
If the @racket[immutable] argument is @racket[#t] and the @racket[c] argument is If the @racket[immutable] argument is @racket[#t] and the @racket[c] argument is
a flat contract, the result will be a flat contract. If the @racket[c] argument a @tech{flat contract}, the result will be a @tech{flat contract}. If the @racket[c] argument
is a chaperone contract, then the result will be a chaperone contract. is a @tech{chaperone contract}, then the result will be a @tech{chaperone contract}.
When a higher-order @racket[vectorof] contract is applied to a vector, the result When a higher-order @racket[vectorof] contract is applied to a vector, the result
is not @racket[eq?] to the input. The result will be a copy for immutable vectors is not @racket[eq?] to the input. The result will be a copy for immutable vectors
and a @tech{chaperone} or @tech{impersonator} of the input for mutable vectors, and a @tech{chaperone} or @tech{impersonator} of the input for mutable vectors,
unless the @racket[c] argument is a flat contract and the vector is immutable, unless the @racket[c] argument is a @tech{flat contract} and the vector is immutable,
in which case the result is the original vector. in which case the result is the original vector.
@history[#:changed "6.3.0.5" @list{Changed flat vector contracts to not copy @history[#:changed "6.3.0.5" @list{Changed flat vector contracts to not copy
@ -376,24 +376,24 @@ in which case the result is the original vector.
@defproc[(vector-immutableof [c contract?]) contract?]{ @defproc[(vector-immutableof [c contract?]) contract?]{
Returns the same contract as @racket[(vectorof c #:immutable #t)]. This form exists for Returns the same @tech{contract} as @racket[(vectorof c #:immutable #t)]. This form exists for
backwards compatibility.} backwards compatibility.}
@defproc[(vector/c [c contract?] ... @defproc[(vector/c [c contract?] ...
[#:immutable immutable (or/c #t #f 'dont-care) 'dont-care] [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care]
[#:flat? flat? boolean? #f]) [#:flat? flat? boolean? #f])
contract?]{ contract?]{
Returns a contract that recognizes vectors whose lengths match the number of Returns a @tech{contract} that recognizes vectors whose lengths match the number of
contracts given. Each element of the vector must match its corresponding contract. contracts given. Each element of the vector must match its corresponding contract.
If the @racket[flat?] argument is @racket[#t], then the resulting contract is If the @racket[flat?] argument is @racket[#t], then the resulting contract is
a flat contract, and the @racket[c] arguments must also be flat contracts. Such a @tech{flat contract}, and the @racket[c] arguments must also be @tech{flat contracts}. Such
flat contracts will be unsound if applied to mutable vectors, as they will not @tech{flat contracts} will be unsound if applied to mutable vectors, as they will not
check future operations on the vector. check future operations on the vector.
If the @racket[immutable] argument is @racket[#t] and the @racket[c] arguments are If the @racket[immutable] argument is @racket[#t] and the @racket[c] arguments are
flat contracts, the result will be a flat contract. If the @racket[c] arguments @tech{flat contracts}, the result will be a @tech{flat contract}. If the @racket[c] arguments
are chaperone contracts, then the result will be a chaperone contract. are @tech{chaperone contracts}, then the result will be a @tech{chaperone contract}.
When a higher-order @racket[vector/c] contract is applied to a vector, the result When a higher-order @racket[vector/c] contract is applied to a vector, the result
is not @racket[eq?] to the input. The result will be a copy for immutable vectors is not @racket[eq?] to the input. The result will be a copy for immutable vectors
@ -415,13 +415,13 @@ Returns a contract that recognizes boxes. The content of the box must match @rac
and mutations on mutable boxes must match @racket[in-c]. and mutations on mutable boxes must match @racket[in-c].
If the @racket[flat?] argument is @racket[#t], then the resulting contract is If the @racket[flat?] argument is @racket[#t], then the resulting contract is
a flat contract, and the @racket[out] argument must also be a flat contract. Such a @tech{flat contract}, and the @racket[out] argument must also be a @tech{flat contract}. Such
flat contracts will be unsound if applied to mutable boxes, as they will not check @tech{flat contracts} will be unsound if applied to mutable boxes, as they will not check
future operations on the box. future operations on the box.
If the @racket[immutable] argument is @racket[#t] and the @racket[c] argument is If the @racket[immutable] argument is @racket[#t] and the @racket[c] argument is
a flat contract, the result will be a flat contract. If the @racket[c] argument is a @tech{flat contract}, the result will be a @tech{flat contract}. If the @racket[c] argument is
a chaperone contract, then the result will be a chaperone contract. a @tech{chaperone contract}, then the result will be a @tech{chaperone contract}.
When a higher-order @racket[box/c] contract is applied to a box, the result When a higher-order @racket[box/c] contract is applied to a box, the result
is not @racket[eq?] to the input. The result will be a copy for immutable boxes is not @racket[eq?] to the input. The result will be a copy for immutable boxes
@ -578,7 +578,7 @@ necessarily @racket[eq?] to the input.
@defproc[(syntax/c [c flat-contract?]) flat-contract?]{ @defproc[(syntax/c [c flat-contract?]) flat-contract?]{
Produces a flat contract that recognizes syntax objects whose Produces a @tech{flat contract} that recognizes syntax objects whose
@racket[syntax-e] content matches @racket[c].} @racket[syntax-e] content matches @racket[c].}
@ -587,11 +587,11 @@ Produces a contract that recognizes instances of the structure
type named by @racket[struct-id], and whose field values match the type named by @racket[struct-id], and whose field values match the
contracts produced by the @racket[contract-expr]s. contracts produced by the @racket[contract-expr]s.
Contracts for immutable fields must be either flat or chaperone contracts. Contracts for immutable fields must be either flat or @tech{chaperone contracts}.
Contracts for mutable fields may be impersonator contracts. Contracts for mutable fields may be impersonator contracts.
If all fields are immutable and the @racket[contract-expr]s evaluate If all fields are immutable and the @racket[contract-expr]s evaluate
to flat contracts, a flat contract is produced. If all the to @tech{flat contracts}, a @tech{flat contract} is produced. If all the
@racket[contract-expr]s are chaperone contracts, a chaperone contract is @racket[contract-expr]s are @tech{chaperone contracts}, a @tech{chaperone contract} is
produced. Otherwise, an impersonator contract is produced. produced. Otherwise, an impersonator contract is produced.
} }
@ -622,8 +622,8 @@ for the fields based on the values of the @racket[dep-field-name] fields (the
@racket[dep-field-name] syntax is the same as the @racket[field-name] syntax). @racket[dep-field-name] syntax is the same as the @racket[field-name] syntax).
If the field is a dependent field and no @racket[contract-type] annotation If the field is a dependent field and no @racket[contract-type] annotation
appears, then it is assumed that the contract is appears, then it is assumed that the contract is
a chaperone, but not always a flat contract (and thus the entire @racket[struct/dc] a chaperone, but not always a @tech{flat contract} (and thus the entire @racket[struct/dc]
contract is not a flat contract). contract is not a @tech{flat contract}).
If this is not the case, and the contract is If this is not the case, and the contract is
always flat then the field must be annotated with always flat then the field must be annotated with
the @racket[#:flat], or the field must be annotated with the @racket[#:flat], or the field must be annotated with
@ -651,11 +651,11 @@ If the @racket[#:inv] clause appears, then the invariant expression is
evaluated (and must return a non-@racket[#f] value) when the contract evaluated (and must return a non-@racket[#f] value) when the contract
is applied to a struct. is applied to a struct.
Contracts for immutable fields must be either flat or chaperone contracts. Contracts for immutable fields must be either flat or @tech{chaperone contracts}.
Contracts for mutable fields may be impersonator contracts. Contracts for mutable fields may be impersonator contracts.
If all fields are immutable and the @racket[contract-expr]s evaluate If all fields are immutable and the @racket[contract-expr]s evaluate
to flat contracts, a flat contract is produced. If all the to @tech{flat contracts}, a @tech{flat contract} is produced. If all the
@racket[contract-expr]s are chaperone contracts, a chaperone contract is @racket[contract-expr]s are @tech{chaperone contracts}, a @tech{chaperone contract} is
produced. Otherwise, an impersonator contract is produced. produced. Otherwise, an impersonator contract is produced.
As an example, the function @racket[bst/c] below As an example, the function @racket[bst/c] below
@ -731,15 +731,15 @@ There are a number of technicalities that control how @racket[hash/c] contracts
behave. behave.
@itemlist[@item{ @itemlist[@item{
If the @racket[flat?] argument is @racket[#t], then the resulting contract is If the @racket[flat?] argument is @racket[#t], then the resulting contract is
a flat contract, and the @racket[key] and @racket[val] arguments must also be flat a @tech{flat contract}, and the @racket[key] and @racket[val] arguments must also be
contracts. @tech{flat contracts}.
@examples[#:eval (contract-eval) #:once @examples[#:eval (contract-eval) #:once
(flat-contract? (hash/c integer? boolean?)) (flat-contract? (hash/c integer? boolean?))
(flat-contract? (hash/c integer? boolean? #:flat? #t)) (flat-contract? (hash/c integer? boolean? #:flat? #t))
(eval:error (hash/c integer? (-> integer? integer?) #:flat? #t))] (eval:error (hash/c integer? (-> integer? integer?) #:flat? #t))]
Such flat contracts will be unsound if applied to mutable hash tables, Such @tech{flat contracts} will be unsound if applied to mutable hash tables,
as they will not check future mutations to the hash table. as they will not check future mutations to the hash table.
@examples[#:eval (contract-eval) #:once @examples[#:eval (contract-eval) #:once
@ -823,8 +823,8 @@ for mutable hash tables.
Produces a contract that recognizes @tech{channel}s that communicate Produces a contract that recognizes @tech{channel}s that communicate
values as specified by the @racket[val] argument. values as specified by the @racket[val] argument.
If the @racket[val] argument is a chaperone contract, then the resulting contract If the @racket[val] argument is a @tech{chaperone contract}, then the resulting contract
is a chaperone contract. Otherwise, the resulting contract is an impersonator is a @tech{chaperone contract}. Otherwise, the resulting contract is an impersonator
contract. When a channel contract is applied to a channel, the resulting channel contract. When a channel contract is applied to a channel, the resulting channel
is not @racket[eq?] to the input. is not @racket[eq?] to the input.
@ -851,7 +851,7 @@ Each @racket[contract] will check the corresponding value passed to
an @racket[abort-current-continuation] and handled by the handler of a an @racket[abort-current-continuation] and handled by the handler of a
call to @racket[call-with-continuation-prompt]. call to @racket[call-with-continuation-prompt].
If all of the @racket[contract]s are chaperone contracts, the resulting If all of the @racket[contract]s are @tech{chaperone contracts}, the resulting
contract will also be a @tech{chaperone} contract. Otherwise, the contract is contract will also be a @tech{chaperone} contract. Otherwise, the contract is
an @tech{impersonator} contract. an @tech{impersonator} contract.
@ -882,7 +882,7 @@ Takes a single contract and returns a contract that recognizes
continuation marks and will check any mappings of marks to values continuation marks and will check any mappings of marks to values
or any accesses of the mark value. or any accesses of the mark value.
If the argument @racket[contract] is a chaperone contract, the resulting If the argument @racket[contract] is a @tech{chaperone contract}, the resulting
contract will also be a @tech{chaperone} contract. Otherwise, the contract is contract will also be a @tech{chaperone} contract. Otherwise, the contract is
an @tech{impersonator} contract. an @tech{impersonator} contract.
@ -907,7 +907,7 @@ Returns a contract that recognizes @tech{synchronizable event}s whose
@racket[contract]s. @racket[contract]s.
The resulting contract is always a @tech{chaperone} contract and its The resulting contract is always a @tech{chaperone} contract and its
arguments must all be chaperone contracts. arguments must all be @tech{chaperone contracts}.
@examples[#:eval (contract-eval) #:once @examples[#:eval (contract-eval) #:once
(define/contract my-evt (define/contract my-evt
@ -937,7 +937,7 @@ For example, the contract
symbol?) symbol?)
] ]
is a flat contract that checks for (a limited form of) is a @tech{flat contract} that checks for (a limited form of)
S-expressions. It says that a @racket[sexp] is either two S-expressions. It says that a @racket[sexp] is either two
@racket[sexp]s combined with @racket[cons], or a number, or a symbol. @racket[sexp]s combined with @racket[cons], or a number, or a symbol.
@ -948,7 +948,7 @@ checking will not terminate.}
@defform[(flat-murec-contract ([id flat-contract-expr ...] ...) body ...+)]{ @defform[(flat-murec-contract ([id flat-contract-expr ...] ...) body ...+)]{
A generalization of @racket[flat-rec-contract] for defining several A generalization of @racket[flat-rec-contract] for defining several
mutually recursive flat contracts simultaneously. Each @racket[id] is mutually recursive @tech{flat contracts} simultaneously. Each @racket[id] is
visible in the entire @racket[flat-murec-contract] form, and the visible in the entire @racket[flat-murec-contract] form, and the
result of the final @racket[body] is the result of the entire form.} result of the final @racket[body] is the result of the entire form.}
@ -971,16 +971,16 @@ Constructs a @tech{flat contract} from @racket[predicate]. A value
satisfies the contract if the predicate returns a true value. satisfies the contract if the predicate returns a true value.
This function is a holdover from before predicates could be used This function is a holdover from before predicates could be used
directly as flat contracts. It exists today for backwards compatibility. directly as @tech{flat contracts}. It exists today for backwards compatibility.
} }
@defproc[(flat-contract-predicate [v flat-contract?]) @defproc[(flat-contract-predicate [v flat-contract?])
(-> any/c any/c)]{ (-> any/c any/c)]{
Extracts the predicate from a flat contract. Extracts the predicate from a @tech{flat contract}.
This function is a holdover from before flat contracts could be used This function is a holdover from before @tech{flat contracts} could be used
directly as predicates. It exists today for backwards compatibility. directly as predicates. It exists today for backwards compatibility.
} }
@ -1184,9 +1184,9 @@ In other words, @racket[->i] expresses dependencies among arguments and results.
The optional first keyword argument to @racket[->i] indicates if the result The optional first keyword argument to @racket[->i] indicates if the result
contract will be a chaperone. If it is @racket[#:chaperone], all of the contract for the arguments contract will be a chaperone. If it is @racket[#:chaperone], all of the contract for the arguments
and results must be chaperone contracts and the result of @racket[->i] will be and results must be @tech{chaperone contracts} and the result of @racket[->i] will be
a chaperone contract. If it is not present, then the result a @tech{chaperone contract}. If it is not present, then the result
contract will not be a chaperone contract. contract will not be a @tech{chaperone contract}.
The first sub-form of a @racket[->i] contract covers the mandatory and the The first sub-form of a @racket[->i] contract covers the mandatory and the
second sub-form covers the optional arguments. Following that is an optional second sub-form covers the optional arguments. Following that is an optional
@ -2003,15 +2003,15 @@ accepted by the third argument to @racket[datum->syntax].
flat-contract?] flat-contract?]
)]{ )]{
These functions build simple higher-order contracts, chaperone contracts, and flat contracts, These functions build simple higher-order contracts, @tech{chaperone contracts}, and @tech{flat contracts},
respectively. They both take the same set of three optional arguments: a name, respectively. They both take the same set of three optional arguments: a name,
a first-order predicate, and a blame-tracking projection. a first-order predicate, and a blame-tracking projection.
The @racket[name] argument is any value to be rendered using @racket[display] to The @racket[name] argument is any value to be rendered using @racket[display] to
describe the contract when a violation occurs. The default name for simple describe the contract when a violation occurs. The default name for simple
higher-order contracts is @racketresult[anonymous-contract], for chaperone higher-order contracts is @racketresult[anonymous-contract], for
contracts is @racketresult[anonymous-chaperone-contract], and for flat @tech{chaperone contracts} is @racketresult[anonymous-chaperone-contract], and for
contracts is @racketresult[anonymous-flat-contract]. @tech{flat contracts} is @racketresult[anonymous-flat-contract].
The first-order predicate @racket[test] can be used to determine which values The first-order predicate @racket[test] can be used to determine which values
the contract applies to; this must be the set of values for which the the contract applies to; this must be the set of values for which the
@ -2051,14 +2051,14 @@ The projection arguments (@racket[late-neg-proj], @racket[proj], and
In particular, if the test argument returns @racket[#f] for some value, In particular, if the test argument returns @racket[#f] for some value,
then the projections must raise a blame error for that value. then the projections must raise a blame error for that value.
Projections for chaperone contracts must produce a value that passes Projections for @tech{chaperone contracts} must produce a value that passes
@racket[chaperone-of?] when compared with the original, uncontracted value. @racket[chaperone-of?] when compared with the original, uncontracted value.
Projections for flat contracts must fail precisely when the first-order test Projections for @tech{flat contracts} must fail precisely when the first-order test
does, and must produce the input value unchanged otherwise. Applying a flat does, and must produce the input value unchanged otherwise. Applying a
contract may result in either an application of the predicate, or the @tech{flat contract} may result in either an application of the predicate, or the
projection, or both; therefore, the two must be consistent. The existence of a projection, or both; therefore, the two must be consistent. The existence of a
separate projection only serves to provide more specific error messages. Most separate projection only serves to provide more specific error messages. Most
flat contracts do not need to supply an explicit projection. @tech{flat contracts} do not need to supply an explicit projection.
The @racket[stronger] argument is used to implement @racket[contract-stronger?]. The The @racket[stronger] argument is used to implement @racket[contract-stronger?]. The
first argument is always the contract itself and the second argument is whatever first argument is always the contract itself and the second argument is whatever
@ -2129,23 +2129,23 @@ contracts. The error messages assume that the function named by
@defproc[(coerce-chaperone-contract [id symbol?] [x any/c]) chaperone-contract?]{ @defproc[(coerce-chaperone-contract [id symbol?] [x any/c]) chaperone-contract?]{
Like @racket[coerce-contract], but requires the result Like @racket[coerce-contract], but requires the result
to be a chaperone contract, not an arbitrary contract. to be a @tech{chaperone contract}, not an arbitrary contract.
} }
@defproc[(coerce-chaperone-contracts [id symbol?] [x (listof any/c)]) @defproc[(coerce-chaperone-contracts [id symbol?] [x (listof any/c)])
(listof chaperone-contract?)]{ (listof chaperone-contract?)]{
Like @racket[coerce-contracts], but requires the results Like @racket[coerce-contracts], but requires the results
to be chaperone contracts, not arbitrary contracts. to be @tech{chaperone contracts}, not arbitrary contracts.
} }
@defproc[(coerce-flat-contract [id symbol?] [x any/c]) flat-contract?]{ @defproc[(coerce-flat-contract [id symbol?] [x any/c]) flat-contract?]{
Like @racket[coerce-contract], but requires the result Like @racket[coerce-contract], but requires the result
to be a flat contract, not an arbitrary contract. to be a @tech{flat contract}, not an arbitrary contract.
} }
@defproc[(coerce-flat-contracts [id symbol?] [x (listof any/c)]) (listof flat-contract?)]{ @defproc[(coerce-flat-contracts [id symbol?] [x (listof any/c)]) (listof flat-contract?)]{
Like @racket[coerce-contracts], but requires the results Like @racket[coerce-contracts], but requires the results
to be flat contracts, not arbitrary contracts. to be @tech{flat contracts}, not arbitrary contracts.
} }
@defproc[(coerce-contract/f [x any/c]) (or/c contract? #f)]{ @defproc[(coerce-contract/f [x any/c]) (or/c contract? #f)]{
@ -2403,12 +2403,12 @@ the message that indicates the violation.
@para{ @para{
The property @racket[prop:contract] allows arbitrary structures to act as The property @racket[prop:contract] allows arbitrary structures to act as
contracts. The property @racket[prop:chaperone-contract] allows arbitrary contracts. The property @racket[prop:chaperone-contract] allows arbitrary
structures to act as chaperone contracts; @racket[prop:chaperone-contract] structures to act as @tech{chaperone contracts}; @racket[prop:chaperone-contract]
inherits @racket[prop:contract], so chaperone contract structures may also act inherits @racket[prop:contract], so @tech{chaperone contract} structures may also act
as general contracts. The property @racket[prop:flat-contract] allows arbitrary structures as general contracts. The property @racket[prop:flat-contract] allows arbitrary structures
to act as flat contracts; @racket[prop:flat-contract] inherits both to act as @tech{flat contracts}; @racket[prop:flat-contract] inherits both
@racket[prop:chaperone-contract] and @racket[prop:procedure], so flat contract structures @racket[prop:chaperone-contract] and @racket[prop:procedure], so @tech{flat contract} structures
may also act as chaperone contracts, as general contracts, and as predicate procedures. may also act as @tech{chaperone contracts}, as general contracts, and as predicate procedures.
} }
@deftogether[( @deftogether[(
@ -2416,7 +2416,7 @@ may also act as chaperone contracts, as general contracts, and as predicate proc
@defthing[prop:chaperone-contract struct-type-property?] @defthing[prop:chaperone-contract struct-type-property?]
@defthing[prop:flat-contract struct-type-property?] @defthing[prop:flat-contract struct-type-property?]
)]{ )]{
These properties declare structures to be contracts or flat contracts, These properties declare structures to be contracts or @tech{flat contracts},
respectively. The value for @racket[prop:contract] must be a @tech{contract respectively. The value for @racket[prop:contract] must be a @tech{contract
property} constructed by @racket[build-contract-property]; likewise, the value property} constructed by @racket[build-contract-property]; likewise, the value
for @racket[prop:chaperone-contract] must be a @tech{chaperone contract property} for @racket[prop:chaperone-contract] must be a @tech{chaperone contract property}
@ -2661,7 +2661,7 @@ projection accessor must return a value that passes @racket[chaperone-of?] when
compared with the original, uncontracted value. compared with the original, uncontracted value.
A @deftech{flat contract property} specifies the behavior of a structure when A @deftech{flat contract property} specifies the behavior of a structure when
used as a flat contract. It is specified using used as a @tech{flat contract}. It is specified using
@racket[build-flat-contract-property], and accepts exactly the same set of @racket[build-flat-contract-property], and accepts exactly the same set of
arguments as @racket[build-contract-property]. The only difference is that the arguments as @racket[build-contract-property]. The only difference is that the
projection accessor is expected not to wrap its argument in a higher-order projection accessor is expected not to wrap its argument in a higher-order
@ -2832,20 +2832,22 @@ higher-order contracts.
@defproc[(contract? [v any/c]) boolean?]{ @defproc[(contract? [v any/c]) boolean?]{
Returns @racket[#t] if its argument is a contract (i.e., constructed Returns @racket[#t] if its argument is a @tech{contract} (i.e., constructed
with one of the combinators described in this section or a value that with one of the combinators described in this section or a value that
can be used as a contract) and @racket[#f] otherwise.} can be used as a contract) and @racket[#f] otherwise.}
@defproc[(chaperone-contract? [v any/c]) boolean?]{ @defproc[(chaperone-contract? [v any/c]) boolean?]{
Returns @racket[#t] if its argument is a contract that guarantees that Returns @racket[#t] if its argument is a @tech{chaperone contract},
i.e., one that guarantees that
it returns a value which passes @racket[chaperone-of?] when compared to it returns a value which passes @racket[chaperone-of?] when compared to
the original, uncontracted value.} the original, uncontracted value.}
@defproc[(impersonator-contract? [v any/c]) boolean?]{ @defproc[(impersonator-contract? [v any/c]) boolean?]{
Returns @racket[#t] if its argument is a contract that is not a chaperone Returns @racket[#t] if its argument is an @tech{impersonator contract},
contract nor a flat contract.} i.e., a @tech{contract} that is neither a @tech{chaperone contract}
nor a @tech{flat contract}.}
@defproc[(flat-contract? [v any/c]) boolean?]{ @defproc[(flat-contract? [v any/c]) boolean?]{
@ -2853,10 +2855,10 @@ Returns @racket[#t] when its argument is a contract that can be
checked immediately (unlike, say, a function contract). checked immediately (unlike, say, a function contract).
For example, For example,
@racket[flat-contract] constructs flat contracts from predicates, and @racket[flat-contract] constructs @tech{flat contracts} from predicates, and
symbols, booleans, numbers, and other ordinary Racket values symbols, booleans, numbers, and other ordinary Racket values
(that are defined as @tech{contracts}) are also (that are defined as @tech{contracts}) are also
flat contracts.} @tech{flat contracts}.}
@defproc[(list-contract? [v any/c]) boolean?]{ @defproc[(list-contract? [v any/c]) boolean?]{
Recognizes certain @racket[contract?] values that accept @racket[list?]s. Recognizes certain @racket[contract?] values that accept @racket[list?]s.
@ -3040,8 +3042,8 @@ currently being checked.
Produces a contract that acts like @racket[contract] but with the name Produces a contract that acts like @racket[contract] but with the name
@racket[name]. @racket[name].
The resulting contract is a flat contract if @racket[contract] is a The resulting contract is a @tech{flat contract} if @racket[contract] is a
flat contract. @tech{flat contract}.
@history[#:added "6.3"] @history[#:added "6.3"]
} }
@ -3082,9 +3084,9 @@ currently being checked.
Produces a contract that, when applied to a value, first tests the Produces a contract that, when applied to a value, first tests the
value with @racket[predicate]; if @racket[predicate] returns true, the value with @racket[predicate]; if @racket[predicate] returns true, the
@racket[then-contract] is applied; otherwise, the @racket[then-contract] is applied; otherwise, the
@racket[else-contract] is applied. The resulting contract is a flat @racket[else-contract] is applied. The resulting contract is a
contract if both @racket[then-contract] and @racket[else-contract] are @tech{flat contract} if both @racket[then-contract] and @racket[else-contract] are
flat contracts. @tech{flat contracts}.
For example, the following contract enforces that if a value is a For example, the following contract enforces that if a value is a
procedure, it is a thunk; otherwise it can be any (non-procedure) procedure, it is a thunk; otherwise it can be any (non-procedure)
@ -3093,7 +3095,7 @@ currently being checked.
Note that the following contract is @bold{not} equivalent: Note that the following contract is @bold{not} equivalent:
@racketblock[(or/c (-> any) any/c) (code:comment "wrong!")] @racketblock[(or/c (-> any) any/c) (code:comment "wrong!")]
The last contract is the same as @racket[any/c] because The last contract is the same as @racket[any/c] because
@racket[or/c] tries flat contracts before higher-order contracts. @racket[or/c] tries @tech{flat contracts} before higher-order contracts.
@history[#:added "6.3"] @history[#:added "6.3"]
} }