This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.


File: pm.info,  Node: Class/Contract,  Next: Class/Contract/Production,  Prev: Class/Classless,  Up: Module List

Design-by-Contract OO in Perl.
******************************

NAME
====

   Class::Contract - Design-by-Contract OO in Perl.

VERSION
=======

   This document describes version 1.10 of Class::Contract, released
February  9, 2001.

SYNOPSIS
========

     package ClassName
     use Class::Contract;

     contract {
       inherits 'BaseClass';

     invar { ... };

     attr 'data1';
     attr 'data2' => HASH;

     class attr 'shared' => SCALAR;

     ctor 'new';

     method 'methodname';
       pre  { ... };
         failmsg 'Error message';

     post  { ... };
       failmsg 'Error message';

     impl { ... };

     method 'nextmethod';
       impl { ... };

     class method 'sharedmeth';
       impl { ... };

     # etc.
         };

DESCRIPTION
===========

Background
----------

   Design-by-contract is a software engineering technique in which each
module of a software system specifies explicitly what input (or data or
arguments) it requires, and what output (or information or results) it
guarantees to produce in response.

   These specifications form the "clauses" of a contract between a module
and the client software that uses it. If the client software abides by the
input requirements, the module guarantees to produce the correct output.
Hence by verifying these clauses at each interaction with a module, the
overall behaviour of the system can be confidently predicted.

   Design-by-contract reinforces the benefits of modular design techniques
by inserting explicit compile-time or run-time checks on a contract.
These checks are most often found in object-oriented languages and are
typically implemented as pre-conditions and post-conditions on methods,
and invariants on classes.

   Note that these features differ from simple verification statements
such as the C assert statement. Conditions and invariants are properties
of a class, and are inherited by derived classes.

   An additional capacity that is often provided in design-by-contract
systems is the ability to selectively disable checking in production code.
This allows the contractual testing to be carried out during
implementation, without impinging on the performance of the final system.

Adding design-by-contract to Perl
---------------------------------

   The Class::Contract module provides a framework for specifying methods
and attributes for a class (much like the existing class definition
modules Class::Struct, Class::MethodMaker, and Class::Generate).
Class::Contract allows both per-object and per-class methods and
attributes to be defined. Attributes may be scalar-, array-, hash-, or
object-based.

   Class::Contract differs from other class-specification modules (except
Class::Generate) in that it also provides the ability to specify invariant
conditions on classes, and pre- and post-conditions on methods and
attributes. All of these clauses are fully inheritable, and may be
selectively disabled. It differs from all other modules in that it has a
cleaner, simpler specification syntax, and - more importantly - it
enforces encapsulation of object attributes, thereby ensuring that the
class contract cannot be subverted.

Defining classes
----------------

   Class::Contract provides an explicit syntax for defining the attributes,
methods, and constructors of a class. The class itself is defined using
the `contract' subroutine. `contract' takes a single argument - a
subroutine reference or a block. That block is executed once and the
results used to construct and install the various components of the class
in the current package:

     package Queue;
     contract {
       # specification of class Queue attributes and methods here
     };

Defining attributes
-------------------

   Attributes are defined within the `contract' block via the attr
subroutine.  Attributes must be given a name, and may also be given a
type: SCALAR, ARRAY, HASH, or a class name:

     contract {
             attr 'last';                   # Scalar attribute (by default)
             attr 'lest' => SCALAR;         # Scalar attribute
             attr 'list' => ARRAY;          # Array attribute
             attr 'lost' => HASH;           # Hash attribute
             attr 'lust' => MyClass;        # Object attribute
     };

   For each attribute so declared, Class::Contract creates an *accessor* -
a method that returns a reference to the attribute in question. Code using
these accessors might look like this:

     ${$obj->last}++;
     push @{$obj->list}, $newitem;
     print $obj->lost->{'marbles'};
     $obj->lust->after('technology stocks');

   Attributes are normally object-specific, but it is also possible to
define attributes that are shared by all objects of a class. Class objects
are specified by prefixing the call to attr with a call to the class
subroutine:

     class Queue;
     contract {
             class attr 'obj_count';
     };

   The accessor for this shared attribute can now be called either as an
object method:

     print ${$obj->obj_count};

   or as a class method:

     print ${Queue->obj_count};

   In order to ensure that the clauses of a class' contract (see below)
are honoured, both class and object attributes are only accessible via
their accessors, and those accessors may only be called within methods
belonging to the same class hierarchy. Objects are implemented as
"flyweight scalars" in order to ensure this strict encapsulation is
preserved.

Defining methods
----------------

   Methods are defined in much the same way as attributes. The method
subroutine is used to specify the name of a method, then the `impl'
subroutine is used to provide an implementation for it:

     contract {
             attr list => ARRAY;

     method 'next';
         impl { shift @{self->list} };

     method 'enqueue';
         impl { push @{self->list}, $_[1] };
             };

   `impl' takes a block (or a reference to a subroutine), which is used as
the implementation of the method named by the preceding method call.
Within that block, the subroutine `self' may be used to return a reference
to the object on which the method was called. Unlike, regular OO Perl, the
object reference is not passed as the method's first argument.  (Note:
this change occurred in version 1.10)

   Like attributes, methods normally belong to - and are accessed via - a
