The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Class-Agreement-0.02
River stage zero No dependents
++
/ Class::Agreement

NAME

Class::Agreement - add contracts to your Perl classes easily

SYNOPSIS

    package SomeClass;
    
    use Class::Agreement;
    
    # use base 'Class::Accessor' or 'Class::MethodMaker',
    # or roll your own:
    sub new { ... }

    invariant {
        my ($self) = @_;
        $self->count > 0;
    };
    
    precondition add_a_positive => sub {
        my ( $self, $value ) = @_;
        return ( $value >= 0 );
    };
    sub add_a_positive {
        my ( $self, $value ) = @_;
        ...
    }
    
    sub choose_word {
        my ( $self, $value ) = @_;
        ...
    }
    postcondition choose_word => sub {
        return ( result >= 0 );
    };
    
    dependent increase_foo => sub {
        my ( $self, $amount ) = @_;
        my $old_foo = $self->foo;
        return sub {
          my ( $self, $amount ) = @_;
          return ( $old_foo < $self->get_foo );
        }
    };
    sub increase_foo {
        my ( $self, $amount ) = @_;
        $self->set_foo( $self->get_foo + $amount );
    }

DESCRIPTION

Class::Agreement is an implementation of behavioral contracts for Perl5. This module allows you to easily add pre- and postconditions to new or existing Perl classes.

