►Contract-Utils: Various contract functions and utilities
1 Flat Contracts
sexp/ c
positive-int/ c
nelistof/ c
listof-unique/ c
listof-unique-compare/ c
immutable-string/ c
2 Higher-Order Contracts
predicate/ c
binary-predicate/ c
equality/ c
comparison/ c
optional/ c
contract/ c
flat-contract/ c
3 Contract Utilities
contract-of
predicate-of
eta
4 Acknowledgments
5 Copyright and License
Version: 5.0.99.5

Contract-Utils: Various contract functions and utilities

Version 4.0, December 2010

Richard Cobbe <cobbe at ccs dot neu dot edu>

 (require (planet cobbe/contract-utils:4/contract-utils))

This module provides several general-purpose contracts and contract utilities.

1 Flat Contracts

sexp/c : flat-contract?
A flat contract that accepts arbitrary S-expressions. Here, an S-expression is any of

  • the empty list

  • a number

  • a symbol

  • a string

  • a Boolean

  • a character

  • a cons cell containing two S-expressions

positive-int/c : flat-contract?
A contract that accepts strictly positive integers.

(nelistof/c c) → contract?
  c : flat-contract/c
Returns a contract that accepts non-empty lists whose every element matches the contract c. As with listof, when this contract is applied to a value, the result is not necessarily eq? to the input.

(listof-unique/c elt=?) → flat-contract?
  elt=? : (any/c any/c . -> . boolean?)
Returns a contract that accepts lists whose elements are unique according to the equality predicate elt=?. As with listof and nelistof/c, the resulting contracts do not necessarily preserve object identity. Additionally, the resulting contract may apply elt=? to individual elements and pairs of elements arbitrarily many times.

(listof-unique-compare/c cmp) → contract?
  cmp : comparison/c
Like listof-unique/c, but uses the order function cmp to determine equality for members of the list.

immutable-string/c : flat-contract?
A contract that accepts immutable strings. (Historically useful for writing contracts for substructures of exn, although this is no longer as important.)

2 Higher-Order Contracts

predicate/c : contract?
A contract that accepts predicate functions. A predicate function is a function which accepts any single value and always produces a Boolean result.

(binary-predicate/c arg/c) → contract?
  arg/c : contract?
Returns a contract for a function that accepts two arguments (each of which must match the contract arg/c) and returns a Boolean.

(equality/c arg/c) → contract?
  arg/c : contract?
Returns a contract for a function that accepts two arguments (each of which must match the contract arg/c) and returns a Boolean. For now, this this function is equivalent to binary-predicate/c, but in later releases, we may modify equality/c to check for additional properties of equivalence relations, like reflexivity.

(comparison/c arg/c) → contract?
  arg/c : contract?
Returns a contract for a SRFI-67-style comparison functions: functions that accept two arguments (each of which must match the contract arg/c) and return one of 1, 0, or -1. We may eventually extend this to check for other desirable properties, like order reflexivity and anti-symmetry.

(optional/c c) → contract?
  c : contract?
Produces a contract that accepts an optional value—that is, all values that c accepts, as well as #f. The result is a flat contract if and only if c is a flat contract or a predicate.

contract/c : contract?
A contract that accepts contracts and (unary) predicates.

flat-contract/c : contract?
A contract that accepts flat contracts and (unary) predicates.

3 Contract Utilities

(contract-of contract-or-predicate) → contract?
  contract-or-predicate : contract/c
Wraps a predicate in a flat contract and leaves contracts unchanged.

(predicate-of flat-contract-or-predicate) → predicate/c
  flat-contract-or-predicate : flat-contract/c
Extracts a flat contract’s predicate and leaves predicates unchanged.

(eta function)
Eta-expands function. That is, it expands to
  (lambda args (apply function args))
This is useful primarily for writing contract specifications that appear before their predicate definitions.

4 Acknowledgments

Thanks to Carl Eastlund for contract/c, flat-contract/c, contract-of, predicate-of, listof-unique/c, listof-unique-compare/c, equality/c, comparison/c.

5 Copyright and License

This work is copyrighted and distributed under the terms of the Modified BSD License, included below.

Copyright (c) 2005-2010, Richard Cobbe.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • The name of Richard Cobbe may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RICHARD COBBE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.