specific object. To define methods that belong to the entire class, the
class qualifier is once again used:

     contract {
             class attr 'obj_count';

     class method 'inc_count';
             impl { ${self->obj_count}++ };
             };

   Note that the `self' subroutine can still be used - within a class
method it returns the appropriate class name, rather than an object
reference.

Defining constructors
---------------------

   Class::Contract requires constructors to be explicitly defined using
the `ctor' subroutine:

     contract {
             ctor 'new';
                 impl { @{self->list} = ( $_[0] ) }
     };

   Note that the implementation section of a constructor *doesn't* specify
code to build or bless the new object. That is taken care of automatically
(in order to ensure the correct "flyweight" implementation of the object).

   Instead, the constructor implementation is invoked after the object has
been created and blessed into the class. Hence the implementation only
needs to initialize the various attributes of the `self' object.  In
addition, the return value of the implementation is ignored: constructor
calls always return a reference to the newly created object.

   Any attribute that is not initialized by a constructor is automatically
"default initialized". By default, scalar attributes remain undef, array
and hash attributes are initialized to an empty array or hash, and object
attributes are initialized by having their new constructor called (with no
arguments). This is the only reasonable default for object attributes, but
it is usually advisable to initialize them explicitly in the constructor.

   It is also possible to define a "class constructor", which may be used
to initialize class attributes:

     contract {
             class attr 'obj_count';

     class ctor;
             impl { ${self->obj_count} = 0 };
             };

   The class constructor is invoked at the very end of the call to
`contract' in which the class is defined.

   Note too that the class constructor does not require a name. It may,
however, be given one, so that it can be explicitly called again (as a
class method) later in the program:

     class MyClass;
     contract {
             class attr 'obj_count';

     class ctor 'reset';
             impl { ${self->obj_count} = 0 };
             };

     # and later...

     MyClass->reset;

Defining destructors
--------------------

   Destructors are also explicitly defined under Class::Contract, using
the `dtor' subroutine:

     contract {
             dtor;
                 impl { print STDLOG "Another object died\n" }
     };

   As with the constructor, the implementation section of a destructor
doesn't specify code to clean up the "flyweight" implementation of the
object. Class::Contract takes care of that automatically.

   Instead, the implementation is invoked before the object is
deallocated, and may be used to clean up any of the internal structure of
the object (for example to break reference cycles).

   It is also possible to define a "class destructor", which may be used
to clean up class attributes:

     contract {
             class attr 'obj_count';

     class dtor;
         impl { print STDLOG "Total was ${self->obj_count}\n" };
             };

   The class destructor is invoked from an END block within Class::Contract
(although the implementation itself is a closure, so it executes in the
namespace of the original class).

Constraining class elements
---------------------------

   As described so far, Class::Contract doesn't provide any features that
differ greatly from those of any other class definition module. But
Class::Contract does have one significant difference: it allows the class
designer to specify "clauses" that implement and enforce a contract on the
class's interface.

   Contract clauses are specified as labelled blocks of code, associated
with a particular class, method, or attribute definition.

Class invariants
----------------

   Classes may be given *invariants*: clauses than must be satisfied at
the end of any method call that is invoked from outside the class itself.
For example, to specify that a class's object count attribute must never
fall below zero:

     contract {
             invar { ${self->obj_count} >= 0 };
     };

   The block following `invar' is treated as if it were a class method
that is automatically invoked after every other method invocation. If the
method returns false, croak is invoked with the error message: `'Class
invariant at %s failed'' (where the '%s' is replaced by the file and line
number at which the invariant was defined).

   This error message can be customized, using the `failmsg' subroutine:

     contract {
             invar { ${self->obj_count} >= 0 };
                 failmsg 'Anti-objects detected by invariant at %s';
     };

   Once again, the '%s' is replaced by the appropriate file name and line
number. A `failmsg' can be specified after other types of clause too (see
below).

   A class may have as many invariants as it requires, and they may be
specified anywhere throughout the the body of the `contract'.

Attribute and method pre- and post-conditions
---------------------------------------------

   Pre- and post-conditions on methods and attributes are specified using
the pre and post subroutines respectively.

   For attributes, pre-conditions are called before the attribute's
accessor is invoked, and post-conditions are called after the reference
returned by the accessor is no longer accessible. This is achieved by
having the accessor return a tied scalar whose DESTROY method invokes the
post-condition.

   Method pre-conditions are tested before their method's implementation is
