7.2 Function Contracts

A 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 -> is the cheapest. It generates wrapper functions that can call the original function directly. Contracts built with ->* require packaging up arguments as lists in the wrapper function and then using either keyword-apply or apply. Finally, ->d is the most expensive, because it requires delaying the evaluation of the contract expressions for the domain and range until the function itself is called or returns.

The case-> contract is a specialized contract, designed to match case-lambda and unconstrained-domain-> allows range checking without requiring that the domain have any particular shape (see below for an exmaple use).

(-> dom ... range)

dom   =   dom-expr     |   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 any is specified).

Each dom-expr is a contract on an argument to a function, and each res-expr is a contract on a result of the function.

Using an -> between two whitespace-delimited .s is the same as putting the -> right after the enclosing open parenthesis. See Lists and Scheme Syntax or Reading Pairs and Lists for more information.

For example,

  (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:

  (integer? #:x boolean? . -> . integer?)

is a contract on a function that accepts a by-position argument that is an integer and a #:x argument is that a boolean.

If any is used as the last sub-form for ->, no contract checking is performed on the result of the function, and tail-recursion is preserved. Note that the function may return multiple values in that case.

If (values res-expr ...) is used as the last sub-form of ->, the function must produce a result for each contract, and each values must match its respective contract.

(->* (mandatory-dom ...) (optional-dom ...) rest range)

mandatory-dom   =   dom-expr     |   keyword dom-expr           optional-dom   =   dom-expr     |   keyword dom-expr           rest   =       |   #:rest rest-expr           range   =   range-expr     |   (values range-expr ...)     |   any

The ->* contract combinator produces contracts for functions that accept optional arguments (either keyword or positional) and or arbitrarily many arguments. The first clause of a ->* contract describes the mandatory arguments, and is similar to the argument description of a -> contract. The second clause describes the optional arguments. The last clause describes the range of the function. It can either be any or a sequence of contracts, indicating that the function must return multiple values. If present, the rest-expr contract governs the arguments in the rest parameter.

As an example, the contract

  (->* () (boolean? #:x integer?) #:rest (listof symbol?) (symbol?))

matches functions that optionally accept a boolean, an integer keyword argument #:x and arbitrarily more symbols, and that return a symbol.

(->d (mandatory-dependent-dom ...)      (optional-dependent-dom ...)      dependent-rest      pre-cond      dep-range)

mandatory-dependent-dom   =   [id dom-expr]     |   keyword [id dom-expr]           optional-dependent-dom   =   [id dom-expr]     |   keyword [id dom-expr]           dependent-rest   =       |   #:rest id rest-expr           pre-cond   =       |   #:pre-cond boolean-expr           dep-range   =   any     |   [_ range-expr] post-cond     |   (values [_ range-expr] ...) post-cond     |   [id range-expr] post-cond     |   (values [id range-expr] ...) post-cond           post-cond   =       |   #:post-cond boolean-expr

The ->d is similar in shape to ->*, with two extensions: names have been added to each argument and result, which allows the contracts to depend on the values of the arguments and results, and pre- and post-condition expressions have been added in order to express contracts that are not naturally tied to a particular argument or result.

The first two subforms of a ->d contract cover the mandatory and optional arguments. Following that is an optional rest-args contract, and an optional pre-condition. The dep-range non-terminal covers the possible post-condition contracts. If it is any, then any result (or results) are allowed. Otherwise, the result contract can be a name and a result contract, or a multiple values return and, in either of the last two cases, it may be optionally followed by a post-condition.

Each of the ids on an argument (including the rest argument) is visible in all of the sub-expressions of ->d. Each of the ids on a result is visible in the subexpressions of the dep-range.

If the identifier position of the range contract is _ (an underscore), then the range contract expressions are evaluated when the function is called (and the underscore is not bound in the range). Otherwise the range expressions are evaluated when the function returns.

(case-> (-> dom-expr ... rest range) ...)

rest   =       |   #:rest rest-expr           range   =   range-expr     |   (values range-expr ...)     |   any

This contract form is designed to match case-lambda. Each argument to case-> is a contract that governs a clause in the case-lambda. If the #:rest keyword is present, the corresponding clause must accept an arbitrary number of arguments. The range specification is just like that for -> and ->*.

(unconstrained-domain-> res-expr ...)

Constructs a contract that accepts a function, but makes no constraint on the function’s domain. The res-exprs 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

(provide/contract

[f (->d ([size natural-number/c]

[proc (and/c (unconstrained-domain-> number?)

(lambda (p)

(procedure-arity-includes? p size)))])

()

number?)])

says that the function f accepts a natural number and a function. The domain of the function that f accepts must include a case for size arguments, meaning that f can safely supply size arguments to its input.

For example, the following is a definition of f that cannot be blamed using the above contract:

(define (f i g)

(apply g (build-list i add1)))