8.7 Building New Contract Combinators

The name argument is any value to be rendered using display to describe the contract when a violation occurs. The default name for simple higher-order contracts is anonymous-contract, for chaperone contracts is anonymous-chaperone-contract, and for flat contracts is anonymous-flat-contract.

The first-order predicate 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 contract-first-order-passes?, and indirectly by or/c to determine which of multiple higher-order contracts to wrap a value with. The default test accepts any value.

The late-neg-proj defines the behavior of applying the contract. If it is supplied, it accepts a blame object that does not have a value for the blame-negative field. Then it must return a function that accepts both the value that is getting the contract and the name of the blame party, in that order. The result must either be the value (perhaps suitably wrapped with a chaperone or impersonator to enforce the contract), or signal a contract violation using raise-blame-error. The default is #f.

The projection proj and val-first-proj are older mechanisms for defining the behavior of applying the contract. The proj argument 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 raise-blame-error. The default projection produces an error when the first-order test fails, and produces the value unchanged otherwise. The val-first-proj is like late-neg-proj, except with an extra layer of currying.

Projections for chaperone contracts must produce a value that passes 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 stronger argument is used to implement contract-stronger?. The first argument is always the contract itself and the second argument is whatever was passed as the second argument to contract-stronger?.

The is-list-contract? argument is used by the list-contract? predicate to determine if this is a contract that accepts only list? values.

Changed in version 6.0.1.13 of package base: Added the #:list-contract? argument.

If x is not one of the coercible values, coerce-contract signals an error, using the first argument in the error message.

See make-contract for more details.

Added in version 6.1.1.5 of package base.

8.7.1 Blame Objects

The context argument describes one layer of the portion of the contract, typically of the form "the 1st argument of" (in the case of a function contract) or "a conjunct of" (in the case of an and/c contract).

The important argument is used to build the beginning part of the contract violation. The last important argument that gets added to a blame object is used. The class/c contract adds an important argument, as does the -> contract (when -> knows the name of the function getting the contract).

The swap? argument has the effect of calling 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 "..." 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., recursive-contract), passing #f as the context string argument avoids adding the "..." string.

The remaining arguments are a format string, fmt, and its arguments, v ..., specifying an error message specific to the precise violation.

If 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 'given with "produced" and 'expected with "promised", depending on whether or not the b argument has been swapped or not (see blame-swap).

If fmt contains the symbols 'given: or 'expected:, they are replaced like 'given: and 'expected: are, but the replacements are prefixed with the string "\n  " to conform to the error message guidelines in Error Message Conventions.

8.7.2 Contracts as structs

The property prop:contract allows arbitrary structures to act as contracts. The property prop:chaperone-contract allows arbitrary structures to act as chaperone contracts; prop:chaperone-contract inherits prop:contract, so chaperone contract structures may also act as general contracts. The property prop:flat-contract allows arbitrary structures to act as flat contracts; prop:flat-contract inherits both prop:chaperone-contract and prop:procedure, so flat contract structures may also act as chaperone contracts, as general contracts, and as predicate procedures.

These functions build the arguments for prop:contract, prop:chaperone-contract, and prop:flat-contract, respectively.

A contract property specifies the behavior of a structure when used as a contract. It is specified in terms of five accessors: get-name, which produces a description to write as part of a contract violation; get-first-order, which produces a first-order predicate to be used by contract-first-order-passes?; get-projection, which produces a blame-tracking projection defining the behavior of the contract; 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); generate, which returns a thunk that generates random values matching the contract (using contract-random-generate-fail) to indicate failure) or #f to indicate that random generation for this contract isn’t supported; exercise, which returns a function that exercises values matching the contract (e.g., if it is a function contract, it may call the function) and a list of contracts whose values will be generated by this process; and is-flat-contract?, which is used by flat-contract? to determine if this contract accepts only list?s.

These accessors are passed as (optional) keyword arguments to 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 make-contract.

A chaperone contract property specifies the behavior of a structure when used as a chaperone contract. It is specified using build-chaperone-contract-property, and accepts exactly the same set of arguments as build-contract-property. The only difference is that the projection accessor must return a value that passes chaperone-of? when compared with the original, uncontracted value.

A flat contract property specifies the behavior of a structure when used as a flat contract. It is specified using build-flat-contract-property, and accepts exactly the same set of arguments as 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 make-flat-contract.

Changed in version 6.0.1.13 of package base: Added the #:list-contract? argument. Changed in version 6.1.1.4: Allow generate to return contract-random-generate-fail

8.7.3 Obligation Information in Check Syntax

Check Syntax in DrRacket shows obligation information for contracts according to syntax-propertys 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):

• '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 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 (->* () #:pre #t any/c #:post #t), the ->* and the #:post should be in the first list and #:pre in the second list.

• '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/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.

• 'racket/contract:positive-position : symbol?
  This form is just like '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.

• '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/contract:contract property); this property indicates that this contract is on a (module) boundary.

  (The value of the property is not used.)

• 'racket/contract:internal-contract : symbol?

  Like '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 ->i contracts, since the contract itself has access to values under contract via the dependency.

8.7.4 Utilities for Building New Combinators

This function is conservative, so it may return #f when x does, in fact, accept fewer values.

If it returns #f, the contract is guaranteed not to hold for that value; if it returns #t, the contract may or may not hold. If the contract is a first-order contract, a result of #t guarantees that the contract holds.