invoked; post-conditions are tested after the implementation finishes (but
before the method's result is returned). Constructors are (by definition)
class methods and may have pre- and post-conditions, just like any other
method.

   Both types of condition clause receive the same argument list as the
accessor or method implementation that they constrain. Both are expected
to return a false value if they fail:

     contract {
             class attr 'obj_count';
                 post { ${&value} > 0 };
                   failmsg 'Anti-objects detected by %s';

     method 'inc_count';
         post { ${self->obj_count} < 1000000 };
           failmsg 'Too many objects!';
         impl { ${self->obj_count}++ };
             };

   Note that within the pre- and post-conditions of an attribute, the
special value subroutine returns a reference to the attribute itself, so
that conditions can check properties of the attribute they guard.

   Methods and attributes may have as many distinct pre- and
post-conditions as they require, specified in any convenient order.

Checking state changes.
-----------------------

   Post-conditions and invariants can access the previous state of an
object or the class, via the old subroutine. Within any post-condition or
invariant, this subroutine returns a reference to a copy of the object or
class state, as it was just before the current method or accessor was
called.

   For example, an append method might use old to verify the appropriate
change in size of an object:

     contract {
         method 'append';
             post { @{self->queue} == @{old->queue} + @_ }
             impl { push @{self->queue}, @_ };
     };

   Note that the implementation's return value is also available in the
method's post-condition(s) and the class's invariants, through the
subroutine value. In the above example, the implementation of append
returns the new size of the queue (i.e. what push returns), so the
post-condition could also be written:

     contract {
         method 'append';
             post { ${&value} == @{old->queue} + @_ }
             impl { push @{self->queue}, @_ };
     };

   Note that value will return a reference to a scalar or to an array,
depending on the context in which the method was originally called.

Clause control
--------------

   Any type of clause may be declared optional:

     contract {
             optional invar { @{self->list} > 0 };
             failmsg 'Empty queue detected at %s after call';
     };

   By default, optional clauses are still checked every time a method or
accessor is invoked, but they may also be switched off (and back on) at
run-time, using the check method:

     local $_ = 'Queue';         # Specify in $_ which class to disable
     check my %contract => 0;    # Disable optional checks for class Queue

   This (de)activation is restricted to the scope of the hash that is
passed as the first argument to check. In addition, the change only
affects the class whose name is held in the variable $_ at the time check
is called.  This makes it easy to (de)activate checks for a series of
classes:

     check %contract => 0 for qw(Queue PriorityQueue DEQueue);  # Turn off
     check %contract => 1 for qw(Stack PriorityStack Heap);     # Turn on

   The special value `'__ALL__'' may also be used as a (pseudo-)class name:

     check %contract => 0 for __ALL__;

   This enables or disables checking on every class defined using
Class::Contract. But note that only clauses that were originally declared
optional are affected by calls to check. Non-optional clauses are always
checked.

   Optional clauses are typically universally disabled in production code,
so Class::Contract provides a short-cut for this. If the module is
imported with the single argument `'production'', optional clauses are
universally and irrevocably deactivated. In fact, the optional subroutine
is replaced by:

     sub Class::Contract::optional {}

   so that optional clauses impose no run-time overhead at all.

   In production code, contract checking ought to be disabled completely,
and the requisite code optimized away.  To do that, simply change:

     use Class::Contract;

   to

     use Class::Contract::Production;

Inheritance
-----------

   The semantics of class inheritance for Class::Contract classes differ
in several respects from those of normal object-oriented Perl.

   To begin with, classes defined using Class::Contract have a *static
inheritance hierarchy*. The inheritance relationships of contracted classes
are defined using the `inherits' subroutine within the class's `contract'
block:

     package PriorityQueue;
     contract {
             inherits qw( Queue OrderedContainer );
     };

   That means that ancestor classes are fixed at compile-time (rather than
being determined at run-time by the @ISA array). Note that multiple
inheritance is supported.

   Method implementations are only inherited if they are not explicitly
provided. As with normal OO Perl, a method's implementation is inherited
from the left-most ancestral class that provides a method of the same name
(though with Class::Contract, this is determined at compile-time).

   Constructors are a special case, however. Their "constructive"
behaviour is always specific to the current class, and hence involves no
inheritance under any circumstances. However, the "initialising" behaviour
specified by a constructor's `impl' block *is* inherited. In fact, the
implementations of all base class constructors are called automatically by
the derived class constructor (in left-most, depth-first order), and
passed the same argument list as the invoked constructor. This behaviour
is much more like that of other OO programming languages (for example,
Eiffel or C++).

   Methods in a base class can also be declared as being abstract:

     contract {
         abstract method 'remove';
             post { ${self->count} == ${old->count}-1 };
     };

   Abstract methods act like placeholders in an inheritance hierarchy.
Specifically, they have no implementation, existing only to reserve the
name of a method and to associate pre- and post-conditions with it.

   An abstract method cannot be directly called (although its associated
conditions may be). If such a method is ever invoked, it immediately calls
croak. Therefore, the presence of an abstract method in a base class
requires the derived class to redefine that method, if the derived class
is to be usable. To ensure this, any constructor built by Class::Contract
will refuse to create objects belonging to classes with abstract methods.

   Methods in a base class can also be declared as being private:

     contract {
         private method 'remove';
             impl { pop @{self->queue} };
     };

   Private methods may only be invoked by the class or one of its
descendants.

Inheritance and condition checking
----------------------------------

   Attribute accessors and object methods inherit all post-conditions of
every ancestral accessor or method of the same name. Objects and classes
also inherit all invariants from any ancestor classes. That is, methods
accumulate all the post- and invariant checks that their ancestors
performed, as well as any new ones they define for themselves, and must
satisfy all of them in order to execute successfully.

   Pre-conditions are handled slightly differently. The principles of
design-by-contract programming state that pre-conditions in derived
classes can be no stronger than those in base classes (and may well be
weaker). In other words, a derived class must handle every case that its
base class handled, but may choose to handle other cases as well, by being
less demanding regarding its pre-conditions.

   Meyers suggests an efficient way to achieve this relaxation of
constraints without the need for detailed logical analysis of
pre-conditions. His solution is to allow a derived class method or
accessor to run if *either* the pre-conditions it inherits are satisfied
or its own pre-conditions are satisfied. This is precisely the semantics
that Class::Contract uses when checking pre-conditions in derived classes.

A complete example
------------------

   The following code implements a PriorityStack class, in which elements
pushed onto the stack "sink" until they encounter an element with lower
priority.  Note the use of old to check that object state has changed
correctly, and the use of explicit dispatch (e.g. `self->Stack::pop') to
invoke inherited methods from the derived-class methods that redefine them.

     package PriorityStack;
     use Class::Contract;

     contract {
         # Reuse existing implementation...
         inherits 'Stack';

     # Name the constructor (nothing special to do, so no implementation)
     ctor 'new';

     method 'push';
         # Check that data to be added is okay...
         pre  { defined $_[0] };
             failmsg 'Cannot push an undefined value';
         pre  { $_[1] > 0 };
             failmsg 'Priority must be greater than zero';

     # Check that push increases stack depth appropriately...
     post { self->count == old->count+1 };

     # Check that the right thing was left on top...
     post { old->top->{'priority'} <= self->top->{'priority'} };

     # Implementation reuses inherited methods: pop any higher
     # priority entries, push the new entry, then re-bury it...
     impl {
         my ($newval, $priority) = @_[0,1];
         my @betters;
         unshift @betters, self->Stack::pop
             while self->count
                && self->Stack::top->{'priority'} > $priority;
         self->Stack::push( {'val'=>$newval, priority=>$priority} );
         self->Stack::push( $_ )  foreach @betters;
     };

     method 'pop';
         # Check that pop decreases stack depth appropriately...
         post { self->count == old->count-1 };

     # Reuse inherited method...
     impl {
         return  unless self->count;
         return self->Stack::pop->{'val'};
     };

     method 'top';
         post { old->count == self->count }
         impl {
             return  unless self->count;
             return self->Stack::top->{'val'};
         };
             };

FUTURE WORK
===========

   Future work on Class::Contract will concentrate on three areas:

  1. Improving the attribute accessor mechanism Lvalue subroutines will be
     introduced in perl version 5.6. They will allow a return value to be
     treated as an alias for the (scalar) argument of a return statement.
     This will make it possible to write subroutines whose return value
     may be assigned to (like the built-in pos and substr functions).

     In the absence of this feature, Class::Contract accessors of all types
     return a reference to their attribute, which then requires an explicit
     dereference:

          ${self->value} = $newval;
          ${self->access_count}++;

     When this feature is available, accessors for scalar attributes will
     be able to return the actual attribute itself as an lvalue. The above
     code would then become cleaner:

          self->value = $newval;
          self->access_count++;

  2. Providing better software engineering tools.  Contracts make the
     consequences of inheritance harder to predict, since they
     significantly increase the amount of ancestral behaviour (i.e.
     contract clauses) that a class inherits.

     Languages such as Eiffel provide useful tools to help the software
     engineer make sense of this extra information. In particular, Eiffel
     provides two alternate ways of inspecting a particular class - flat
     form and short form.

     "Flattening" a class produces an equivalent class definition without
     any inheritance. That is, the class is modified by making explicit
     all the attributes, methods, conditions, and invariants it inherits
     from other classes. This allows the designer to see every feature a
     class possesses in one location.

     "Shortening" a class, takes the existing class definition and removes
     all implementation aspects of it - that is, those that have no
     bearing on its public interface. A shortened representation of a
     class therefore has all attribute specifications and method
     implementations removed. Note that the two processes can be
     concatenated: shortening a flattened class produces an explicit
     listing of its complete public interface. Such a representation can
     be profitably used as a basis for documenting the class.

     It is envisaged that Class::Contract will eventually provide a
     mechanism to produce equivalent class representations in Perl.

  3. Offering better facilities for retrofitting contracts.  At present,
     adding contractual clauses to an existing class requires a major
     restructuring of the original code. Clearly, if design-by-contract is
     to gain popularity with Perl programmers, this transition cost must
     be minimized.

     It is as yet unclear how this might be accomplished, but one
     possibility would be to allow the implementation of certain parts of a
     Class::Contract class (perhaps even the underlying object
     implementation itself) to be user-defined.


AUTHOR
======

   Damian Conway (damian@conway.org)

MAINTAINER
==========

   C. Garrett Goebel (ggoebel@cpan.org)

BUGS
====

   There are undoubtedly serious bugs lurking somewhere in code this funky
:-) Bug reports and other feedback are most welcome.

COPYRIGHT
=========

   Copyright (c) 1997-2000, Damian Conway. All Rights Reserved.  This
module is free software. It may be used, redistributed and/or modified
under the terms of the Perl Artistic License   (see
http://www.perl.com/perl/misc/Artistic.html)

   Copyright (c) 2000-2001, C. Garrett Goebel. All Rights Reserved.  This
module is free software. It may be used, redistributed and/or modified
under the terms of the Perl Artistic License   (see
http://www.perl.com/perl/misc/Artistic.html)


File: pm.info,  Node: Class/Contract/Production,  Next: Class/DBI,  Prev: Class/Contract,  Up: Module List

Design-by-Contract OO in Perl.
******************************

NAME
====

   Class::Contract - Design-by-Contract OO in Perl.

VERSION
=======

   This document describes version 1.10 of Class::Contract, released
February  9, 2001.

SYNOPSIS
========

     package ClassName
     use Class::Contract;

     contract {
       inherits 'BaseClass';

     invar { ... };

     attr 'data1';
     attr 'data2' => HASH;

     class attr 'shared' => SCALAR;

     ctor 'new';

     method 'methodname';
       pre  { ... };
         failmsg 'Error message';

     post  { ... };
       failmsg 'Error message';

     impl { ... };

     method 'nextmethod';
       impl { ... };

     class method 'sharedmeth';
       impl { ... };

     # etc.
         };

DESCRIPTION
===========

Background
----------

   Design-by-contract is a software engineering technique in which each
module of a software system specifies explicitly what input (or data or
arguments) it requires, and what output (or information or results) it
guarantees to produce in response.

   These specifications form the "clauses" of a contract between a module
and the client software that uses it. If the client software abides by the
input requirements, the module guarantees to produce the correct output.
Hence by verifying these clauses at each interaction with a module, the
overall behaviour of the system can be confidently predicted.

   Design-by-contract reinforces the benefits of modular design techniques
by inserting explicit compile-time or run-time checks on a contract.
These checks are most often found in object-oriented languages and are
typically implemented as pre-conditions and post-conditions on methods,
and invariants on classes.

   Note that these features differ from simple verification statements
such as the C assert statement. Conditions and invariants are properties
of a class, and are inherited by derived classes.

   An additional capacity that is often provided in design-by-contract
systems is the ability to selectively disable checking in production code.
This allows the contractual testing to be carried out during
implementation, without impinging on the performance of the final system.

Adding design-by-contract to Perl
---------------------------------

   The Class::Contract module provides a framework for specifying methods
and attributes for a class (much like the existing class definition
modules Class::Struct, Class::MethodMaker, and Class::Generate).
Class::Contract allows both per-object and per-class methods and
attributes to be defined. Attributes may be scalar-, array-, hash-, or
object-based.

   Class::Contract differs from other class-specification modules (except
Class::Generate) in that it also provides the ability to specify invariant
conditions on classes, and pre- and post-conditions on methods and
attributes. All of these clauses are fully inheritable, and may be
selectively disabled. It differs from all other modules in that it has a
cleaner, simpler specification syntax, and - more importantly - it
enforces encapsulation of object attributes, thereby ensuring that the
class contract cannot be subverted.

Defining classes
----------------

   Class::Contract provides an explicit syntax for defining the attributes,
methods, and constructors of a class. The class itself is defined using
the `contract' subroutine. `contract' takes a single argument - a
subroutine reference or a block. That block is executed once and the
results used to construct and install the various components of the class
in the current package:

     package Queue;
     contract {
       # specification of class Queue attributes and methods here
     };

Defining attributes
-------------------

   Attributes are defined within the `contract' block via the attr
subroutine.  Attributes must be given a name, and may also be given a
type: SCALAR, ARRAY, HASH, or a class name:

     contract {
             attr 'last';                   # Scalar attribute (by default)
             attr 'lest' => SCALAR;         # Scalar attribute
             attr 'list' => ARRAY;          # Array attribute
             attr 'lost' => HASH;           # Hash attribute
             attr 'lust' => MyClass;        # Object attribute
     };

   For each attribute so declared, Class::Contract creates an *accessor* -
a method that returns a reference to the attribute in question. Code using
these accessors might look like this:

     ${$obj->last}++;
     push @{$obj->list}, $newitem;
     print $obj->lost->{'marbles'};
     $obj->lust->after('technology stocks');

   Attributes are normally object-specific, but it is also possible to
define attributes that are shared by all objects of a class. Class objects
are specified by prefixing the call to attr with a call to the class
subroutine:

     class Queue;
     contract {
             class attr 'obj_count';
     };

   The accessor for this shared attribute can now be called either as an
object method:

     print ${$obj->obj_count};

   or as a class method:

     print ${Queue->obj_count};

   In order to ensure that the clauses of a class' contract (see below)
are honoured, both class and object attributes are only accessible via
their accessors, and those accessors may only be called within methods
belonging to the same class hierarchy. Objects are implemented as
"flyweight scalars" in order to ensure this strict encapsulation is
preserved.

Defining methods
----------------

   Methods are defined in much the same way as attributes. The method
subroutine is used to specify the name of a method, then the `impl'
subroutine is used to provide an implementation for it:

     contract {
             attr list => ARRAY;

     method 'next';
         impl { shift @{self->list} };

     method 'enqueue';
         impl { push @{self->list}, $_[1] };
             };

   `impl' takes a block (or a reference to a subroutine), which is used as
the implementation of the method named by the preceding method call.
Within that block, the subroutine `self' may be used to return a reference
to the object on which the method was called. Unlike, regular OO Perl, the
object reference is not passed as the method's first argument.  (Note:
this change occurred in version 1.10)

   Like attributes, methods normally belong to - and are accessed via - a
specific object. To define methods that belong to the entire class, the
class qualifier is once again used:

     contract {
             class attr 'obj_count';

     class method 'inc_count';
             impl { ${self->obj_count}++ };
             };

   Note that the `self' subroutine can still be used - within a class
method it returns the appropriate class name, rather than an object
reference.

Defining constructors
---------------------

   Class::Contract requires constructors to be explicitly defined using
the `ctor' subroutine:

     contract {
             ctor 'new';
                 impl { @{self->list} = ( $_[0] ) }
     };

   Note that the implementation section of a constructor *doesn't* specify
code to build or bless the new object. That is taken care of automatically
(in order to ensure the correct "flyweight" implementation of the object).

   Instead, the constructor implementation is invoked after the object has
been created and blessed into the class. Hence the implementation only
needs to initialize the various attributes of the `self' object.  In
addition, the return value of the implementation is ignored: constructor
calls always return a reference to the newly created object.

   Any attribute that is not initialized by a constructor is automatically
"default initialized". By default, scalar attributes remain undef, array
and hash attributes are initialized to an empty array or hash, and object
attributes are initialized by having their new constructor called (with no
arguments). This is the only reasonable default for object attributes, but
it is usually advisable to initialize them explicitly in the constructor.

   It is also possible to define a "class constructor", which may be used
to initialize class attributes:

     contract {
             class attr 'obj_count';

     class ctor;
             impl { ${self->obj_count} = 0 };
             };

   The class constructor is invoked at the very end of the call to
`contract' in which the class is defined.

   Note too that the class constructor does not require a name. It may,
however, be given one, so that it can be explicitly called again (as a
class method) later in the program:

     class MyClass;
     contract {
             class attr 'obj_count';

     class ctor 'reset';
             impl { ${self->obj_count} = 0 };
             };

     # and later...

     MyClass->reset;

Defining destructors
--------------------

   Destructors are also explicitly defined under Class::Contract, using
the `dtor' subroutine:

     contract {
             dtor;
                 impl { print STDLOG "Another object died\n" }
     };

   As with the constructor, the implementation section of a destructor
doesn't specify code to clean up the "flyweight" implementation of the
object. Class::Contract takes care of that automatically.

   Instead, the implementation is invoked before the object is
deallocated, and may be used to clean up any of the internal structure of
the object (for example to break reference cycles).

   It is also possible to define a "class destructor", which may be used
to clean up class attributes:

     contract {
             class attr 'obj_count';

     class dtor;
         impl { print STDLOG "Total was ${self->obj_count}\n" };
             };

   The class destructor is invoked from an END block within Class::Contract
(although the implementation itself is a closure, so it executes in the
namespace of the original class).

Constraining class elements
---------------------------

   As described so far, Class::Contract doesn't provide any features that
differ greatly from those of any other class definition module. But
Class::Contract does have one significant difference: it allows the class
designer to specify "clauses" that implement and enforce a contract on the
class's interface.

   Contract clauses are specified as labelled blocks of code, associated
with a particular class, method, or attribute definition.

Class invariants
----------------

   Classes may be given *invariants*: clauses than must be satisfied at
the end of any method call that is invoked from outside the class itself.
For example, to specify that a class's object count attribute must never
fall below zero:

     contract {
             invar { ${self->obj_count} >= 0 };
     };

   The block following `invar' is treated as if it were a class method
that is automatically invoked after every other method invocation. If the
method returns false, croak is invoked with the error message: `'Class
invariant at %s failed'' (where the '%s' is replaced by the file and line
number at which the invariant was defined).

   This error message can be customized, using the `failmsg' subroutine:

     contract {
             invar { ${self->obj_count} >= 0 };
                 failmsg 'Anti-objects detected by invariant at %s';
     };

   Once again, the '%s' is replaced by the appropriate file name and line
number. A `failmsg' can be specified after other types of clause too (see
below).

   A class may have as many invariants as it requires, and they may be
specified anywhere throughout the the body of the `contract'.

Attribute and method pre- and post-conditions
---------------------------------------------

   Pre- and post-conditions on methods and attributes are specified using
the pre and post subroutines respectively.

   For attributes, pre-conditions are called before the attribute's
accessor is invoked, and post-conditions are called after the reference
returned by the accessor is no longer accessible. This is achieved by
having the accessor return a tied scalar whose DESTROY method invokes the
post-condition.

   Method pre-conditions are tested before their method's implementation is
invoked; post-conditions are tested after the implementation finishes (but
before the method's result is returned). Constructors are (by definition)
class methods and may have pre- and post-conditions, just like any other
method.

   Both types of condition clause receive the same argument list as the
accessor or method implementation that they constrain. Both are expected
to return a false value if they fail:

     contract {
             class attr 'obj_count';
                 post { ${&value} > 0 };
                   failmsg 'Anti-objects detected by %s';

     method 'inc_count';
         post { ${self->obj_count} < 1000000 };
           failmsg 'Too many objects!';
         impl { ${self->obj_count}++ };
             };

   Note that within the pre- and post-conditions of an attribute, the
special value subroutine returns a reference to the attribute itself, so
that conditions can check properties of the attribute they guard.

   Methods and attributes may have as many distinct pre- and
post-conditions as they require, specified in any convenient order.

Checking state changes.
-----------------------

   Post-conditions and invariants can access the previous state of an
object or the class, via the old subroutine. Within any post-condition or
invariant, this subroutine returns a reference to a copy of the object or
class state, as it was just before the current method or accessor was
called.

   For example, an append method might use old to verify the appropriate
change in size of an object:

     contract {
         method 'append';
             post { @{self->queue} == @{old->queue} + @_ }
             impl { push @{self->queue}, @_ };
     };

   Note that the implementation's return value is also available in the
method's post-condition(s) and the class's invariants, through the
subroutine value. In the above example, the implementation of append
returns the new size of the queue (i.e. what push returns), so the
post-condition could also be written:

     contract {
         method 'append';
             post { ${&value} == @{old->queue} + @_ }
             impl { push @{self->queue}, @_ };
     };

   Note that value will return a reference to a scalar or to an array,
depending on the context in which the method was originally called.

Clause control
--------------

   Any type of clause may be declared optional:

     contract {
             optional invar { @{self->list} > 0 };
             failmsg 'Empty queue detected at %s after call';
     };

   By default, optional clauses are still checked every time a method or
accessor is invoked, but they may also be switched off (and back on) at
run-time, using the check method:

     local $_ = 'Queue';         # Specify in $_ which class to disable
     check my %contract => 0;    # Disable optional checks for class Queue

   This (de)activation is restricted to the scope of the hash that is
passed as the first argument to check. In addition, the change only
affects the class whose name is held in the variable $_ at the time check
is called.  This makes it easy to (de)activate checks for a series of
classes:

     check %contract => 0 for qw(Queue PriorityQueue DEQueue);  # Turn off
     check %contract => 1 for qw(Stack PriorityStack Heap);     # Turn on

   The special value `'__ALL__'' may also be used as a (pseudo-)class name:

     check %contract => 0 for __ALL__;

   This enables or disables checking on every class defined using
Class::Contract. But note that only clauses that were originally declared
optional are affected by calls to check. Non-optional clauses are always
checked.

   Optional clauses are typically universally disabled in production code,
so Class::Contract provides a short-cut for this. If the module is
imported with the single argument `'production'', optional clauses are
universally and irrevocably deactivated. In fact, the optional subroutine
is replaced by:

     sub Class::Contract::optional {}

   so that optional clauses impose no run-time overhead at all.

   In production code, contract checking ought to be disabled completely,
and the requisite code optimized away.  To do that, simply change:

     use Class::Contract;

   to

     use Class::Contract::Production;

Inheritance
-----------

   The semantics of class inheritance for Class::Contract classes differ
in several respects from those of normal object-oriented Perl.

   To begin with, classes defined using Class::Contract have a *static
inheritance hierarchy*. The inheritance relationships of contracted classes
are defined using the `inherits' subroutine within the class's `contract'
block:

     package PriorityQueue;
     contract {
             inherits qw( Queue OrderedContainer );
     };

   That means that ancestor classes are fixed at compile-time (rather than
being determined at run-time by the @ISA array). Note that multiple
inheritance is supported.

   Method implementations are only inherited if they are not explicitly
provided. As with normal OO Perl, a method's implementation is inherited
from the left-most ancestral class that provides a method of the same name
(though with Class::Contract, this is determined at compile-time).

   Constructors are a special case, however. Their "constructive"
behaviour is always specific to the current class, and hence involves no
inheritance under any circumstances. However, the "initialising" behaviour
specified by a constructor's `impl' block *is* inherited. In fact, the
implementations of all base class constructors are called automatically by
the derived class constructor (in left-most, depth-first order), and
passed the same argument list as the invoked constructor. This behaviour
is much more like that of other OO programming languages (for example,
Eiffel or C++).

   Methods in a base class can also be declared as being abstract:

     contract {
         abstract method 'remove';
             post { ${self->count} == ${old->count}-1 };
     };

   Abstract methods act like placeholders in an inheritance hierarchy.
Specifically, they have no implementation, existing only to reserve the
name of a method and to associate pre- and post-conditions with it.

   An abstract method cannot be directly called (although its associated
conditions may be). If such a method is ever invoked, it immediately calls
croak. Therefore, the presence of an abstract method in a base class
requires the derived class to redefine that method, if the derived class
is to be usable. To ensure this, any constructor built by Class::Contract
will refuse to create objects belonging to classes with abstract methods.

   Methods in a base class can also be declared as being private:

     contract {
         private method 'remove';
             impl { pop @{self->queue} };
     };

   Private methods may only be invoked by the class or one of its
descendants.

Inheritance and condition checking
----------------------------------

   Attribute accessors and object methods inherit all post-conditions of
every ancestral accessor or method of the same name. Objects and classes
also inherit all invariants from any ancestor classes. That is, methods
accumulate all the post- and invariant checks that their ancestors
performed, as well as any new ones they define for themselves, and must
satisfy all of them in order to execute successfully.

   Pre-conditions are handled slightly differently. The principles of
design-by-contract programming state that pre-conditions in derived
classes can be no stronger than those in base classes (and may well be
weaker). In other words, a derived class must handle every case that its
base class handled, but may choose to handle other cases as well, by being
less demanding regarding its pre-conditions.

   Meyers suggests an efficient way to achieve this relaxation of
constraints without the need for detailed logical analysis of
pre-conditions. His solution is to allow a derived class method or
accessor to run if *either* the pre-conditions it inherits are satisfied
or its own pre-conditions are satisfied. This is precisely the semantics
that Class::Contract uses when checking pre-conditions in derived classes.

A complete example
------------------

   The following code implements a PriorityStack class, in which elements
pushed onto the stack "sink" until they encounter an element with lower
priority.  Note the use of old to check that object state has changed
correctly, and the use of explicit dispatch (e.g. `self->Stack::pop') to
invoke inherited methods from the derived-class methods that redefine them.

     package PriorityStack;
     use Class::Contract;

     contract {
         # Reuse existing implementation...
         inherits 'Stack';

     # Name the constructor (nothing special to do, so no implementation)
     ctor 'new';

     method 'push';
         # Check that data to be added is okay...
         pre  { defined $_[0] };
             failmsg 'Cannot push an undefined value';
         pre  { $_[1] > 0 };
             failmsg 'Priority must be greater than zero';

     # Check that push increases stack depth appropriately...
     post { self->count == old->count+1 };

     # Check that the right thing was left on top...
     post { old->top->{'priority'} <= self->top->{'priority'} };

     # Implementation reuses inherited methods: pop any higher
     # priority entries, push the new entry, then re-bury it...
     impl {
         my ($newval, $priority) = @_[0,1];
         my @betters;
         unshift @betters, self->Stack::pop
             while self->count
                && self->Stack::top->{'priority'} > $priority;
         self->Stack::push( {'val'=>$newval, priority=>$priority} );
         self->Stack::push( $_ )  foreach @betters;
     };

     method 'pop';
         # Check that pop decreases stack depth appropriately...
         post { self->count == old->count-1 };

     # Reuse inherited method...
     impl {
         return  unless self->count;
         return self->Stack::pop->{'val'};
     };

     method 'top';
         post { old->count == self->count }
         impl {
             return  unless self->count;
             return self->Stack::top->{'val'};
         };
             };

FUTURE WORK
===========

   Future work on Class::Contract will concentrate on three areas:

  1. Improving the attribute accessor mechanism Lvalue subroutines will be
     introduced in perl version 5.6. They will allow a return value to be
     treated as an alias for the (scalar) argument of a return statement.
     This will make it possible to write subroutines whose return value
     may be assigned to (like the built-in pos and substr functions).

     In the absence of this feature, Class::Contract accessors of all types
     return a reference to their attribute, which then requires an explicit
     dereference:

          ${self->value} = $newval;
          ${self->access_count}++;

     When this feature is available, accessors for scalar attributes will
     be able to return the actual attribute itself as an lvalue. The above
     code would then become cleaner:

          self->value = $newval;
          self->access_count++;

  2. Providing better software engineering tools.  Contracts make the
     consequences of inheritance harder to predict, since they
     significantly increase the amount of ancestral behaviour (i.e.
     contract clauses) that a class inherits.

     Languages such as Eiffel provide useful tools to help the software
     engineer make sense of this extra information. In particular, Eiffel
     provides two alternate ways of inspecting a particular class - flat
     form and short form.

     "Flattening" a class produces an equivalent class definition without
     any inheritance. That is, the class is modified by making explicit
     all the attributes, methods, conditions, and invariants it inherits
     from other classes. This allows the designer to see every feature a
     class possesses in one location.

     "Shortening" a class, takes the existing class definition and removes
     all implementation aspects of it - that is, those that have no
     bearing on its public interface. A shortened representation of a
     class therefore has all attribute specifications and method
     implementations removed. Note that the two processes can be
     concatenated: shortening a flattened class produces an explicit
     listing of its complete public interface. Such a representation can
     be profitably used as a basis for documenting the class.

     It is envisaged that Class::Contract will eventually provide a
     mechanism to produce equivalent class representations in Perl.

  3. Offering better facilities for retrofitting contracts.  At present,
     adding contractual clauses to an existing class requires a major
     restructuring of the original code. Clearly, if design-by-contract is
     to gain popularity with Perl programmers, this transition cost must
     be minimized.

     It is as yet unclear how this might be accomplished, but one
     possibility would be to allow the implementation of certain parts of a
     Class::Contract class (perhaps even the underlying object
     implementation itself) to be user-defined.


AUTHOR
======

   Damian Conway (damian@conway.org)

MAINTAINER
==========

   C. Garrett Goebel (ggoebel@cpan.org)

BUGS
====

   There are undoubtedly serious bugs lurking somewhere in code this funky
:-) Bug reports and other feedback are most welcome.

COPYRIGHT
=========

   Copyright (c) 1997-2000, Damian Conway. All Rights Reserved.  This
module is free software. It may be used, redistributed and/or modified
under the terms of the Perl Artistic License   (see
http://www.perl.com/perl/misc/Artistic.html)

   Copyright (c) 2000-2001, C. Garrett Goebel. All Rights Reserved.  This
module is free software. It may be used, redistributed and/or modified
under the terms of the Perl Artistic License   (see
http://www.perl.com/perl/misc/Artistic.html)