This module provides contracts such as dependent contracts, contracts for higher-order functions, and informative messages when things fail. At the time of this writing, Class::Agreement is one of only two contract implementations that blames contract-breaking components correctly. (See: "Object-oriented Programming Languages Need Well-founded Contracts" at http://citeseer.ist.psu.edu/findler01objectoriented.html.)

Using Class::Agreement lets you specify proper input and output of your functions or methods, thus strengthening your code and allowing you to spot bugs earlier.

Comparison with Class::Contract

Class::Contract requires you to use its own object and accessor system, which makes the addition of contracts to existing code difficult. In contrast, it should be easy to implement contracts with Class::Agreement no matter what object system (Class::Accessor, Class::MethodMaker, Spiffy, etc.) you use.

Class::Contract also clones objects every time you add a postcondition, which can get pretty expensive. Class::Agreement doesn't clone -- alternatively, it provides you with dependent contracts so that you can use closure to keep track of only the values you care about. (See "Testing old values".)

Comparison with Eiffel

You could say that Class::Agreement gives you Perl equivalents of Eiffel's require, ensures, invariant and (indirectly) old keywords. For example, the following Eiffel method:

    decrement is
        require
            item > 0
        do
            item := item - 1
        ensure
            item = old item - 1
        end

...could be written in Perl as:

    use Class::Contract;
    ...
    
    precondition decrement => sub { shift()->item > 0 }

    sub decrement {
        my ( $self ) = @_;
        $self->item( $self->item - 1 );
    }

    dependent decrement => sub {
        my ( $self ) = @_;
        my $old_item = $self->item;
        return sub { $self->item == $old_item - 1 };
    };

EXPORT

The following functions are exported by default:

  • precondition, postcondition, and dependent, each of which have two distinct calling syntaxes: one for functional programming and one for object-oriented.

  • result, which should only be used within postconditions or functions returned by dependent contracts.

  • invariant and specify_constructors, both of which are used only in object-oriented programming.

All exported functions are described in the following section, "FUNCTIONS".

FUNCTIONS

precondition NAME, BLOCK

Specify that the method NAME must meet the precondition as specified in BLOCK.

In BLOCK, the variable @_ will be the argument list of the method. (The first item of @_ will be the class name or object, as usual.)

For example, to specify a precondition on a method to ensure that the first argument given is greater than zero:

    precondition foo => sub {
        my ( $self, $value ) = @_;
        return ( $value >= 0 );
    };
    sub foo {
        my ( $self, $value ) = @_;
        ...
    }

With methods, if the precondition fails (returns false), preconditions for the parent class will be checked. If the preconditions for both the child's method and the parent's method fail, the input to the method must have been invalid. If the precondition for the parent passes, the hierarchy between the class and the parent class is incorrect because, to fulfill the Liskov-Wing principal of substitutability, the subclass' method should accept that the superclass' does, and optionally more. Note that only the relationships between child and parent classes are checked -- this module won't traverse the complete ancestry of a class.

You can use this keyword multiple times to declare multiple preconditions on the given method.

precondition VARIABLE, BLOCK

Specify that, when called, the subroutine reference pointed to by the lvalue VARIABLE must meet the precondition as specified in BLOCK.

In BLOCK, the variable @_ will be the argument list of the subroutine.

There are times when you will have a function or method that accepts another function as an argument. Say that you have a function g() that accepts another function, f(), as its argument. However, the argument given to f() must be greater than zero:

    sub g {
        my ($f) = @_;
        precondition $f => sub { 
            my ($value) = @_;
            return ( $value >= 0 );
        };
        $f->(15); # will pass
        $f->(-3); # will fail
    }

If called in void context this function will modify VARIABLE to point to a new subroutine reference with the precondition. If called in scalar context, this function will return a new function with the attached precondition.

You can use this keyword multiple times to declare multiple preconditions on the given function.

postcondition NAME, BLOCK

Specify that the method NAME must meet the postcondition as specified in BLOCK.

In BLOCK, the variable @_ will be the argument list of the method. The function result may be used to retrieve the return values of the method. If the method returns a list, calling result in array context will return all of return values, and calling result in scalar context will return only the first item of that list. If the method returns a scalar, result called in scalar context will be that scalar, and result in array context will return a list with one element.

For example, to specify a postcondition on a method to ensure that the method returns a number less than zero, BLOCK would check the

    sub foo {
        my ( $self, $value ) = @_;
        ...
    }
    postcondition foo => sub {
        return ( result >= 0 );
    };

With methods, postconditions for the parent class will be checked if they exist. If the postcondition for the child's method fails, the blame lies with the child method's implementation since it is not adhering to its contract. If the postcondition for the child method passes, but the postcondition for the parent's fails, the problem lies with the hierarchy betweeen the classes. Note again that only the relationships between child and parent classes are checked -- this module won't traverse the complete ancestry of a class.

You can use this keyword multiple times to declare multiple postconditions on the given method.

postcondition VARIABLE, BLOCK

Specify that, when called, the subroutine reference pointed to by the lvalue VARIABLE must meet the postcondition as specified in BLOCK.

In BLOCK, the varable @_ and function result are available and may be used in the same ways as described in the previous usage of postcondition.

Say that you have a function g() that accepts another function, f() as its argument. f(), however, must return a number that is divisible by two. This can be expressed as:

    sub g {
        my ($f) = @_;
        postcondition $f => sub {
            return ! ( result % 2 );
        };
        ...
    }

If called in void context this function will modify VARIABLE to point to a new subroutine reference with the postcondition. If called in scalar context, this function will return a new function with the attached postcondition.

You can use this keyword multiple times to declare multiple postconditions on the given function.

dependent NAME, BLOCK

Specify that the method NAME will use the subroutine reference returned by BLOCK as a postcondition. If BLOCK returns undefined, no postcondition will be added. In some cases, the postcondition returned will depend on the input provided, hence these are referred to as dependent contracts. However, since the arguments to the method are given in the postcondition, dependent contracts will be used typically to compare old and new values.

BLOCK is run at the same time as preconditions, thus the @_ variable works in the same manner as in preconditions. However, the subroutine reference that BLOCK returns will be invoked as a postcondition, thus it may the result function in addition to @_.

You'll probably use these, along with closure, to check the old copies of values. See the example in "Testing old values".

You can use this keyword multiple times to declare multiple dependent contracts on the given method.

dependent VARIABLE, BLOCK

Specify that the subroutine reference pointed to by the lvalue VARIABLE will use the subroutine reference returned by BLOCK as a postcondition. If BLOCK returns undefined, no postcondition will be added.

Identical to the previous usage, BLOCK is run at the same time as preconditions, thus the @_ variable works in the same manner as in preconditions. However, the subroutine reference that BLOCK returns will be invoked as a postcondition, thus it may the result function in addition to @_.

Say that you have a function g() that accepts another function, f() as its argument. You want to make sure that f(), as a side effect, adds to the global variable $count:

    my $count = 0;
    ...

    sub g {
        my ($f) = @_;
        dependent $f => sub {
            my $old_count = $count;
            return sub { $count > $old_count };
        };
        ...
    }

You can use this keyword multiple times to declare multiple dependent contracts on the given function.

invariant BLOCK

BLOCK will be evaluated before and after every public method in the current class. A public method is described as any subroutine in the package whose name begins with a letter and is not composed entirely of uppercase letters.

Invariants will not be evaluated for class methods. More specifically, invariants will only be evaluated when the first argument to a subroutine is a blessed reference. This would mean that invariants would not be checked for constructors, but Class::Agreement provides another function, "specify_constructors", which is used for this purpose. (See the following section for details.)

Invariant BLOCKS are provided with only one argument: the current object. An exception is if the method is a constructor, the only argument to the BLOCK is the first return value of the method. (If your constructors return an object as the first or only return value -- as they normally do -- this means you're fine.)

Invariants are not checked when destructors are invoked. For an explanation as to why, see "WHITEPAPER".

You can use this keyword multiple times to declare multiple invariant contracts for the class.

Blame

Blaming violators of invariants is easy. If an invariant contract fails following a method invocation, we assume that the check prior to the invocation must have succeeded, so the implementation of the method is at fault. If an invariant fails before the method runs, invariants must have succeeded after the last method was called, so the object must have been tampered with by an exogenous source. Eeek!

Example

For example, say that you have a class for Othello boards, which are typically 8x8 grids. Othello begins with four pieces already placed on the board and ends when the board is full or there are no remaining moves. Thus, the board must always have between four and sixty-four pieces, inclusive:

    invariant sub {
        my ( $self ) = @_;
        return ( $self->pieces >= 4 and $self->pieces <= 64 );
    };

If the invariant fails after a method is called, the method's implementation is at fault. If the invariant fails before the method is run, an outside source has tampered with the object.

specify_constructors LIST

As described above, invariants are checked on public methods when the first argument is an object. Since constructors are typically class methods (if not also object methods), Class::Agreement needs to know which methods are constructors so that it can check invariants against the constructors' return values instead of simply ignoring them.

By default, it is assumed that a method named new is the constructor. You don't have to bother with this keyword if you don't specify any invariants or if your only constructor is new.

If your class has more constructors, you should specify all of them (including new) with specify_constructors so that invariants can be checked properly:

    package Othello::Board;
    use Class::Agreement;

    specify_constructors qw( new new_random );

    invariant sub {
        my ( $self ) = @_;
        return ( $self->pieces >= 4 and $self->pieces <= 64 );
    };

    sub new {
        ...
        return bless [], shift;
    }

    sub new_random {
        ...
        return bless [], shift;
    }

Any subclasses of Othello::Board would also have the invariants of the methods new() and new_random() checked as constructors. You can override the specified constructors of any class -- all subclasses will use the settings specified by their parents.

If, for some reason, your class has no constructors, you can pass specify_constructors an empty list:

    specify_constructors ();

REAL-LIFE EXAMPLES

Checking a method's input

Say that you have a board game that uses a graph of tiles. Every turn, players draw a tile and, if it's placable, plop it into the graph. The method insert_tile() of the Graph class should take a placable tile as an argument, which we can express as a contract:

    precondition insert_tile => sub {
        my ( $self, $tile ) = @_;
        return $self->verify_tile_fits( $tile );
    };

    sub insert_tile {
        my ( $self, $tile ) = @_;
        ...
    }

Before the implementation of insert_tile is executed, the precondition checks to ensure that $tile is placable in the graph as determined by verify_tile_fits().

Checking a method's output

Using the Graph class from the previous example, say we have a method get_neighbors() which, given an x and y, will return all tiles surrounding the tile at that position. If the tiles are square, any given tile shouldn't have more than eight neighbors:

    sub get_neighbors {
        my ( $self, $x, $y ) = @_;
        ...
    }

    postcondition get_neighbors => sub {
        return ( (result) <= 8 );
    };

The postcondition ensures that get_neighbors() returns no more than eight items.

Testing old values

Dependent contracts occur when the postcondition depends on the input given to the method. You can use dependent contracts to save old copies of values through the use of closure.

Given the Graph class from previous examples, say that the tiles in the graph are stored in a list. If insert tile has successfully added the tile to the graph, the number of tiles in the graph should have increased by one. Using the dependent() function, we return a closure that will check exactly this:

    dependent insert_tile => sub {
        my ( $self, $tile ) = @_;
        my $old_count = $self->num_tiles;
        return sub {
            my ( $self, $tile ) = @_;
            return ( $self->num_tiles > $old_count );
        };
    };

    sub insert_tile {
        my ( $self, $tile ) = @_;
        ...
    }

Before the implementation of insert_tile() is run, the block given to dependent() is run, which returns a closure. This closure is then run after insert_tile() as if it were a precondition. (Thus, the closure returned by the block may make use the result function as well as @_.)

Contracts on coderefs

This is where contracts get interesting. Say that you have a function g() that takes a function f() as an argument and returns a number greater than zero. However, f() has a contract, too: it must take a natural number as the first argument and must return a single letter of the alphabet. This can be represented as follows:

    precondition g => sub {
        # first argument of @_ is f()
        precondition $_[0] => sub {
            my ( $val ) = @_;
            return ( $val =~ /^\d+$/ );
        };
        postcondition $_[0] => sub {
            return ( result =~ /^[A-Z]$/i );
        };
    };

    sub g {
        my ($f) = @_;
        ... # call $f somehow
    }

    postcondition g => sub {
        return ( result > 0 );
    };

Thus, when the function f() is used within g(), the contracts set up for f() in the precondition apply to it.

FAQ

Aren't contracts just assertions I could write with something like die unless ?

The answer to this has been nicely worded by Jim Weirich in "Design by Contract and Unit Testing" located at http://onestepback.org/index.cgi/Tech/Programming/DbcAndTesting.html:

"Although Design by Contract and assertions are very closely related, DbC is more than just slapping a few assertions into your code at strategic locations. It is about identifying the contract under which your code will execute and you expect all clients to adhere to. It is about clearly defining responsibilities between client software and supplier software.

"In short, Design by Contract starts by specifying the conditions under which it is legal to call a method. It is the responsibility of the client software to ensure these conditions (called preconditions) are met.

"Given that the preconditions are met, the method in the supplier software guarantees that certion other conditions will be true when the method returns. These are called postcondition, and are the responsibility of the supplier code in ensure."

Why not just use Carp::Assert?

Use Carp::Assert and Carp::Assert if you need to check values. If you want to assert behavior, Class::Agreement does everything that Carp::Assert can do for you and it determines which components are faulty when something fails.

If you're looking for the sexiness of Carp::Assert::More, try using Class::Agreement with something like Data::Validate:

    use Class::Agreement;
    use Data::Validate qw(:math :string);

    precondition foo => sub { is_integer( $_[1] ) };
    precondition bar => sub { is_greater_than( $_[1], 0 ) };
    precondition baz => sub { is_alphanumeric( $_[1] ) };

How do I save an old copy of the object?

Hopefully you don't need to. Just save the variable (or variables) you need to check in the postcondition by creating closures. See "Testing old values" for an example of how to do this.

How do I disable contracts?

Before you ask this, determine why you want to do this. If your contracts are slowing down your program, first try following these guidelines:

  • Don't clone.

    Cloning in Perl is expensive. Hopefully you've read the above examples on "Testing old values" and have realized that cloning an object isn't necessary.

  • Don't recreate the function in the contract.

    If your contract is performing the exact same tasks or calculations that are in the function itself, toss it. Only code the essentials into the contracts, such as "this function returns a number greater than twelve" or "the object was modified in this mannar."

  • Don't do type-checking in the contracts.

    You can if you want, but contracts are designed to be declarations of behavior, not to enforce the types of data structures you're passing around.

If you really want to disable this module, replace use Class::Agreement with use Class::Agreement::Dummy, which exports identically-named functions that do nothing.

What do you mean, "There's a problem with the hierarchy?"

The Liskov-Wing principle states, "The objects of subtype ought to behave the same as those of the supertype as far as anyone or any program using the supertype objects can tell." (See: "Liskov Wing Subtyping" at http://c2.com/cgi/wiki?LiskovWingSubtyping.) Say that ClassA is a parent class of ClassB, and both classes implement a method m(), and both implementations have pre- and postconditions. According to Liskov-Wing, the valid input of ClassA::m() should be a subset of the valid input of ClassB::m(). Thus, if the precondition for ClassA::m() fails but the precondition for ClassB::m() passes, the class heiarchy fails the principle. Postconditions are the opposite: the output of ClassA::m() should be a superset of the output of ClassB::m(). If the postcondition for ClassA::m() passes but the postcondition for ClassB::m() fails, this violates the principle.

Can I modify the argument list?

If the argument list @_ is made up of simple scalars, no. However, if the method or function is passed a reference of some sort. This is a Bad Thing because your code should

How can I type less?

...or more ugly? Use implicit returns and don't name your variables. For example, the dependent contract in "Dependent Contracts" could be written as follows:

    dependent insert_tile => sub {
        my $o = shift()->num_tiles;
        sub { shift()->num_tiles > $o };
    };

Other examples:

    precondition sqrt => sub { shift() > 0 };

    postcondition digits => sub { result =~ /^\d+$/ };

    invariant sub { shift()->size > 4 };

Or, write your own generator to make things clean:

    sub argument_is_divisible_by {
        my $num = shift;
        return sub { not $_[1] % $num };
    }

    precondition foo => argument_is_divisible_by(2);
    precondition bar => argument_is_divisible_by(3);

What if I generate methods?

There's no problem as long as you build your subroutines before runtime, probably by sticking the generation in a BEGIN block.

Here's a snippet from one of the included tests, t/generate-methods.t. Three methods, foo, bar and baz, are created and given an assertion that the argument passed to them must be greater than zero:

    my $assertion = sub { $_[1] > 0 };
    precondition foo => $assertion;
    precondition bar => $assertion;
    precondition baz => $assertion;

    BEGIN {
        no strict 'refs';
        *{$_} = sub { }
            for qw( foo bar baz );
    }

CAVEATS

  • You can't add contracts for abstract methods. If you try to add a contract to a method that isn't implemented in the given class or any of its parents, Class::Agreement will croak. One must declare an empty subroutine to get around this.

  • The wantarray keyword will not properly report void context to any methods with contracts.

  • The caller keyword will return an extra stack frame.

AUTHOR

Ian Langworth, <ian@cpan.org>

BUGS

Please report any bugs or feature requests to bug-class-agreement@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Agreement. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

Thanks to Prof. Matthias Felleisen who granted me a directed study to pursue this project and guided me during its development.

Thanks to a number of other people who contributed to this module in some way, including: Damian Conway, Simon Cozens, Dan "Lamech" Friedman, Uri Guttman, Christian Hansen, Adrian Howard, David Landgren, Curtis "Ovid" Poe, Ricardo SIGNES, Richard Soderburg, Jesse Vincent.

SEE ALSO

Class::Contract, Hook::LexWrap, Carp::Assert, Carp::Assert::More, Param::Util

http://citeseer.ist.psu.edu/findler01objectoriented.html, http://c2.com/cgi/wiki?LiskovWingSubtyping

COPYRIGHT & LICENSE

Copyright 2005 Ian Langworth, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.