#lang scribble/manual

@; To compile this:
@;   1) Create a package development link:
@;          raco planet link cobbe bcond.plt 1 0 bcond
@;   2) Create the package
@;          raco planet create bcond
@;   3) Install the package
@;          raco planet fileinject cobbe bcond.plt 1 0

@(require (for-label racket)
          (for-label (planet cobbe/contract-utils:4/contract-utils)))

@title{@bold{Contract-Utils}: Various contract functions and utilities}

Version 4.0, December 2010

Richard Cobbe <cobbe at ccs dot neu dot edu>

@defmodule[(planet cobbe/contract-utils:4/contract-utils)]

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

@section{Flat Contracts}

@defthing[sexp/c flat-contract?]{
A flat contract that accepts arbitrary S-expressions.  Here, an S-expression is
any of
@itemlist[
  @item{the empty list}
  @item{a number}
  @item{a symbol}
  @item{a string}
  @item{a Boolean}
  @item{a character}
  @item{a cons cell containing two S-expressions}]}

@defthing[positive-int/c flat-contract?]{
A contract that accepts strictly positive integers.}

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

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

@defproc[(listof-unique-compare/c [cmp comparison/c]) contract?]{
Like @racket[listof-unique/c], but uses the order function @racket[cmp] to
determine equality for members of the list.}

@defthing[immutable-string/c flat-contract?]{
A contract that accepts immutable strings.  (Historically useful for writing
contracts for substructures of @racket[exn], although this is no longer as
important.)}

@section{Higher-Order Contracts}

@defthing[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.}

@defproc[(binary-predicate/c [arg/c contract?]) contract?]{
Returns a contract for a function that accepts two arguments (each of which
must match the contract @racket[arg/c]) and returns a Boolean.}

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

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

@defproc[(optional/c [c contract?]) contract?]{
Produces a contract that accepts an optional value---that is, all values that
@racket[c] accepts, as well as @racket[#f].  The result is a flat contract if
and only if @racket[c] is a flat contract or a predicate.}

@defthing[contract/c contract?]{
A contract that accepts contracts and (unary) predicates.
}

@defthing[flat-contract/c contract?]{
A contract that accepts flat contracts and (unary) predicates.
}

@section{Contract Utilities}

@defproc[(contract-of [contract-or-predicate contract/c]) contract?]{
Wraps a predicate in a flat contract and leaves contracts unchanged.}

@defproc[(predicate-of [flat-contract-or-predicate flat-contract/c])
         predicate/c]{
Extracts a flat contract's predicate and leaves predicates unchanged.}

@defform[(eta function)]{
Eta-expands @racket[function].  That is, it expands to
@racketblock[(lambda args (apply function args))]  This is useful primarily for
writing contract specifications that appear before their predicate
definitions.}

@section{Acknowledgments}

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

@section{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:
@itemlist[
    @item{Redistributions of source code must retain the above
    copyright notice, this list of conditions and the following
    disclaimer.}
    @item{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.}
    @item{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.