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 .) 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 : "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 .) 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, "" BUGS Please report any bugs or feature requests to "bug-class-agreement@rt.cpan.org", or through the web interface at . 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 , 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.