#lang scribble/doc @(require "mz.rkt") @(require (for-label syntax/modcollapse racket/stxparam)) @(define contract-eval (lambda () (let ([the-eval (make-base-eval)]) (the-eval '(require racket/contract racket/contract/parametric)) the-eval))) @title[#:tag "contracts" #:style 'toc]{Contracts} @guideintro["contracts"]{contracts} The contract system guards one part of a program from another. Programmers specify the behavior of a module's exports via @racket[(provide (contract-out ....))], and the contract system enforces those constraints. @(define-syntax-rule (add-use-sources (x y ...)) (x y ... #:use-sources (racket/contract/private/base racket/contract/private/misc racket/contract/private/provide racket/contract/private/guts racket/contract/private/prop racket/contract/private/blame racket/contract/private/ds racket/contract/private/opt racket/contract/private/basic-opters racket/contract/private/box racket/contract/private/hash racket/contract/private/vector racket/contract/private/struct-dc))) @(define-syntax-rule (declare-exporting-ctc mod) (add-use-sources (declare-exporting mod racket/contract racket))) @(add-use-sources @note-lib[racket/contract]) @deftech{Contracts} come in two forms: those constructed by the various operations listed in this section of the manual, and various ordinary Racket values that double as contracts, including @itemize[ @item{@tech{symbols}, @tech{booleans}, @tech{characters}, @tech{keywords}, and @racket[null], which are treated as contracts that recognize themselves, using @racket[eq?], } @item{@tech{strings} and @tech{byte strings}, which are treated as contracts 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{predicates: any procedure of arity 1 is treated as a predicate. During contract checking, it is applied to the values that appear and should return @racket[#f] to indicate that the contract failed, and anything else to indicate it passed.} ] Contracts in Racket are subdivided into three different categories: @itemlist[@item{@deftech{Flat contract}s can be fully checked immediately for a given value. These kinds of contracts are essentially predicate functions. Using @racket[flat-contract-predicate], you can extract the predicate from a flat contract, and @racket[flat-contract?] recognizes a flat contract.} @item{@deftech{Chaperone contracts} are not always immediately checkable, but are guaranteed to not change any properties of any values that they check. That is, they may wrap a value in such a way that it signals contract violations later, as the value is used (e.g., a function contract checks the inputs and outputs to the function only when the function is called and returned), but any properties that the value had before being wrapped by the contract are preserved by the contract wrapper. All flat contracts are also chaperone contracts (but not vice-versa).} @item{@deftech{Impersonator contracts} do not provide any guarantees about values they check. Impersonator contracts may hide properties of values, or even make them completely opaque (e.g, @racket[new-∀/c]). All contracts are impersonator contracts.}] For more about this hierarchy, see @tech{chaperones} and a research paper on chaperones, impersonators, and how they can be used to implement contracts @cite{Strickland12}. @local-table-of-contents[] @; ---------------------------------------- @section[#:tag "data-structure-contracts"]{Data-structure Contracts} @declare-exporting-ctc[racket/contract/base] @defproc[(flat-named-contract [type-name any/c] [predicate (or/c flat-contract? (any/c . -> . any))] [generator (or/c #f (-> contract (-> int? any))) #f]) flat-contract?]{ On predicates, behaves like @racket[flat-contract], but the first argument must be the (quoted) name of a contract used for error reporting. For example, @racketblock[(flat-named-contract 'odd-integer (lambda (x) (and (integer? x) (odd? x))))] turns the predicate into a contract with the name @tt{odd-integer}. On flat contracts, the new flat contract is the same as the old except for the name. The generator argument adds a generator for the flat-named-contract. See @racket[contract-generate] for more information. } @defthing[any/c flat-contract?]{ A flat contract that accepts any value. When using this contract as the result portion of a function contract, consider using @racket[any] instead; using @racket[any] leads to better memory performance, but it also allows multiple results.} @defthing[none/c flat-contract?]{ A @tech{flat contract} that accepts no values.} @defproc[(or/c [contract contract?] ...) contract?]{ Takes any number of contracts and returns a contract that accepts any value that any one of the contracts accepts individually. The @racket[or/c] result tests any value by applying the contracts in order, from left to right, with the exception that it always moves the non-@tech{flat contracts} (if any) to the end, checking them last. Thus, a contract such as @racket[(or/c (not/c real?) positive?)] is guaranteed to only invoke the @racket[positive?] predicate on real numbers. If all of the arguments are procedures or @tech{flat contracts}, the result is a @tech{flat contract}. If only one of the arguments is a higher-order contract, the result is a contract that just checks the flat contracts and, if they don't pass, applies the higher-order contract. If there are multiple higher-order contracts, @racket[or/c] uses @racket[contract-first-order-passes?] to distinguish between them. More precisely, when an @racket[or/c] is checked, it first checks all of the @tech{flat contracts}. If none of them pass, it calls @racket[contract-first-order-passes?] with each of the higher-order contracts. If only one returns true, @racket[or/c] uses that contract. If none of them return true, it signals a contract violation. If more than one returns true, it also signals a contract violation. For example, this contract @racketblock[ (or/c (-> number? number?) (-> string? string? string?)) ] does not accept a function like this one: @racket[(lambda args ...)] since it cannot tell which of the two arrow contracts should be used with the function. } @defproc[(and/c [contract (or/c contract? (any/c . -> . any/c))] ...) contract?]{ Takes any number of contracts and returns a contract that accepts any value that satisfies all of the contracts simultaneously. If all of the arguments are procedures or @tech{flat contracts}, the result is a @tech{flat contract}. The contract produced by @racket[and/c] tests any value by applying the contracts in order, from left to right.} @defproc[(not/c [flat-contract (or/c flat-contract? (any/c . -> . any/c))]) flat-contract?]{ Accepts a flat contracts or a predicate and returns a flat contract that checks the inverse of the argument.} @defproc[(=/c [z real?]) flat-contract?]{ Returns a flat contract that requires the input to be a number and @racket[=] to @racket[z].} @defproc[(/c [n real?]) flat-contract?]{ Like @racket[].} @defproc[(<=/c [n real?]) flat-contract?]{ Like @racket[=/c [n real?]) flat-contract?]{ Like @racket[=].} @defproc[(between/c [n real?] [m real?]) flat-contract?]{ Returns a flat contract that requires the input to be a real number between @racket[n] and @racket[m] or equal to one of them.} @defproc[(real-in [n real?] [m real?]) flat-contract?]{ An alias for @racket[between/c].} @defproc[(integer-in [j exact-integer?] [k exact-integer?]) flat-contract?]{ Returns a flat contract that requires the input to be an exact integer between @racket[j] and @racket[k], inclusive.} @defthing[natural-number/c flat-contract?]{ A flat contract that requires the input to be an exact non-negative integer.} @defproc[(string-len/c [len exact-nonnegative-integer?]) flat-contract?]{ Returns a flat contract that recognizes strings that have fewer than @racket[len] characters.} @defthing[false/c flat-contract?]{ An alias @racket[#f] for backwards compatibility.} @defthing[printable/c flat-contract?]{ A flat contract that recognizes values that can be written out and read back in with @racket[write] and @racket[read].} @defproc[(one-of/c [v any/c] ...+) flat-contract?]{ 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}, @|void-const|, and @|undefined-const|. This is a backwards compatibility contract constructor. If neither @|void-const| nor @|undefined-const| are arguments, it simply passes its arguments to @racket[or/c]. } @defproc[(symbols [sym symbol?] ...+) flat-contract?]{ Accepts any number of symbols and returns a flat contract that recognizes those symbols. This is a backwards compatibility constructor; it merely passes its arguments to @racket[or/c]. } @defproc[(vectorof [c contract?] [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care] [#:flat? flat? boolean? #f]) contract?]{ Returns a contract that recognizes vectors. The elements of the vector must match @racket[c]. 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 flat contracts will be unsound if applied to mutable vectors, as they will not check future operations on the vector. 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 chaperone contract, then the result will be a chaperone contract. 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 and a @tech{chaperone} or @tech{impersonator} of the input for mutable vectors.} @defproc[(vector-immutableof [c contract?]) contract?]{ Returns the same contract as @racket[(vectorof c #:immutable #t)]. This form exists for backwards compatibility.} @defproc[(vector/c [c contract?] ... [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care] [#:flat? flat? boolean? #f]) contract?]{ Returns a contract that recognizes vectors whose lengths match the number of 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 a flat contract, and the @racket[c] arguments must also be flat contracts. Such flat contracts will be unsound if applied to mutable vectors, as they will not check future operations on the vector. 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 are chaperone contracts, then the result will be a chaperone contract. 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 and a @tech{chaperone} or @tech{impersonator} of the input for mutable vectors.} @defproc[(vector-immutable/c [c contract?] ...) contract?]{ Returns the same contract as @racket[(vector/c c ... #:immutable #t)]. This form exists for reasons of backwards compatibility.} @defproc[(box/c [c contract?] [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care] [#:flat? flat? boolean? #f]) contract?]{ Returns a contract that recognizes boxes. The content of the box must match @racket[c]. 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 flat contracts will be unsound if applied to mutable boxes, as they will not check future operations on the box. 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 chaperone contract, then the result will be a chaperone contract. 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 and either a @tech{chaperone} or @tech{impersonator} of the input for mutable boxes.} @defproc[(box-immutable/c [c contract?]) contract?]{ Returns the same contract as @racket[(box/c c #:immutable #t)]. This form exists for reasons of backwards compatibility.} @defproc[(listof [c (or/c contract? (any/c . -> . any/c))]) contract?]{ Returns a contract that recognizes a list whose every element matches the contract @racket[c]. Beware that when this contract is applied to a value, the result is not necessarily @racket[eq?] to the input.} @defproc[(non-empty-listof [c (or/c contract? (any/c . -> . any/c))]) contract?]{ Returns a contract that recognizes non-empty lists whose elements match the contract @racket[c]. Beware that when this contract is applied to a value, the result is not necessarily @racket[eq?] to the input.} @defproc[(cons/c [car-c contract?] [cdr-c contract?]) contract?]{ Produces a contract that recognizes pairs whose first and second elements match @racket[car-c] and @racket[cdr-c], respectively. Beware that when this contract is applied to a value, the result is not necessarily @racket[eq?] to the input.} @defproc[(list/c [c (or/c contract? (any/c . -> . any/c))] ...) contract?]{ Produces a contract for a list. The number of elements in the list must match the number of arguments supplied to @racket[list/c], and each element of the list must match the corresponding contract. Beware that when this contract is applied to a value, the result is not necessarily @racket[eq?] to the input.} @defproc[(syntax/c [c flat-contract?]) flat-contract?]{ Produces a flat contract that recognizes syntax objects whose @racket[syntax-e] content matches @racket[c].} @defform[(struct/c struct-id contract-expr ...)]{ Produces a contract that recognizes instances of the structure type named by @racket[struct-id], and whose field values match the contracts produced by the @racket[contract-expr]s. Contracts for immutable fields must be either flat or chaperone contracts. Contracts for mutable fields may be impersonator contracts. If all fields are immutable and the @racket[contract-expr]s evaluate to flat contracts, a flat contract is produced. If all the @racket[contract-expr]s are chaperone contracts, a chaperone contract is produced. Otherwise, an impersonator contract is produced. } @defform/subs[(struct/dc struct-id field-spec ...) ([field-spec [field-name maybe-lazy contract-expr] [field-name (dep-field-name ...) maybe-lazy maybe-flat-or-impersonator maybe-dep-state contract-expr]] [field-name field-id (field-id #:parent struct-id)] [maybe-lazy (code:line) #:lazy] [maybe-flat-or-impersonator (code:line) #:flat #:impersonator] [maybe-dep-state (code:line) #:depends-on-state])]{ Produces a contract that recognizes instances of the structure type named by @racket[struct-id], and whose field values match the contracts produced by the @racket[field-spec]s. If the @racket[field-spec] lists the names of other fields, then the contract depends on values in those fields, and the @racket[contract-expr] expression is evaluated each time a selector is applied, building a new contract 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). If the field is a dependent field, then it is assumed that the contract is a chaperone, but not always a flat contract (and theus the entire @racket[struct/dc] contract is not a flat contract). If this is not the case, and the contract is always flat then the field must be annotated with the @racket[#:flat], or the field must be annotated with @racket[#:chaperone] (in which case, it must be a mutable field). If the @racket[#:lazy] keyword appears, then the contract on the field is check lazily (only when a selector is applied); @racket[#:lazy] contracts cannot be put on mutable fields. If a dependent contract depends on some mutable state, then use the @racket[#:depends-on-state] keyword argument (if a field's dependent contract depends on a mutable field, this keyword is automatically inferred). The presence of this keyword means that the contract expression is evaluated each time the corresponding field is accessed (or mutated, if it is a mutable field). Otherwise, the contract expression for a dependent field contract is evaluated when the contract is applied to a value. Contracts for immutable fields must be either flat or chaperone contracts. Contracts for mutable fields may be impersonator contracts. If all fields are immutable and the @racket[contract-expr]s evaluate to flat contracts, a flat contract is produced. If all the @racket[contract-expr]s are chaperone contracts, a chaperone contract is produced. Otherwise, an impersonator contract is produced. As an example, the function @racket[bst/c] below returns a contract for binary search trees whose values are all between @racket[lo] and @racket[hi]. The lazy annotations ensure that this contract does not change the running time of operations that do not inspect the entire tree. @racketblock[(struct bt (val left right)) (define (bst/c lo hi) (or/c #f (struct/dc bt [val (between/c lo hi)] [left (val) #:lazy (bst lo val)] [right (val) #:lazy (bst val hi)])))] } @defproc[(parameter/c [c contract?]) contract?]{ Produces a contract on parameters whose values must match @racket[contract].} @defproc[(procedure-arity-includes/c [n exact-nonnegative-integer?]) flat-contract?]{ Produces a contract for procedures that accept @racket[n] argument (i.e,. the @racket[procedure?] contract is implied).} @defproc[(hash/c [key chaperone-contract?] [val contract?] [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care] [#:flat? flat? boolean? #f]) contract?]{ Produces a contract that recognizes @racket[hash] tables with keys and values as specified by the @racket[key] and @racket[val] arguments. 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 contracts. Such flat contracts will be unsound if applied to mutable hash tables, as they will not check future operations on the hash table. If the @racket[immutable] argument is @racket[#t] and the @racket[key] and @racket[val] arguments are flat contracts, the result will be a flat contract. If either the domain or the range is a chaperone contract, then the result will be a chaperone contract. If the @racket[key] argument is a chaperone contract, then the resulting contract can only be applied to @racket[equal?]-based hash tables. When a higher-order @racket[hash/c] contract is applied to a hash table, the result is not @racket[eq?] to the input. The result will be a copy for immutable hash tables, and either a @tech{chaperone} or @tech{impersonator} of the input for mutable hash tables. } @defform/subs[#:literals (values) (prompt-tag/c contract ... maybe-call/cc) ([maybe-call/cc (code:line) (code:line #:call/cc contract) (code:line #:call/cc (values contract ...))]) #:contracts ([contract contract?])]{ Takes any number of contracts and returns a contract that recognizes continuation prompt tags and will check any aborts or prompt handlers that use the contracted prompt tag. Each @racket[contract] will check the corresponding value passed to an @racket[abort-current-continuation] and handled by the handler of a call to @racket[call-with-continuation-prompt]. If all of the @racket[contract]s are chaperone contracts, the resulting contract will also be a @tech{chaperone} contract. Otherwise, the contract is an @tech{impersonator} contract. If @racket[maybe-call/cc] is provided, then the provided contracts are used to check the return values from a continuation captured with @racket[call-with-current-continuation]. @examples[#:eval (contract-eval) (define/contract tag (prompt-tag/c (-> number? string?)) (make-continuation-prompt-tag)) (call-with-continuation-prompt (lambda () (number->string (call-with-composable-continuation (lambda (k) (abort-current-continuation tag k))))) tag (lambda (k) (k "not a number"))) ] } @defproc[(continuation-mark-key/c [contract contract?]) contract?]{ Takes a single contract and returns a contract that recognizes continuation marks and will check any mappings of marks to values or any accesses of the mark value. If the argument @racket[contract] is a chaperone contract, the resulting contract will also be a @tech{chaperone} contract. Otherwise, the contract is an @tech{impersonator} contract. @examples[#:eval (contract-eval) (define/contract mark-key (continuation-mark-key/c (-> symbol? (listof symbol?))) (make-continuation-mark-key)) (with-continuation-mark mark-key (lambda (s) (append s '(truffle fudge ganache))) (let ([mark-value (continuation-mark-set-first (current-continuation-marks) mark-key)]) (mark-value "chocolate-bar"))) ] } @defform[(flat-rec-contract id flat-contract-expr ...)]{ Constructs a recursive @tech{flat contract}. A @racket[flat-contract-expr] can refer to @racket[id] to refer recursively to the generated contract. For example, the contract @racketblock[ (flat-rec-contract sexp (cons/c sexp sexp) number? symbol?) ] is a flat contract that checks for (a limited form of) S-expressions. It says that a @racket[sexp] is either two @racket[sexp]s combined with @racket[cons], or a number, or a symbol. Note that if the contract is applied to a circular value, contract checking will not terminate.} @defform[(flat-murec-contract ([id flat-contract-expr ...] ...) body ...+)]{ A generalization of @racket[flat-rec-contract] for defining several mutually recursive flat contracts simultaneously. Each @racket[id] is visible in the entire @racket[flat-murec-contract] form, and the result of the final @racket[body] is the result of the entire form.} @defidform[any]{ Represents a contract that is always satisfied. In particular, it can accept multiple values. It can only be used in a result position of contracts like @racket[->]. Using @racket[any] elsewhere is a syntax error.} @defform[(promise/c expr)]{ Constructs a contract on a promise. The contract does not force the promise, but when the promise is forced, the contract checks that the result value meets the contract produced by @racket[expr].} @defproc[(flat-contract [predicate (any/c . -> . any/c)]) flat-contract?]{ Constructs a @tech{flat contract} from @racket[predicate]. A value satisfies the contract if the predicate returns a true value. This function is a holdover from before flat contracts could be used directly as predicates. It exists today for backwards compatibilty. } @defproc[(flat-contract-predicate [v flat-contract?]) (any/c . -> . any/c)]{ Extracts the predicate from a flat contract. This function is a holdover from before flat contracts could be used directly as predicates. It exists today for backwards compatibility. } @; ------------------------------------------------------------------------ @section[#:tag "function-contracts"]{Function Contracts} @declare-exporting-ctc[racket/contract/base] A @deftech{function contract} wraps a procedure to delay checks for its arguments and results. There are three primary function contract combinators that have increasing amounts of expressiveness and increasing additional overheads. The first @racket[->] is the cheapest. It generates wrapper functions that can call the original function directly. Contracts built with @racket[->*] require packaging up arguments as lists in the wrapper function and then using either @racket[keyword-apply] or @racket[apply]. Finally, @racket[->i] is the most expensive (along with @racket[->d]), because it requires delaying the evaluation of the contract expressions for the domain and range until the function itself is called or returns. The @racket[case->] contract is a specialized contract, designed to match @racket[case-lambda] and @racket[unconstrained-domain->] allows range checking without requiring that the domain have any particular shape (see below for an example use). @defform*/subs[#:literals (any values) [(-> dom ... range)] ([dom dom-expr (code:line keyword dom-expr)] [range range-expr (values range-expr ...) any])]{ Produces a contract for a function that accepts a fixed number of arguments and returns either a fixed number of results or completely unspecified results (the latter when @racket[any] is specified). Each @racket[dom-expr] is a contract on an argument to a function, and each @racket[range-expr] is a contract on a result of the function. @margin-note{Using a @racket[->] between two whitespace-delimited @racketparenfont{.}s is the same as putting the @racket[->] right after the enclosing opening parenthesis. See @guidesecref["lists-and-syntax"] or @secref["parse-pair"] for more information.} For example, @racketblock[(integer? boolean? . -> . integer?)] produces a contract on functions of two arguments. The first argument must be an integer, and the second argument must be a boolean. The function must produce an integer. A domain specification may include a keyword. If so, the function must accept corresponding (mandatory) keyword arguments, and the values for the keyword arguments must match the corresponding contracts. For example: @racketblock[(integer? #:x boolean? . -> . integer?)] is a contract on a function that accepts a by-position argument that is an integer and a @racket[#:x] argument that is a boolean. If @racket[any] is used as the last sub-form for @racket[->], no contract checking is performed on the result of the function, and thus any number of values is legal (even different numbers on different invocations of the function). If @racket[(values range-expr ...)] is used as the last sub-form of @racket[->], the function must produce a result for each contract, and each value must match its respective contract.} @defform*/subs[#:literals (any values) [(->* (mandatory-dom ...) optional-doms rest pre range post)] ([mandatory-dom dom-expr (code:line keyword dom-expr)] [optional-doms (code:line) (optional-dom ...)] [optional-dom dom-expr (code:line keyword dom-expr)] [rest (code:line) (code:line #:rest rest-expr)] [pre (code:line) (code:line #:pre pre-cond-expr)] [range range-expr (values range-expr ...) any] [post (code:line) (code:line #:post post-cond-expr)])]{ The @racket[->*] contract combinator produces contracts for functions that accept optional arguments (either keyword or positional) and/or arbitrarily many arguments. The first clause of a @racket[->*] contract describes the mandatory arguments, and is similar to the argument description of a @racket[->] contract. The second clause describes the optional arguments. The range of description can either be @racket[any] or a sequence of contracts, indicating that the function must return multiple values. If present, the @racket[rest-expr] contract governs the arguments in the rest parameter. Note that the @racket[rest-expr] contract governs only the arguments in the rest parameter, not those in mandatory arguments. For example, this contract: @racketblock[(->* () #:rest (cons/c integer? (listof integer?)) any)] does not match the function @racketblock[(λ (x . rest) x)] because the contract insists that the function accept zero arguments (because there are no mandatory arguments listed in the contract). The @racket[->i] contract does not know that the contract on the rest argument is going to end up disallowing empty argument lists. The @racket[pre-cond-expr] and @racket[post-cond-expr] expressions are checked as the function is called and returns, respectively, and allow checking of the environment without an explicit connection to an argument (or a result). As an example, the contract @racketblock[(->* () (boolean? #:x integer?) #:rest (listof symbol?) symbol?)] matches functions that optionally accept a boolean, an integer keyword argument @racket[#:x] and arbitrarily more symbols, and that return a symbol. } @defform*/subs[#:literals (any values) [(->i (mandatory-dependent-dom ...) dependent-rest pre-condition dep-range post-condition) (->i (mandatory-dependent-dom ...) (optional-dependent-dom ...) dependent-rest pre-condition dep-range post-condition)] ([mandatory-dependent-dom id+ctc (code:line keyword id+ctc)] [optional-dependent-dom id+ctc (code:line keyword id+ctc)] [dependent-rest (code:line) (code:line #:rest id+ctc)] [pre-condition (code:line) (code:line #:pre (id ...) boolean-expr pre-condition) (code:line #:pre/name (id ...) string boolean-expr pre-condition)] [dependent-range any id+ctc un+ctc (values id+ctc ...) (values un+ctc ...)] [post-condition (code:line) (code:line #:post (id ...) boolean-expr post-condition) (code:line #:post/name (id ...) string boolean-expr post-condition)] [id+ctc [id contract-expr] [id (id ...) contract-expr]] [un+ctc [_ contract-expr] [_ (id ...) contract-expr]] )]{ The @racket[->i] contract combinator differs from the @racket[->*] combinator in that the support pre- and post-condition clauses and in that each argument and result is named. These names can then be used in the subcontracts and in the pre-/post-condition clauses. In short, contracts now express dependencies among arguments and results. 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 rest-args contract, and an optional pre-condition. The pre-condition is introduced with the @racket[#:pre] keyword followed by the list of names on which it depends. If the @racket[#:pre/name] keyword is used, the string supplied is used as part of the error message; similarly with @racket[#:post/name]. The @racket[dep-range] non-terminal specifies the possible result contracts. If it is @racket[any], then any value is allowed. Otherwise, the result contract pairs a name and a contract or a multiple values return with names and contracts. In the last two cases, the range contract may be optionally followed by a post-condition; the post-condition expression is not allowed if the range contract is @racket[any]. Like the pre-condition, the post-condition must specify the variables on which it depends. Consider this sample contract: @racketblock[(->i ([x number?] [y (x) (>=/c x)]) [result (x y) (and/c number? (>=/c (+ x y)))])] It specifies a function of two arguments, both numbers. The contract on the second argument (@racket[y]) demands that it is greater than the first argument. The result contract promises a number that is greater than the sum of the two arguments. While the dependency specification for @racket[y] signals that the argument contract depends on the value of the first argument, the dependency sequence for @racket[result] indicates that the contract depends on both argument values. @margin-note*{In general, an empty sequence is (nearly) equivalent to not adding a sequence at all except that the former is more expensive than the latter.} Since the contract for @racket[x] does not depend on anything else, it does not come with any dependency sequence, not even @racket[()]. The contract expressions are not always evaluated in order. First, if there is no dependency for a given contract expression, the contract expression is evaluated at the time that the @racket[->i] expression is evaluated rather than the time when the function is called or returns. These dependency-free contract expressions are evaluated in the order in which they are listed. @; Second, the dependent contract sub-expressions are evaluated when the contracted function is called or returns in some order that satisfies the dependencies. That is, if a contract for an argument depends on the value of some other contract, the former is evaluated first (so that the argument, with its contract checked, is available for the other). When there is no dependency between two arguments (or the result and an argument), then the contract that appears earlier in the source text is evaluated first. Finally, if all of the identifier positions of the range contract are @racket[_]s (underscores), then the range contract expressions are evaluated when the function is called and the underscore is not bound in the range, after the argument contracts are evaluated and checked. Otherwise, the range expressions are evaluated when the function returns. If there are optional arguments that are not supplied, then the corresponding variables will be bound to a special value called @racket[the-unsupplied-arg] value. } @defform*/subs[#:literals (any values) [(->d (mandatory-dependent-dom ...) dependent-rest pre-condition dependent-range post-condition) (->d (mandatory-dependent-dom ...) (optional-dependent-dom ...) dependent-rest pre-condition dependent-range post-condition)] ([mandatory-dependent-dom [id dom-expr] (code:line keyword [id dom-expr])] [optional-dependent-dom [id dom-expr] (code:line keyword [id dom-expr])] [dependent-rest (code:line) (code:line #:rest id rest-expr)] [pre-condition (code:line) (code:line #:pre boolean-expr) (code:line #:pre-cond boolean-expr)] [dependent-range any [_ range-expr] (values [_ range-expr] ...) [id range-expr] (values [id range-expr] ...)] [post-condition (code:line) (code:line #:post-cond boolean-expr)] )]{ This contract is here for backwards compatibility; any new code should use @racket[->i] instead. This contract is similar to @racket[->i], but is ``lax'', meaning that it does not enforce contracts internally. For example, using this contract @racketblock[(->d ([f (-> integer? integer?)]) #:pre (zero? (f #f)) any)] will allow @racket[f] to be called with @racket[#f], trigger whatever bad behavior the author of @racket[f] was trying to prohibit by insisting that @racket[f]'s contract accept only integers. The @racket[#:pre-cond] and @racket[#:post-cond] keywords are aliases for @racket[#:pre] and @racket[#:post] and are provided for backwards compatibility. } @defform*/subs[#:literals (any values ->) [(case-> (-> dom-expr ... rest range) ...)] ([rest (code:line) (code:line #:rest rest-expr)] [range range-expr (values range-expr ...) any])]{ This contract form is designed to match @racket[case-lambda]. Each argument to @racket[case->] is a contract that governs a clause in the @racket[case-lambda]. If the @racket[#:rest] keyword is present, the corresponding clause must accept an arbitrary number of arguments. The @racket[range] specification is just like that for @racket[->] and @racket[->*]. } @defform[(unconstrained-domain-> range-expr ...)]{ Constructs a contract that accepts a function, but makes no constraint on the function's domain. The @racket[range-expr]s determine the number of results and the contract for each result. Generally, this contract must be combined with another contract to ensure that the domain is actually known to be able to safely call the function itself. For example, the contract @racketblock[ (provide (contract-out [f (->d ([size natural-number/c] [proc (and/c (unconstrained-domain-> number?) (lambda (p) (procedure-arity-includes? p size)))]) () [_ number?])])) ] says that the function @racket[f] accepts a natural number and a function. The domain of the function that @racket[f] accepts must include a case for @racket[size] arguments, meaning that @racket[f] can safely supply @racket[size] arguments to its input. For example, the following is a definition of @racket[f] that cannot be blamed using the above contract: @racketblock[ (define (f i g) (apply g (build-list i add1))) ]} @defthing[predicate/c contract?]{ Use this contract to indicate that some function is a predicate. It is semantically equivalent to @racket[(-> any/c boolean?)]. This contract also includes an optimization so that functions returning @racket[#t] from @racket[struct-predicate-procedure?] are just returned directly, without being wrapped. This contract is used by @racket[provide/contract]'s @racket[struct] subform so that struct predicates end up not being wrapped. } @defthing[the-unsupplied-arg unsupplied-arg?]{ Used by @racket[->i] (and @racket[->d]) to bind optional arguments that are not supplied by a call site. } @defproc[(unsupplied-arg? [v any/c]) boolean?]{ A predicate to determine whether @racket[v] is @racket[the-unsupplied-arg]. } @section[#:tag "parametric-contracts"]{Parametric Contracts} @defmodule*/no-declare[(racket/contract/parametric)] @declare-exporting-ctc[racket/contract/parametric] The most convenient way to use parametric contract is to use @racket[contract-out]'s @racket[#:exists] keyword. The @racketmodname[racket/contract/parametric] provides a few more, general-purpose parametric contracts. @defform[(parametric->/c (x ...) c)]{ Creates a contract for parametric polymorphic functions. Each function is protected by @racket[c], where each @racket[x] is bound in @racket[c] and refers to a polymorphic type that is instantiated each time the function is applied. At each application of a function, the @racket[parametric->/c] contract constructs a new opaque wrapper for each @racket[x]; values flowing into the polymorphic function (i.e. values protected by some @racket[x] in negative position with respect to @racket[parametric->/c]) are wrapped in the corresponding opaque wrapper. Values flowing out of the polymorphic function (i.e. values protected by some @racket[x] in positive position with respect to @racket[parametric->/c]) are checked for the appropriate wrapper. If they have it, they are unwrapped; if they do not, a contract violation is signaled. @examples[#:eval (contract-eval) (define/contract (check x y) (parametric->/c [X] (boolean? X . -> . X)) (if (or (not x) (equal? y 'surprise)) 'invalid y)) (check #t 'ok) (check #f 'ignored) (check #t 'surprise) ] } @defproc[(new-∀/c [name symbol?]) contract?]{ Constructs a new universal contract. 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). The name is used to identify the contract in error messages. For example, this contract: @racketblock[(let ([a (new-∀/c 'a)]) (-> a a))] describes the identity function (or a non-terminating function) That is, the first use of the @racket[a] appears in a negative position and thus inputs to that function are wrapped with an opaque struct. Then, when the function returns, it is checked to determine whether the result is wrapped, since the second @racket[a] appears in a positive position. The @racket[new-∀/c] construct constructor is dual to @racket[new-∃/c]. } @defproc[(new-∃/c [name symbol?]) contract?]{ Constructs a new existential contract. Existential contracts accept all values when in positive positions (e.g., function returns) and wrap them in an opaque struct, hiding the precise value. In negative positions (e.g. function inputs), they accepts only values that were previously accepted in positive positions (by checking for the wrappers). The name is used to identify the contract in error messages. For example, this contract: @racketblock[(let ([a (new-∃/c 'a)]) (-> (-> a a) any/c))] describes a function that accepts the identity function (or a non-terminating function) and returns an arbitrary value. That is, the first use of the @racket[a] appears in a positive position and thus inputs to that function are wrapped with an opaque struct. Then, when the function returns, it is checked to see if the result is wrapped, since the second @racket[a] appears in a negative position. The @racket[new-∃/c] construct constructor is dual to @racket[new-∀/c]. } @; ------------------------------------------------------------------------ @section{Lazy Data-structure Contracts} @defform[(contract-struct id (field-id ...))]{ @deprecated[@racket[struct]]{Lazy struct contracts no longer require a separate struct declaration; instead @racket[struct/dc] and @racket[struct/c] work directly with @racket[struct] and @racket[define-struct]. } Like @racket[struct], but with two differences: they do not define field mutators, and they define two contract constructors: @racket[id]@racketidfont{/c} and @racket[id]@racketidfont{/dc}. The first is a procedure that accepts as many arguments as there are fields and returns a contract for struct values whose fields match the arguments. The second is a syntactic form that also produces contracts on the structs, but the contracts on later fields may depend on the values of earlier fields. The generated contract combinators are @italic{lazy}: they only verify the contract holds for the portion of some data structure that is actually inspected. More precisely, a lazy data structure contract is not checked until a selector extracts a field of a struct. @specsubform/subs[ (#,(elem (racket id) (racketidfont "/dc")) field-spec ...) ([field-spec [field-id contract-expr] [field-id (field-id ...) contract-expr]]) ]{ In each @racket[field-spec] case, the first @racket[field-id] specifies which field the contract applies to; the fields must be specified in the same order as the original @racket[contract-struct]. The first case is for when the contract on the field does not depend on the value of any other field. The second case is for when the contract on the field does depend on some other fields, and the parenthesized @racket[field-id]s indicate which fields it depends on; these dependencies can only be to earlier fields.}} @defform[(define-contract-struct id (field-id ...))]{ @deprecated[@racket[struct]]{Lazy struct contracts no longer require a separate struct declaration; instead @racket[struct/dc] and @racket[struct/c] work directly with @racket[struct] and @racket[define-struct]. } Like @racket[contract-struct], but where the constructor's name is @racketidfont["make-"]@racket[id], much like @racket[define-struct]. } @; ------------------------------------------------------------------------ @include-section["contracts-struct-prop.scrbl"] @; ------------------------------------------------------------------------ @section[#:tag "attaching-contracts-to-values"]{Attaching Contracts to Values} @declare-exporting-ctc[racket/contract/base] @defform/subs[ #:literals (struct rename) (contract-out p/c-item ...) ([p/c-item (struct id ((id contract-expr) ...)) (struct (id identifier) ((id contract-expr) ...)) (rename orig-id id contract-expr) (id contract-expr) (code:line #:∃ poly-variables) (code:line #:exists poly-variables) (code:line #:∀ poly-variables) (code:line #:forall poly-variables)] [poly-variables identifier (identifier ...)])]{ A @racket[_provide-spec] for use in @racket[provide] (currently only for the same @tech{phase level} as the @racket[provide] form; for example, @racket[contract-out] cannot be nested within @racket[for-syntax]). Each @racket[id] is provided from the module. In addition, clients of the module must live up to the contract specified by @racket[contract-expr] for each export. The @racket[contract-out] form treats modules as units of blame. The module that defines the provided variable is expected to meet the positive (co-variant) positions of the contract. Each module that imports the provided variable must obey the negative (contra-variant) positions of the contract. Each @racket[contract-expr] in a @racket[contract-out] form is effectively moved to the end of the enclosing module, so a @racket[contract-expr] can refer to variables that are defined later in the same module. Only uses of the contracted variable outside the module are checked. Inside the module, no contract checking occurs. The @racket[rename] form of @racket[contract-out] exports the first variable (the internal name) with the name specified by the second variable (the external name). The @racket[struct] form of @racket[contract-out] provides a structure-type definition, and each field has a contract that dictates the contents of the fields. The structure-type definition must appear before the @racket[provide] clause within the enclosing module. If the structure type has a parent, the second @racket[struct] form (above) must be used, with the first name referring to the structure type to export and the second name referring to the parent structure type. Unlike a @racket[struct] definition, however, all of the fields (and their contracts) must be listed. The contract on the fields that the sub-struct shares with its parent are only used in the contract for the sub-struct's constructor, and the selector or mutators for the super-struct are not provided. The exported structure-type name always doubles as a constructor, even if the original structure-type name does not act as a constructor. The @racket[#:∃], @racket[#:exists], @racket[#:∀], and @racket[#:forall] clauses define new abstract contracts. The variables are bound in the remainder of the @racket[contract-out] form to new contracts that hide the values they accept and ensure that the exported functions are treated parametrically. See @racket[new-∃/c] and @racket[new-∀/c] for details on how the clauses hide the values. The implementation of @racket[contract-out] attaches uses @racket[syntax-property] to attach properties to the code it generates that records the syntax of the contracts in the fully expanded program. Specifically, the symbol @racket['provide/contract-original-contract] is bound to vectors of two elements, the exported identifier and a syntax object for the expression that produces the contract controlling the export. } @defform[(provide/contract p/c-item ...)]{ A legacy shorthand for @racket[(provide (contract-out p/c-item ...))], except that a @racket[_contract-expr] within @racket[provide/contract] is evaluated at the position of the @racket[provide/contract] form instead of at the end of the enclosing module.} @subsection{Nested Contract Boundaries} @defmodule*/no-declare[(racket/contract/region)] @declare-exporting-ctc[racket/contract/region] @defform*/subs[ [(with-contract blame-id (wc-export ...) free-var-list ... body ...+) (with-contract blame-id results-spec free-var-list ... body ...+)] ([wc-export (id contract-expr)] [result-spec (code:line #:result contract-expr) (code:line #:results (contract-expr ...))] [free-var-list (code:line) (code:line #:freevar id contract-expr) (code:line #:freevars ([id contract-expr] ...))])]{ Generates a local contract boundary. The first @racket[with-contract] form cannot appear in expression position. All names defined within the first @racket[with-contract] form are visible externally, but those names listed in the @racket[wc-export] list are protected with the corresponding contract. The @racket[body] of the form allows definition/expression interleaving if its context does. The second @racket[with-contract] form must appear in expression position. The final @racket[body] expression should return the same number of values as the number of contracts listed in the @racket[result-spec], and each returned value is contracted with its respective contract. The sequence of @racket[body] forms is treated as for @racket[let]. The @racket[blame-id] is used for the positive positions of contracts paired with exported @racket[id]s. Contracts broken within the @racket[with-contract] @racket[body] will use the @racket[blame-id] for their negative position. If a free-var-list is given, then any uses of the free variables inside the @racket[body] will be protected with contracts that blame the context of the @racket[with-contract] form for the positive positions and the @racket[with-contract] form for the negative ones.} @defform*[[(define/contract id contract-expr free-var-list init-value-expr) (define/contract (head args) contract-expr free-var-list body ...+)]]{ Works like @racket[define], except that the contract @racket[contract-expr] is attached to the bound value. For the definition of @racket[head] and @racket[args], see @racket[define]. For the definition of @racket[free-var-list], see @racket[with-contract]. The @racket[define/contract] form treats the individual definition as a contract region. The definition itself is responsible for positive (co-variant) positions of the contract, and references to @racket[id] outside of the definition must meet the negative positions of the contract. Since the contract boundary is between the definition and the surrounding context, references to @racket[id] inside the @racket[define/contract] form are not checked. If a free-var-list is given, then any uses of the free variables inside the @racket[body] will be protected with contracts that blame the context of the @racket[define/contract] form for the positive positions and the @racket[define/contract] form for the negative ones.} @defform*[[(define-struct/contract struct-id ([field contract-expr] ...) struct-option ...) (define-struct/contract (struct-id super-struct-id) ([field contract-expr] ...) struct-option ...)]]{ Works like @racket[define-struct], except that the arguments to the constructor, accessors, and mutators are protected by contracts. For the definitions of @racket[field] and @racket[struct-option], see @racket[define-struct]. The @racket[define-struct/contract] form only allows a subset of the @racket[struct-option] keywords: @racket[#:mutable], @racket[#:transparent], @racket[#:auto-value], @racket[#:omit-define-syntaxes], @racket[#:property] and @racket[#:omit-define-values]. @examples[#:eval (contract-eval) (define-struct/contract fish ([color number?])) (make-fish 5) (make-fish #f) (define-struct/contract (salmon fish) ([ocean symbol?])) (make-salmon 5 'atlantic) (make-salmon 5 #f) (make-salmon #f 'pacific) ]} @defidform[current-contract-region]{ Bound by @racket[define-syntax-parameter], this contains information about the current contract region, used by the above forms to determine the candidates for blame assignment. } @subsection{Low-level Contract Boundaries} @declare-exporting-ctc[racket/contract/base] @defform*[[(contract contract-expr to-protect-expr positive-blame-expr negative-blame-expr) (contract contract-expr to-protect-expr positive-blame-expr negative-blame-expr value-name-expr source-location-expr)]]{ The primitive mechanism for attaching a contract to a value. The purpose of @racket[contract] is as a target for the expansion of some higher-level contract specifying form. The @racket[contract] expression adds the contract specified by @racket[contract-expr] to the value produced by @racket[to-protect-expr]. The result of a @racket[contract] expression is the result of the @racket[to-protect-expr] expression, but with the contract specified by @racket[contract-expr] enforced on @racket[to-protect-expr]. The values of @racket[positive-blame-expr] and @racket[negative-blame-expr] indicate how to assign blame for positive and negative positions of the contract specified by @racket[contract-expr]. They may be any value, and are formatted as by @racket[display] for purposes of contract violation error messages. If specified, @racket[value-name-expr] indicates a name for the protected value to be used in error messages. If not supplied, or if @racket[value-name-expr] produces @racket[#f], no name is printed. Otherwise, it is also formatted as by @racket[display]. If specified, @racket[source-location-expr] indicates the source location reported by contract violations. The expression must produce a @racket[srcloc] structure, @tech{syntax object}, @racket[#f], or a list or vector in the format accepted by the third argument to @racket[datum->syntax]. } @; ------------------------------------------------------------------------ @section{Building New Contract Combinators} @defmodule*/no-declare[(racket/contract/combinator)] @declare-exporting-ctc[racket/contract/combinator] Contracts are represented internally as functions that accept information about the contract (who is to blame, source locations, @|etc|) and produce projections (in the spirit of Dana Scott) that enforce the contract. A projection is a function that accepts an arbitrary value, and returns a value that satisfies the corresponding contract. For example, a projection that accepts only integers corresponds to the contract @racket[(flat-contract integer?)], and can be written like this: @racketblock[ (define int-proj (lambda (x) (if (integer? x) x (signal-contract-violation)))) ] As a second example, a projection that accepts unary functions on integers looks like this: @racketblock[ (define int->int-proj (lambda (f) (if (and (procedure? f) (procedure-arity-includes? f 1)) (lambda (x) (int-proj (f (int-proj x)))) (signal-contract-violation)))) ] Although these projections have the right error behavior, they are not quite ready for use as contracts, because they do not accommodate blame, and do not provide good error messages. In order to accommodate these, contracts do not just use simple projections, but use functions that accept a @deftech{blame object} encapsulating the names of two parties that are the candidates for blame, as well as a record of the source location where the contract was established and the name of the contract. They can then, in turn, pass that information to @racket[raise-blame-error] to signal a good error message. Here is the first of those two projections, rewritten for use in the contract system: @racketblock[ (define (int-proj blame) (lambda (x) (if (integer? x) x (raise-blame-error blame val '(expected: "" given: "~e") val)))) ] The new argument specifies who is to be blamed for positive and negative contract violations. Contracts, in this system, are always established between two parties. One party provides some value according to the contract, and the other consumes the value, also according to the contract. The first is called the ``positive'' person and the second the ``negative''. So, in the case of just the integer contract, the only thing that can go wrong is that the value provided is not an integer. Thus, only the positive party can ever accrue blame. The @racket[raise-blame-error] function always blames the positive party. Compare that to the projection for our function contract: @racketblock[ (define (int->int-proj blame) (let ([dom (int-proj (blame-swap blame))] [rng (int-proj blame)]) (lambda (f) (if (and (procedure? f) (procedure-arity-includes? f 1)) (lambda (x) (rng (f (dom x)))) (raise-blame-error blame val '(expected "a procedure of one argument" given: "~e") val))))) ] In this case, the only explicit blame covers the situation where either a non-procedure is supplied to the contract or the procedure does not accept one argument. As with the integer projection, the blame here also lies with the producer of the value, which is why @racket[raise-blame-error] is passed @racket[blame] unchanged. The checking for the domain and range are delegated to the @racket[int-proj] function, which is supplied its arguments in the first two lines of the @racket[int->int-proj] function. The trick here is that, even though the @racket[int->int-proj] function always blames what it sees as positive, we can swap the blame parties by calling @racket[blame-swap] on the given @tech{blame object}, replacing the positive party with the negative party and vice versa. This technique is not merely a cheap trick to get the example to work, however. The reversal of the positive and the negative is a natural consequence of the way functions behave. That is, imagine the flow of values in a program between two modules. First, one module defines a function, and then that module is required by another. So, far the function itself has to go from the original, providing module to the requiring module. Now, imagine that the providing module invokes the function, supplying it an argument. At this point, the flow of values reverses. The argument is traveling back from the requiring module to the providing module! And finally, when the function produces a result, that result flows back in the original direction. Accordingly, the contract on the domain reverses the positive and the negative blame parties, just like the flow of values reverses. We can use this insight to generalize the function contracts and build a function that accepts any two contracts and returns a contract for functions between them. This projection also goes further and uses @racket[blame-add-context] to improve the error messages when a contract violation is detected. @racketblock[ (define (make-simple-function-contract dom-proj range-proj) (lambda (blame) (let ([dom (dom-proj (blame-add-context blame "the argument of" #:swap? #t))] [rng (range-proj (blame-add-context blame "the range of"))]) (lambda (f) (if (and (procedure? f) (procedure-arity-includes? f 1)) (lambda (x) (rng (f (dom x)))) (raise-blame-error blame val '(expected "a procedure of one argument" given: "~e") val)))))) ] Projections like the ones described above, but suited to other, new kinds of value you might make, can be used with the contract library primitives below. @deftogether[( @defproc[(make-contract [#:name name any/c 'anonymous-contract] [#:first-order test (-> any/c any/c) (λ (x) #t)] [#:projection proj (-> blame? (-> any/c any/c)) (λ (b) (λ (x) (if (test x) x (raise-blame-error b x '(expected: "~a" given: "~e") name x))))] [#:stronger stronger (or/c #f (-> contract? contract? boolean?)) #f]) contract?] @defproc[(make-chaperone-contract [#:name name any/c 'anonymous-chaperone-contract] [#:first-order test (-> any/c any/c) (λ (x) #t)] [#:projection proj (-> blame? (-> any/c any/c)) (λ (b) (λ (x) (if (test x) x (raise-blame-error b x '(expected: "~a" given: "~e") name x))))] [#:stronger stronger (or/c #f (-> contract? contract? boolean?)) #f]) chaperone-contract?] @defproc[(make-flat-contract [#:name name any/c 'anonymous-flat-contract] [#:first-order test (-> any/c any/c) (λ (x) #t)] [#:projection proj (-> blame? (-> any/c any/c)) (λ (b) (λ (x) (if (test x) x (raise-blame-error b x '(expected: "~a" given: "~e") name x))))] [#:stronger stronger (or/c #f (-> contract? contract? boolean?)) #f]) flat-contract?] )]{ These functions build simple higher-order contracts, chaperone contracts, and flat contracts, respectively. They both take the same set of three optional arguments: a name, a first-order predicate, and a blame-tracking projection. 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 higher-order contracts is @racketresult[anonymous-contract], for chaperone contracts is @racketresult[anonymous-chaperone-contract], and for flat contracts is @racketresult[anonymous-flat-contract]. The first-order predicate @racket[test] can be used to determine which values the contract applies to; usually, this is the set of values for which the contract fails immediately without any higher-order wrapping. This test is used by @racket[contract-first-order-passes?], and indirectly by @racket[or/c] to determine which of multiple higher-order contracts to wrap a value with. The default test accepts any value. The projection @racket[proj] defines the behavior of applying the contract. It is a curried function of two arguments: the first application accepts a blame object, and the second accepts a value to protect with the contract. The projection must either produce the value, suitably wrapped to enforce any higher-order aspects of the contract, or signal a contract violation using @racket[raise-blame-error]. The default projection produces an error when the first-order test fails, and produces the value unchanged otherwise. Projections for chaperone contracts must produce a value that passes @racket[chaperone-of?] when compared with the original, uncontracted value. Projections for flat contracts must fail precisely when the first-order test does, and must produce the input value unchanged otherwise. Applying a 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 separate projection only serves to provide more specific error messages. Most flat contracts do not need to supply an explicit projection. 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 was passed as the second argument to @racket[contract-stronger?]. @defexamples[#:eval (contract-eval) (define int/c (make-flat-contract #:name 'int/c #:first-order integer?)) (contract int/c 1 'positive 'negative) (contract int/c "not one" 'positive 'negative) (int/c 1) (int/c "not one") (define int->int/c (make-contract #:name 'int->int/c #:first-order (λ (x) (and (procedure? x) (procedure-arity-includes? x 1))) #:projection (λ (b) (let ([domain ((contract-projection int/c) (blame-swap b))] [range ((contract-projection int/c) b)]) (λ (f) (if (and (procedure? f) (procedure-arity-includes? f 1)) (λ (x) (range (f (domain x)))) (raise-blame-error b f '(expected "a function of one argument" 'given: "~e") f))))))) (contract int->int/c "not fun" 'positive 'negative) (define halve (contract int->int/c (λ (x) (/ x 2)) 'positive 'negative)) (halve 2) (halve 1/2) (halve 1) ] } @defproc[(build-compound-type-name [c/s any/c] ...) any]{ Produces an S-expression to be used as a name for a contract. The arguments should be either contracts or symbols. It wraps parentheses around its arguments and extracts the names from any contracts it is supplied with.} @defproc[(coerce-contract [id symbol?] [x any/c]) contract?]{ Converts a regular Racket value into an instance of a contract struct, converting it according to the description of @tech{contracts}. If @racket[x] is not one of the coercible values, @racket[coerce-contract] signals an error, using the first argument in the error message.} @defproc[(coerce-contracts [id symbol?] [xs (listof any/c)]) (listof contract?)]{ Coerces all of the arguments in 'xs' into contracts (via @racket[coerce-contract/f]) and signals an error if any of them are not contracts. The error messages assume that the function named by @racket[id] got @racket[xs] as its entire argument list. } @defproc[(coerce-chaperone-contract [id symbol?] [x any/c]) chaperone-contract?]{ Like @racket[coerce-contract], but requires the result to be a chaperone contract, not an arbitrary 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. } @defproc[(coerce-flat-contract [id symbol?] [x any/c]) flat-contract?]{ Like @racket[coerce-contract], but requires the result to be a flat contract, not an arbitrary contract. } @defproc[(coerce-flat-contracts [id symbol?] [x (listof any/c)]) (listof/c flat-contract?)]{ Like @racket[coerce-contracts], but requires the results to be flat contracts, not arbitrary contracts. } @defproc[(coerce-contract/f [x any/c]) (or/c contract? #f)]{ Like @racket[coerce-contract], but returns @racket[#f] if the value cannot be coerced to a contract. } @subsection{Blame Objects} @defproc[(blame? [x any/c]) boolean?]{ This predicate recognizes @tech{blame objects}. } @defproc[(blame-add-context [blame blame?] [context (or/c string? #f)] [#:important important (or/c string? #f) #f] [#:swap? swap? boolean? #f]) blame?]{ Adds some context information to blame error messages that explicates which portion of the contract failed (and that gets rendered by @racket[raise-blame-error]). The @racket[context] argument describes one layer of the portion of the contract, typically of the form @racket["the 1st argument of"] (in the case of a function contract) or @racket["a conjunct of"] (in the case of an @racket[and/c] contract). For example, consider this contract violation: @interaction[#:eval (contract-eval) (define/contract f (list/c (-> integer? integer?)) (list (λ (x) x))) ((car f) #f) ] It shows that the portion of the contract being violated is the first occurrence of @racket[integer?], because the @racket[->] and the @racket[list/c] combinators each internally called @racket[blame-add-context] to add the two lines following ``in'' in the error message. The @racket[important] argument is used to build the beginning part of the contract violation. The last @racket[important] argument that gets added to a blame object is used. The @racket[class/c] contract adds an important argument, as does the @racket[->] contract (when @racket[->] knows the name of the function getting the contract). The @racket[swap?] argument has the effect of calling @racket[blame-swap] while adding the layer of context, but without creating an extra blame object. The context information recorded in blame structs keeps track of combinators that do not add information, and add the string @racket["..."] for them, so programmers at least see that there was some context they are missing in the error messages. Accordingly, since there are combinators that should not add any context (e.g., @racket[recursive-contract]), passing @racket[#f] as the context string argument avoids adding the @racket["..."] string. } @deftogether[( @defproc[(blame-positive [b blame?]) any/c] @defproc[(blame-negative [b blame?]) any/c] )]{ These functions produce printable descriptions of the current positive and negative parties of a blame object. } @defproc[(blame-contract [b blame?]) any/c]{ This function produces a description of the contract associated with a blame object (the result of @racket[contract-name]). } @defproc[(blame-value [b blame?]) any/c]{ This function produces the name of the value to which the contract was applied, or @racket[#f] if no name was provided. } @defproc[(blame-source [b blame?]) srcloc?]{ This function produces the source location associated with a contract. If no source location was provided, all fields of the structure will contain @racket[#f]. } @defproc[(blame-swap [b blame?]) blame?]{ This function swaps the positive and negative parties of a @tech{blame object}. (See also @racket[blame-add-context].) } @deftogether[( @defproc[(blame-original? [b blame?]) boolean?] @defproc[(blame-swapped? [b blame?]) boolean?] )]{ These functions report whether the current blame of a given blame object is the same as in the original contract invocation (possibly of a compound contract containing the current one), or swapped, respectively. Each is the negation of the other; both are provided for convenience and clarity. } @defproc[(blame-replace-negative [b blame?] [neg any/c]) blame?]{ Produces a @racket[blame?] object just like @racket[b] except that it uses @racket[neg] instead of the negative position @racket[b] has. } @defproc[(raise-blame-error [b blame?] [x any/c] [fmt (or/c string? (listof (or/c string? 'given 'given: 'expected 'expected:)))] [v any/c] ...) none/c]{ Signals a contract violation. The first argument, @racket[b], records the current blame information, including positive and negative parties, the name of the contract, the name of the value, and the source location of the contract application. The second argument, @racket[x], is the value that failed to satisfy the contract. The remaining arguments are a format string, @racket[fmt], and its arguments, @racket[v ...], specifying an error message specific to the precise violation. If @racket[fmt] is a list, then the elements are concatenated together (with spaces added, unless there are already spaces at the ends of the strings), after first replacing symbols with either their string counterparts, or replacing @racket['given] with @racket["produced"] and @racket['expected] with @racket["promised"], depending on whether or not the @racket[b] argument has been swapped or not (see @racket[blame-swap]). If @racket[fmt] contains the symbols @racket['given:] or @racket['expected:], they are replaced like @racket['given:] and @racket['expected:] are, but the replacements are prefixed with the string @racket["\n "] to conform to the error message guidelines in @secref["err-msg-conventions"]. } @defstruct[(exn:fail:contract:blame exn:fail:contract) ([object blame?])]{ This exception is raised to signal a contract error. The @racket[object] field contains a @tech{blame object} associated with a contract violation. } @defparam[current-blame-format proc (-> blame? any/c string? string?)]{ A @tech{parameter} that is used when constructing a contract violation error. Its value is procedure that accepts three arguments: @itemize[ @item{the blame object for the violation,} @item{the value that the contract applies to, and} @item{a message indicating the kind of violation.}] The procedure then returns a string that is put into the contract error message. Note that the value is often already included in the message that indicates the violation. @defexamples[#:eval (contract-eval) (define (show-blame-error blame value message) (string-append "Contract Violation!\n" (format "Guilty Party: ~a\n" (blame-positive blame)) (format "Innocent Party: ~a\n" (blame-negative blame)) (format "Contracted Value Name: ~a\n" (blame-value blame)) (format "Contract Location: ~s\n" (blame-source blame)) (format "Contract Name: ~a\n" (blame-contract blame)) (format "Offending Value: ~s\n" value) (format "Offense: ~a\n" message))) (current-blame-format show-blame-error) (define/contract (f x) (-> integer? integer?) (/ x 2)) (f 2) (f 1) (f 1/2) ] } @subsection{Contracts as structs} @para{ The property @racket[prop:contract] allows arbitrary structures to act as contracts. The property @racket[prop:chaperone-contract] allows arbitrary structures to act as chaperone contracts; @racket[prop:chaperone-contract] inherits @racket[prop:contract], so chaperone contract structures may also act as general contracts. The property @racket[prop:flat-contract] allows arbitrary structures to act as flat contracts; @racket[prop:flat-contract] inherits both @racket[prop:chaperone-contract] and @racket[prop:procedure], so flat contract structures may also act as chaperone contracts, as general contracts, and as predicate procedures. } @deftogether[( @defthing[prop:contract struct-type-property?] @defthing[prop:chaperone-contract struct-type-property?] @defthing[prop:flat-contract struct-type-property?] )]{ These properties declare structures to be contracts or flat contracts, respectively. The value for @racket[prop:contract] must be a @tech{contract property} constructed by @racket[build-contract-property]; likewise, the value for @racket[prop:chaperone-contract] must be a @tech{chaperone contract property} constructed by @racket[build-chaperone-contract-property] and the value for @racket[prop:flat-contract] must be a @tech{flat contract property} constructed by @racket[build-flat-contract-property]. } @deftogether[( @defthing[prop:contracted struct-type-property?] @defthing[impersonator-prop:contracted impersonator-property?] )]{ These properties attach a contract value to the protected structure, chaperone, or impersonator value. The function @racket[has-contract?] returns @racket[#t] for values that have one of these properties, and @racket[value-contract] extracts the value from the property (which is expected to be the contract on the value). } @deftogether[( @defproc[(build-flat-contract-property [#:name get-name (-> contract? any/c) (λ (c) 'anonymous-flat-contract)] [#:first-order get-first-order (-> contract? (-> any/c boolean?)) (λ (c) (λ (x) #t))] [#:projection get-projection (-> contract? (-> blame? (-> any/c any/c))) (λ (c) (λ (b) (λ (x) (if ((get-first-order c) x) x (raise-blame-error b x '(expected: "~a" given: "~e") (get-name c) x)))))] [#:stronger stronger (or/c (-> contract? contract? boolean?) #f) #f] [#:generator generator (or/c (-> number? (listof (list any/c contract?)) any/c) #f) #f]) flat-contract-property?] @defproc[(build-chaperone-contract-property [#:name get-name (-> contract? any/c) (λ (c) 'anonymous-chaperone-contract)] [#:first-order get-first-order (-> contract? (-> any/c boolean?)) (λ (c) (λ (x) #t))] [#:projection get-projection (-> contract? (-> blame? (-> any/c any/c))) (λ (c) (λ (b) (λ (x) (if ((get-first-order c) x) x (raise-blame-error b x '(expected: "~a" given: "~e") (get-name c) x)))))] [#:stronger stronger (or/c (-> contract? contract? boolean?) #f) #f] [#:generator generator (or/c (-> number? (listof (list any/c contract?)) any/c) #f) #f]) chaperone-contract-property?] @defproc[(build-contract-property [#:name get-name (-> contract? any/c) (λ (c) 'anonymous-contract)] [#:first-order get-first-order (-> contract? (-> any/c boolean?)) (λ (c) (λ (x) #t))] [#:projection get-projection (-> contract? (-> blame? (-> any/c any/c))) (λ (c) (λ (b) (λ (x) (if ((get-first-order c) x) x (raise-blame-error b x '(expected: "~a" given: "~e") (get-name c) x)))))] [#:stronger stronger (or/c (-> contract? contract? boolean?) #f) #f] [#:generator generator (or/c (-> number? (listof (list any/c contract?)) any/c) #f) #f]) contract-property?] )]{ These functions build the arguments for @racket[prop:contract], @racket[prop:chaperone-contract], and @racket[prop:flat-contract], respectively. A @deftech{contract property} specifies the behavior of a structure when used as a contract. It is specified in terms of five accessors: @racket[get-name], which produces a description to @racket[write] as part of a contract violation; @racket[get-first-order], which produces a first-order predicate to be used by @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. These accessors are passed as (optional) keyword arguments to @racket[build-contract-property], and are applied to instances of the appropriate structure type by the contract system. Their results are used analogously to the arguments of @racket[make-contract]. A @deftech{chaperone contract property} specifies the behavior of a structure when used as a chaperone contract. It is specified using @racket[build-chaperone-contract-property], and accepts exactly the same set of arguments as @racket[build-contract-property]. The only difference is that the projection accessor must return a value that passes @racket[chaperone-of?] when compared with the original, uncontracted value. A @deftech{flat contract property} specifies the behavior of a structure when used as a flat contract. It is specified using @racket[build-flat-contract-property], and accepts exactly the same set of 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 fashion, analogous to the constraint on projections in @racket[make-flat-contract]. } @deftogether[( @defproc[(contract-property? [x any/c]) boolean?] @defproc[(chaperone-contract-property? [x any/c]) boolean?] @defproc[(flat-contract-property? [x any/c]) boolean?] )]{ These predicates detect whether a value is a @tech{contract property}, @tech{chaperone contract property}, or a @tech{flat contract property}, respectively. } @subsection{Obligation Information in Check Syntax} @seclink[#:doc '(lib "scribblings/drracket/drracket.scrbl") "buttons"]{Check Syntax} in DrRacket shows obligation information for contracts according to @racket[syntax-property]s that the contract combinators leave in the expanded form of the program. These properties indicate where contracts appear in the source and where the positive and negative positions of the contracts appear. To make Check Syntax show obligation information for your new contract combinators, use the following properties (some helper macros and functions are below): @itemize[@item{@racketblock0['racket/contract:contract : (vector/c symbol? (listof syntax?) (listof syntax?))] This property should be attached to the result of a transformer that implements a contract combinator. It signals to Check Syntax that this is where a contract begins. The first element in the vector should be a unique (in the sense of @racket[eq?]) value that Check Syntax can use a tag to match up this contract with its subpieces (specified by the two following syntax properties). The second and third elements of the vector are syntax objects from pieces of the contract, and Check Syntax will color them. The first list should contain subparts that are the responsibility of parties (typically modules) that provide implementations of the contract. The second list should contain subparts that are the responsibility of clients. For example, in @racket[(->* () #:pre #t any/c #:post #t)], the @racket[->*] and the @racket[#:post] should be in the first list and @racket[#:pre] in the second list.} @item{@racketblock0['racket/contract:negative-position : symbol?] This property should be attached to sub-expressions of a contract combinator that are expected to be other contracts. The value of the property should be the key (the first element from the vector for the @racket['racket/contract:contract] property) indicating which contract this is. This property should be used when the expression's value is a contract that clients are responsible for. } @item{@racketblock0['racket/contract:positive-position : symbol?] This form is just like @racket['racket/contract:negative-position], except that it should be used when the expression's value is a contract that the original party should be responsible for. } @item{@racketblock0['racket/contract:contract-on-boundary : symbol?] The presence of this property tells Check Syntax that it should start coloring from this point. It expects the expression to be a contract (and, thus, to have the @racket['racket/contract:contract] property); this property indicates that this contract is on a (module) boundary. (The value of the property is not used.) } @item{@racketblock0['racket/contract:internal-contract : symbol?] Like @racket['racket/contract:contract-on-boundary], the presence of this property triggers coloring, but this is meant for use when the party (module) containing the contract (regardless of whether or not this module exports anything matching the contract) can be blamed for violating the contract. This comes into play for @racket[->i] contracts, since the contract itself has access to values under contract via the dependency. } ] @defform/subs[(define/final-prop header body ...) ([header main-id (main-id id ...) (main-id id ... . id)])]{ The same as @racket[(define header body ...)], except that uses of @racket[main-id] in the header are annotated with the @racket['racket/contract:contract] property (as above). } @defform/subs[(define/subexpression-pos-prop header body ...) ([header main-id (main-id id ...) (main-id id ... . id)])]{ The same as @racket[(define header body ...)], except that uses of @racket[main-id] in the header are annotated with the @racket['racket/contract:contract] property (as above) and arguments are annotated with the @racket['racket/contract:positive-position] property. } @; ------------------------------------------------------------------------ @subsection{Utilities for Building New Combinators} @defproc[(contract-stronger? [x contract?] [y contract?]) boolean?]{ Returns @racket[#t] if the contract @racket[x] accepts either fewer or the same number of values as @racket[y] does. This function is conservative, so it may return @racket[#f] when @racket[x] does, in fact, accept fewer values. @examples[#:eval (contract-eval) (contract-stronger? integer? integer?) (contract-stronger? (between/c 25 75) (between/c 0 100)) (contract-stronger? (between/c 0 100) (between/c 25 75)) (contract-stronger? (between/c -10 0) (between/c 0 10)) (contract-stronger? (λ (x) (and (real? x) (<= x (random 10)))) (λ (x) (and (real? x) (<= x (+ 100 (random 10))))))] } @defproc[(contract-first-order-passes? [contract contract?] [v any/c]) boolean?]{ Returns a boolean indicating whether the first-order tests of @racket[contract] pass for @racket[v]. If it returns @racket[#f], the contract is guaranteed not to hold for that value; if it returns @racket[#t], the contract may or may not hold. If the contract is a first-order contract, a result of @racket[#t] guarantees that the contract holds.} @defproc[(contract-first-order [c contract?]) (-> any/c boolean?)]{ Produces the first-order test used by @racket[or/c] to match values to higher-order contracts. } @section[#:tag "contract-utilities"]{Contract Utilities} @declare-exporting-ctc[racket/contract/base] @defproc[(contract? [v any/c]) boolean?]{ Returns @racket[#t] if its argument is a contract (i.e., constructed with one of the combinators described in this section or a value that can be used as a contract) and @racket[#f] otherwise.} @defproc[(chaperone-contract? [v any/c]) boolean?]{ Returns @racket[#t] if its argument is a contract that guarantees that it returns a value which passes @racket[chaperone-of?] when compared to the original, uncontracted value.} @defproc[(impersonator-contract? [v any/c]) boolean?]{ Returns @racket[#t] if its argument is a contract that is not a chaperone contract nor a flat contract.} @defproc[(flat-contract? [v any/c]) boolean?]{ Returns @racket[#t] when its argument is a contract that can be checked immediately (unlike, say, a function contract). For example, @racket[flat-contract] constructs flat contracts from predicates, and symbols, booleans, numbers, and other ordinary Racket values (that are defined as @tech{contracts}) are also flat contracts.} @defproc[(contract-name [c contract?]) any/c]{ Produces the name used to describe the contract in error messages. } @defproc[(value-contract [v has-contract?]) contract?]{ Returns the contract attached to @racket[v], if recorded. Otherwise it returns @racket[#f]. To support @racket[value-contract] and @racket[has-contract?] in your own contract combinators, use @racket[prop:contracted] or @racket[impersonator-prop:contracted]. } @defproc[(has-contract? [v any/c]) boolean?]{ Returns @racket[#t] if @racket[v] is a value that has a recorded contract attached to it. See also @racket[value-contract]. } @defproc[(contract-projection [c contract?]) (-> blame? (-> any/c any/c))]{ Produces the projection defining a contract's behavior on protected values. } @defproc[(make-none/c [sexp-name any/c]) contract?]{ Makes a contract that accepts no values, and reports the name @racket[sexp-name] when signaling a contract violation.} @defform*[[(recursive-contract contract-expr) (recursive-contract contract-expr type)]]{ Delays the evaluation of its argument until the contract is checked, making recursive contracts possible. If @racket[type] is given, it describes the expected type of contract and must be one of the keywords @racket[#:impersonator], @racket[#:chaperone], or @racket[#:flat]. If @racket[type] is not given, an impersonator contract is created.} @defform[(opt/c contract-expr)]{ This optimizes its argument contract expression by traversing its syntax and, for known contract combinators, fuses them into a single contract combinator that avoids as much allocation overhead as possible. The result is a contract that should behave identically to its argument, except faster (due to less allocation).} @defform[(define-opt/c (id id ...) expr)]{ This defines a recursive contract and simultaneously optimizes it. Semantically, it behaves just as if the @racket[-opt/c] were not present, defining a function on contracts (except that the body expression must return a contract). But, it also optimizes that contract definition, avoiding extra allocation, much like @racket[opt/c] does. For example, @racketblock[ (define-contract-struct bt (val left right)) (define-opt/c (bst-between/c lo hi) (or/c null? (bt/c [val (real-in lo hi)] [left (val) (bst-between/c lo val)] [right (val) (bst-between/c val hi)]))) (define bst/c (bst-between/c -inf.0 +inf.0)) ] defines the @racket[bst/c] contract that checks the binary 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] [proj (or/c (-> any/c any/c (list/c any/c any/c) contact? (-> any/c any/c)) (-> any/c any/c (list/c any/c any/c) contact? boolean? (-> any/c any/c)))] [first-order (-> any/c boolean?)]) contract?]{ Builds a contract using an old interface. Modulo errors, it is equivalent to: @racketblock[(make-contract #:name name #:first-order first-order #:projection (cond [(procedure-arity-includes? proj 5) (lambda (blame) (proj (blame-positive blame) (blame-negative blame) (list (blame-source blame) (blame-value blame)) (blame-contract blame) (not (blame-swapped? blame))))] [(procedure-arity-includes? proj 4) (lambda (blame) (proj (blame-positive blame) (blame-negative blame) (list (blame-source blame) (blame-value blame)) (blame-contract blame)))]))] } @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. The @racket[fmt] string and following arguments are passed to @racket[format] and used as the string in the error message. } @defproc[(contract-proc [c contract?]) (->* (symbol? symbol? (or/c syntax? (list/c any/c any/c))) (boolean?) (-> any/c any))]{ Constructs an old-style projection from a contract. The resulting function accepts the information that is in a @racket[blame] struct and returns a projection function that checks the contract. } @section{Random generation} @defproc[(contract-random-generate [ctc contract?] [fuel int?] [fail (-> any/c) (λ () (error ...))]) any/c]{ Attempts to randomly generate a value which will match the contract. The fuel argument limits how hard the generator tries to generate a value matching the contract and is a rough limit of the size of the resulting value. The generator may fail to generate a contract, either because some contracts do not have corresponding generators (for example, not all predicates have generators) or because there is not enough fuel. In either case, the thunk @racket[fail] is invoked. }