NAME
    Class::Declare - Declare classes with public, private and protected
    attributes and methods.

SYNOPSIS
      package My::Class;

      use strict;
      use warnings;
      use base qw( Class::Declare );

      __PACKAGE__->declare(

        public     => { public_attr     => 42         }  ,
        private    => { private_attr    => 'Foo'      }  ,
        protected  => { protected_attr  => 'Bar'      }  ,
        class      => { class_attr      => [ 3.141 ]  }
        static     => { static_attr     => { a => 1 } }  ,
        restricted => { restricted_attr => \'string'  }  ,
        abstract   => 'abstract_attr'                    ,
        friends    => 'main::trustedsub'                 ,
        new        => [ 'public_attr' , 'private_attr' ] ,
        init       => sub { # object initialisation
                        ...
                        1;
                      }                                  ,
        strict     => 0

      );

      sub publicmethod {
        my $self = __PACKAGE__->public( shift );
        ...
      }

      sub privatemethod {
        my $self = __PACKAGE__->private( shift );
        ...
      }

      sub protectedmethod {
        my $self = __PACKAGE__->protected( shift );
        ...
      }

      sub classmethod {
        my $self = __PACKAGE__->class( shift );
        ...
      }

      sub staticmethod {
        my $self = __PACKAGE__->static( shift );
        ...
      }

      sub restrictedmethod {
        my $self = __PACKAGE__->restricted( shift );
        ...
      }

      sub abstractmethod { __PACKAGE__->abstract }

      1;

      ...

      my $obj = My::Class->new( public_attr => 'fish' );


INSTALLATION
    To install this module type the following:

       perl Makefile.PL
       make
       make test
       make install
   
MOTIVATION
    One of Perl's greatest strengths is it's flexible object model. You can
    turn anything (so long as it's a reference, or you can get a reference
    to it) into an object. This allows coders to choose the most appropriate
    implementation for each specific need, and still maintain a consistent
    object oriented approach.

    A common paradigm for implementing objects in Perl is to use a blessed
    hash reference, where the keys of the hash represent attributes of the
    class. This approach is simple, relatively quick, and trivial to extend,
    but it's not very secure. Since we return a reference to the hash
    directly to the user they can alter hash values without using the
    class's accessor methods. This allows for coding "short-cuts" which at
    best reduce the maintainability of the code, and at worst may introduce
    bugs and inconsistencies not anticipated by the original module author.

    On some systems, this may not be too much of a problem. If the developer
    base is small, then we can trust the users of our modules to Do The
    Right Thing. However, as a module's user base increases, or the
    complexity of the systems our module's are embedded in grows, it may
    become desirable to control what users can and can't access in our
    module to guarantee our code's behaviour. A traditional method of
    indicating that an object's data and methods are for internal use only
    is to prefix attribute and method names with underscores. However, this
    still relies on the end user Doing The Right Thing.

    Class::Declare provides mechanisms for module developers to explicitly
    state where and how their class attributes and methods may be accessed,
    as well as hiding the underlying data store of the objects to prevent
    unwanted tampering with the data of the objects and classes. This
    provides a robust framework for developing Perl modules consistent with
    more strongly-typed object oriented languages, such as Java and C++,
    where classes provide "public", "private", and "protected" interfaces to
    object and class data and methods.

DESCRIPTION
    Class::Declare allows class authors to specify public, private and
    protected attributes and methods for their classes, giving them control
    over how their modules may be accessed. The standard object oriented
    programming concepts of *public*, *private* and *protected* have been
    implemented for both class and instance (or object) attributes and
    methods.

    Attributes and methods belong to either the *class* or an *instance*
    depending on whether they may be invoked via class instances (class and
    instance methods/attributes), or via classes (class methods/attributes
    only).

    Class::Declare uses the following definitions for *public*, *private*
    and *protected*:

    public
        Public attributes and methods may be accessed by anyone from
        anywhere. The term public is used by Class::Declare to refer to
        instance attributes and methods, while the equivalent for class
        attributes and methods are given the term class attributes and
        methods.

    private
        Private attributes and methods may be accessed only by the class
        defining them and instances of that class. The term private is used
        to refer to instance methods and attributes, while the term static
        refers to class attributes and methods that exhibit the same
        properties.

    protected
        Protected attributes and methods may only be accessed by the
        defining class and it's instances, and classes and objects derived
        from the defining class. Protected attributes and methods are used
        to define the interface for extending a given class (through normal
        inheritance/derivation). The term protected is used to refer to
        protected instance methods and attributes, while protected class
        methods and attributes are referred to as restricted.

        Note: since version 0.02, protected class methods and attributes are
        refered to as *restricted*, rather than *shared*. This change was
        brought about by the introduction of Class::Declare::Attributes and
        then clash with the existing Perl threading attribute :shared. The
        term *restricted* has been chosen to reflect that the use of these
        methods and attributes is restricted to the family of classes
        derived from the base class.

    The separation of terms for class and instance methods and attributes
    has been adopted to simplify class declarations. See declare() below.

    Class attributes are regarded as constant by Class::Declare: once
    declared they may not be modified. Instance attributes, on the other
    hand, are specific to each object, and may be modified at run-time.

    Internally, Class::Declare uses hashes to represent the attributes of
    each of its objects, with the hashes remaining local to Class::Declare.
    To the user, the objects are represented as references to scalars which
    Class::Declare maps to object hashes in the object accessors. This
    prevents users from accessing object and class data without using the
    class's accessors.

    The granting of access to attributes and methods is determined by
    examining the *target* of the invocation (the first parameter passed to
    the method, usually represented by $self), as well as the *context* of
    the invocation (where was the call made and who made it, determined by
    examining the caller() stack). This adds an unfortunate but necessary
    processing overhead for Class::Declare objects for each method and
    attribute access. While this overhead has been kept as low as possible,
    it may be desirable to turn it off in a production environment.
    Class::Declare permits disabling of the access control checks on a
    per-module basis, which may greatly improve the performance of an
    application. Refer to the *strict* parameter of declare() below for more
    information.

    Class::Declare inherits from Exporter, so modules derived from
    Class::Declare can use the standard symbol export mechanisms. See
    Exporter for more information.

  Defining Classes
    To define a Class::Declare-derived class, a package must first "use"
    Class::Declare and inherit from it (either by adding it to the @ISA
    array, or through "use base"). Then Class::Declare::declare() must be
    called with the new class's name as its first parameter, followed by a
    list of arguments that actually defines the class. For example:

      package My::Class;

      use strict;
      use warnings;
      use base qw( Class::Declare );

      __PACKAGE__->declare( ... );

      1;

    Class::Declare::declare() is a class method of Class::Declare and has
    the following call syntax and behaviour:

    declare( [ *param* => *value* ] )
        declare()'s primary task is to define the attributes of the class
        and its instances. In addition, it supports options for defining
        object initialisation code, friend methods and classes, and the
        application of strict access checking. *param* may have one of the
        following values:

        *public*
            *public* expects either a hash reference of attribute names and
            default values, an array reference containing attribute names
            whose default values will be "undef", or a single attribute name
            whose value will default to "undef". These represent the public
            attributes of this class. Class::Declare constructs accessor
            methods within the class, with the same name as the attributes.
            These methods are "lvalue" methods by default (see also
            Attribute Modifiers below), which means that the attributes may
            be assigned to, as well as being set by passing the new value as
            an accessor's argument.

            For example:

              package My::Class;

              use strict;
              use warnings;
              use base qw( Class::Declare );

              __PACKAGE__->declare( public => { name => 'John' } );

              1;

              my $obj = My::Class->new;
              print $obj->name . "\n";    # prints 'John'
                    $obj->name = 'Fred';  # the 'name' attribute is now 'Fred'
                    $obj->name( 'Mary' ); # the 'name' attribute is now 'Mary'

            The default value of each attribute is assigned during the
            object initialisation phase (see *init* and new() below). Public
            attributes may be set during the object creation call:

              my $obj = My::Class->new( name => 'Jane' );
              print $obj->name . "\n"; # prints 'Jane'

            *public* attributes are instance attributes and therefore may
            only be accessed through class instances, and not through the
            class itself.

            Note that the declare() call for "My::Class" from above could
            have been written as

              __PACKAGE__->declare( public => [ qw( name ) ] );

            or

              __PACKAGE__->declare( public => 'name' );

            In these cases, the attribute "name" would have had a default
            value of "undef".

        *private*
            As with *public* above, but the attributes are private (i.e.
            only accessible from within this class). If access is attempted
            from outside the defining class, then an error will be reported
            through die(). *Private* attributes may not be set in the call
            to the constructor, and as with *public* attributes, are
            instance attributes. See also *strict* and *friends* below.

        *protected*
            As with *private* above, but the attributes are protected (i.e.
            only accessible from within this class, and all classes that
            inherit from this class). Protected attributes are instance
            attributes, and they may not be set in the call to the
            constructor. See also *strict* and *friends* below.

        *class*
            This declares class attributes in the same manner as *public*
            above. *class* attributes are not restricted to object
            instances, and may be accessed via the class directly. The
            accessor methods created by Class::Declare, however, are not
            "lvalue" methods, and cannot, therefore, be assigned to. Nor can
            the values be set through the accessor methods. They behave in
            the same manner as values declared by "use constant" (except
            they must be called as class or instance methods). *class*
            attributes may not be set in the call to the constructor.

        *static*
            As with *class* attributes, except access to "static" attributes
            is limited to the defining class and its objects. *static*
            attributes are the class-equivalent of *private* instance
            attributes. See also *friends*.

        *restricted*
            As with *class* attributes, except access to "restricted"
            attributes is limited to the defining class and all classes that
            inherit from the defining class, and their respective objects.
            *restricted* attributes are the class-equivalent of *protected*
            instance attributes. See also *friends*.

        *abstract*
            This declares the set of abstract methods provided by this
            class, and will cause the generation of stub routines that die()
            when invoked, ensuring derived classes define these methods.

        *friends*
            Here you may specify classes and methods that may be granted
            access to the defining classes *private*, *protected*, *static*
            and *restricted* attributes and methods. *friends* expects
            either a single value, or a reference to a list of values. These
            values may either be class names, or fully-qualified method
            names (i.e. class and method name). When a call is made to a
            private or protected method or attribute accessor, and a friend
            has been declared, a check is performed to see if the caller is
            within a friend package or is a friend method. If so, access is
            granted. Otherwise, access is denied through a call to die().

            Note that friend status may not be inherited. This is to avoid
            scenarios such as the following:

              package My::Class;

              use strict;
              use warnings;
              use base qw( Class::Declare );

              __PACKAGE__->declare( ...
                                    friends => 'My::Trusted::Class' );
              1;

              package My::Trusted::Class;
              ...
              1;

              package Spy::Class;

              use strict;
              use warnings;
              use base qw( My::Trusted::Class );

              sub infiltrate {
                .. do things here to My::Class objects that we shouldn't
              }

              1;

        *init*
            This defines the object initialisation code, which is executed
            as the last phase of object creation by new(). *init* expects a
            "CODEREF" which is called with the first argument being the new
            object being created by the call to new(). The initialisation
            routine is expected to return a true value to indicate success.
            A false value will cause new() to "die()" with an error. The
            initialisation routines are invoked during object creation by
            new(), after default and constructor attribute values have been
            assigned.

            If the inheritance tree of a class contains multiple *init*
            methods, then these will be executed in reverse @ISA order to
            ensure the primary base-class of the new class has the final say
            on object initialisation (i.e. the class left-most in the @ISA
            array will have it's *init* routine executed last). If a class
            appears multiple times in an @ISA array, either through
            repetition or inheritance, then it will only be executed once,
            and as early in the *init* execution chain as possible.

            Class::Declare uses a "CODEREF" rather than specifying a default
            initialisation subroutine (e.g. "sub INIT { ... }") to avoid
            unnecessary pollution of class namespaces. There is generally no
            need for initialisation routines to be accessible outside of
            new().

        *new*
            If *new* is defined, then it should contain a list (either a
            single value or an array reference) of the instance attributes
            (public, private or protected) that may be set in the call to
            the constructor new(). This permits the exposure of protected
            and private attributes during construction (and thus permitting
            read-only protected and private attributes). *new* makes it
            possible to do the following:

              package My::Class;

              use strict;
              use warnings;
              use base qw( Class::Declare );

              __PACKAGE__->declare(

                public  => { mypublic  => undef } ,
                private => { myprivate => undef } ,
                new     => [ qw( myprivate ) ]

              );

              1;

              ...

              my  $obj  = My::Class->new( myprivate => 1 );

            Note that if *new* is specified in a call to declare() then only
            those attributes listed in the value of *new* may be defined in
            the call to the constructor new() (overriding the default
            behaviour of allowing public attributes). In addition, the
            attributes must be defined in this class, and not inherited.
            This prevents unintended access such as:

              public My::Class;

              use strict;
              use warnings;
              use base qw( Class::Declare );

              __PACKAGE__->declare(
  
                private => { myprivate => undef }

              );

              1;

              ...

              public Bad::Class;

              use strict;
              use warnings;
              use base qw( My::Class );

              __PACKAGE__->declare(

                # this will throw an error with die()
                new => 'myprivate'

              );

              1;

        *strict*
            If *strict* is set to *true*, then Class::Declare will define
            class(), static(), restricted(), public(), private(), and
            protected() methods (see "Class Methods" and "Object Methods"
            below) within the current package that enforce the
            class/static/restricted/public/private/protected relationships
            in method calls.

            If *strict* is set to *false* and defined (e.g. 0, not "undef"),
            then Class::Declare will convert the above method calls to
            no-ops, and no invocation checking will be performed. Note that
            this conversion is performed for this class only.

            By setting *strict* to "undef" (or omitting it from the call to
            declare() altogether), Class::Declare will not create these
            methods in the current package, but will rather let them be
            inherited from the parent class. In this instance, if the
            parent's methods are no-ops, then the child class will inherit
            no-ops. Note that the public(), private(), etc methods from
            Class::Declare enforce the public/private/etc relationships.

            One possible use of this feature is as follows:

              package My::Class;

              use strict;
              use warnings;
              use base qw( Class::Declare );

              __PACKAGE__->declare( public    => ...                ,
                                    private   => ...                ,
                                    protected => ...                ,
                                    strict    => $ENV{ USE_STRICT } );

              ...

              1;

            Here, during development and testing the environment variable
            "USE_STRICT" may be left undefined, or set to true to help
            ensure correctness of the code, but then set to false (e.g. 0)
            in production to avoid the additional computational overhead.

            Setting *strict* to *false* does not interfere with the
            friends() method (see below). Turning strict access checking off
            simply stops the checks from being performed and does not change
            the logic of whether a class or method as been declared as a
            friend of a given class.

        Note:

        *   declare() may be called only once per class to prevent class
            redefinitions

        *   attribute names specified in the call to declare() may not be
            the same as class and instance methods already defined in the
            class

        *   attribute names must be unique for a class

        If any of the above rules are violated, then declare() will raise an
        error with die().

  Creating Objects
    Once a Class::Declare-derived class has been declared, instances of that
    class may be created through the new() method supplied by
    Class::Declare. new() may be called either as a class or an instance
    method. If called as a class method, a new instance will be created,
    using the class's default attribute values as the default values for
    this instance. If new() is called as an instance method, the default
    attribute values for the new instance will be taken from the invoking
    instance. This may be used to clone Class::Declare-derived objects.

    Class::Declare::new() has the following call syntax and behaviour:

    new( [ *param* => *value* ] )
        new() creates instances of Class::Declare objects. If a problem
        occurs during the creation of an object, such as the failure of an
        object initialisation routine, then new() will raise an error
        through die().

        When called as a class method, new() will create new instances of
        the specified class, using the class's default attribute values. If
        it's called as an instance method, then new() will clone the
        invoking object.

        new() accepts named parameters as arguments, where *param*
        corresponds to a *public* attribute of the class of the object being
        created. If an unknown attribute name, or a non-*public* attribute
        name is specified, then new() will die() with an error. Public
        attribute values specified in the call to new() are assigned after
        the creation of the object, to permit over-riding of default values
        (either class-default attributes or attributes cloned from the
        invoking object).

        new() can be extended to accept non-public instance attributes as
        parameters through the specification of the *new* attribute of
        declare() (see above). In this instance, only the attributes listed
        in the definition of *new* in declare() will be accepted, and all
        public attributes will only be accepted if contained within this
        list.

        If the calling class, or any of its base classes, has an object
        initialisation routine defined (specified by the *init* parameter of
        declare()), then these routines will be invoked in reverse @ISA
        order, once the object's attribute values have been set. An
        initialisation routine may only be called once per class per object,
        so if a class appears multiple times in the @ISA array of the new
        object's class, then the base class's initialisation routine will be
        called as early in the initialisation chain as possible, and only
        once (i.e. as a result of the right-most occurrence of the base
        class in the @ISA array).

        The initialisation routines should return a true value to indicate
        success. If any of the routines fail (i.e. return a false value),
        then new() will die() with an error.

    When a new instance is created, instance attributes (i.e. *public*,
    *private* and *protected* attributes) are cloned, so that the new
    instance has a copy of the default values. For values that are not
    references, this amounts to simply copying the value through assignment.
    For values that are references, Storable::dclone() is used to ensure
    each instance has it's own copy of the references data structure (the
    structures are local to each instance).

    However, if an instance attribute value is a "CODEREF", then new()
    simply copies the reference to the new object, since "CODEREF"s cannot
    be cloned.

    Class attributes are not cloned as they are assumed to be constant
    across all object instances.

  Class Access Control Methods
    Class::Declare provides the following class methods for implementing
    *class*, *static* and *restricted* access control in class methods.
    These methods may be called either through a Class::Declare-derived
    class, or an instance of such a class.

    Note that a *class* method is a *public* class method, a *static* method
    is a *private* class method, and a *restricted* method is a *protected*
    class method.

    abstract( *target* )
        Ensure a method is implemented, but throwing a fatal error (i.e.
        die()'ing if called).

    class( *target* )
        Ensure a method is called as a class method of this package via the
        *target*.

          sub myclasssub {
            my $self = __PACKAGE__->class( shift );
            ...
          }

        A *class* method may be called from anywhere, and *target* must
        inherit from this class (either an object or instance). If class()
        is not invoked in this manner, then class() will die() with an
        error.

        See also the *strict* parameter for declare() above.

    static( *target* )
        Ensure a method is called as a static method of this package via
        *target*.

          sub mystaticsub {
            my $self = __PACKAGE__->static( shift );
            ...
          }

        A *static* method may only be called from within the defining class,
        and *target* must inherit from this class (either an object or
        instance). If static() is not invoked in this manner, then static()
        will die() with an error.

        See also the *strict* and *friends* parameters for declare() above.

    restricted( *target* )
        Ensure a method is called as a restricted method of this package via
        *target*.

          sub myrestrictedsub {
            my $self = __PACKAGE__->restricted( shift );
            ...
          }

        A *restricted* method may only be called from within the defining
        class or a class that inherits from the defining class, and *target*
        must inherit from this class (either an object or instance). If
        restricted() is not invoked in this manner, then restricted() will
        die() with an error.

        See also the *strict* and *friends* parameters for declare() above.

        Note: restricted() was called shared() in the first release of
        Class::Declare. However, with the advent of
        Class::Declare::Attributes, there was a clash between the use of
        :shared as an attribute by Class::Declare::Attributes, and the Perl
        use of :shared attributes for threading.

  Instance Access Control Methods
    Class::Declare provides the following instance methods for implementing
    *public*, *private* and *protected* access control in instance methods.
    These methods may only be called through a Class::Declare-derived
    instance.

    public( *target* )
        Ensure a method is called as a public method of this class via
        *target*.

          sub mypublicsub {
            my $self = __PACKAGE__->public( shift );
            ...
          }

        A *public* method may be called from anywhere, and *target* must be
        an object that inherits from this class. If public() is not invoked
        in this manner, then public() will die() with an error.

        See also the *strict* parameter for declare() above.

    private( *target* )
        Ensure a method is called as a private method of this class via
        *target*.

          sub myprivatesub {
            my $self = __PACKAGE__->private( shift );
            ...
          }

        A *private* method may only be called from within the defining
        class, and *target* must be an instance that inherits from this
        class. If private() is not invoked in this manner, then private()
        will die() with an error.

        See also the *strict* and *friends* parameters for declare() above.

    protected( *target* )
        Ensure a method is called as a protected method of this class via
        *target*.

          sub myprotectedsub {
            my $self = __PACKAGE__->protected( shift );
            ...
          }

        A *protected* method may only be called from within the defining
        class or a class that inherits from the defining class, and *target*
        must be an instance that inherits from this class. If protected() is
        not invoked in this manner, then protected() will die() with an
        error.

        See also the *strict* and *friends* parameters for declare() above.

  Destroying Objects
    Object destruction is handled via the normal Perl "DESTROY()" method.
    Class::Declare implements a "DESTROY()" method that performs clean-up
    and house keeping, so it is important that any class derived from
    Class::Declare that requires a "DESTROY()" method ensures that it
    invokes it's parent's "DESTROY()" method, using a paradigm similar to
    the following:

      sub DESTROY
      {
        my $self = __PACKAGE__->public( shift );

        ... do local clean-up here ..

        # call the parent clean-up
           $self->SUPER::DESTROY( @_ );
      } # DESTROY()

  Attribute Modifiers
    By default Class::Declare class attributes ("class", "static", and
    "restricted") are *read-only*, while instance attributes ("public",
    "private", and "protected") are *read-write*. Class::Declare provides
    two attribute modifiers, rw and ro for changing this behaviour, allowing
    class attributes to be read-write, and instance attributes to be read
    only.

    The modifiers may be imported separately,

      use Class::Declare qw( :read-only  );

    or

      use Class::Declare qw( ro );

    or

      use Class::Declare qw( :read-write );

    or

      use Class::Declare qw( rw );

    or collectively, using the ":modifiers" tag.

      use Class::Declare qw( :modifiers );

    To use the modifiers, they must be incorporated into the attribute
    definition for the class. For example:

      package My::Class;

      use strict;
      use Class::Declare qw( :modifiers );
      use vars           qw( @ISA );
          @ISA = qw( Class::Declare );

      __PACKAGE__->declare( class  => { my_class  => rw undef } ,
                            public => { my_public => ro 1234  } );

    Here, the attribute "my_class" has been declared *read-write* by rw,
    permitting it's value to be changed at run time. The public attribute
    "my_public" has been declared *read-only* by ro, preventing it from
    being changed once set. Please note that although they may be marked as
    *read-only*, public attributes may still be set during object creation
    (i.e. in the call to new()). However, once set, the value may not be
    changed.

    rw  Declare a class attribute to be *read-write*, instead of defaulting
        to read-only. Note that this has no effect on instance attributes as
        they are read-write by default.

    ro  Declare an instance attribute to be *read-only*, instead of
        defaulting to read-write. Note that this has no effect on class
        attributes as they are read-only by default.

  Serialising Objects
    Class::Declare objects may be serialised (and therefore cloned) by using
    Storable. Class::Declare uses Storable::dclone() itself during object
    creation to copy instance attribute values. However, Storable is unable
    to serialise "CODEREF"s, and attempts to do so will fail. This causes
    the failure of serialisation of Class::Declare objects that have
    "CODEREF"s as attribute values. However, for cloning, Class::Declare
    avoids this problem by simply copying "CODEREF"s from the original
    object to the clone.

  Miscellaneous Methods
    The following methods are class methods of Class::Declare provided to
    simplify the creation of classes. They are provided as convenience
    methods, and may be called as either class or instance methods.

    friend()
        Returns *true* if the calling class or method is a friend of the
        given class or object. That is, for a given object or class,
        friend() will return *true* if it is called within the context of a
        class or method that has been granted friend status by the object or
        class (see *friend* in declare() above). A friend may access
        *private*, *protected*, *static* and *restricted* methods and
        attributes of a class and it's instances, but not of derived
        classes.

        friend() will return true for a given class or object if called
        within that class. That is, a class is always it's own friend.

        In all other circumstances, friend() will return *false*.

          package Class::A;

          my $object = Class::B;

          sub somesub {
            ...
            $object->private_method   if ( $object->friend );
            ...
          }

    dump( [ *param* => *value* ] )
        Generate a textual representation of an object or class. Since
        Class::Declare objects are represented as references to scalars,
        Data::Dumper is unable to generate a meaningful dump of
        Class::Declare-derived objects. dump() pretty-prints objects,
        showing their attributes and their values. dump() obeys the access
        control imposed by Class::Declare on it's objects and classes,
        limiting it's output to attributes a caller has been granted access
        to see or use.

        dump() will always observe the access control mechanisms as
        specified by Class::Declare::class(), Class::Declare::private(),
        etc, and it's behaviour is not altered by the setting of *strict* in
        declare() to be *false* (see declare() above). This is because
        *strict* is designed as a mechanism to accelerate the execution of
        Class::Declare-derived modules, not circumvent the intended access
        restrictions of those modules.

        dump() accepts the following optional named parameters:

        *all*
            If *all* is true (the default value), and none of the
            attribute/method type parameters (e.g. *public*, *static*, etc)
            have been set, then dump() will display all attributes the
            caller has access to. If any of the attribute type parameters
            have been set to true, then *all* will be ignored, and only
            those attribute types specified in the call to dump() will be
            displayed.

        *class*
            If *class* is true, then dump() will display only *class*
            attributes of the invocant and their values, and all other types
            of attributes explicitly requested in the call to dump() (the
            *all* parameter is ignored). If the caller doesn't have access
            to *class* methods, then dump() will die() with an error. If no
            class attributes exist, and no other attributes have been
            requested then "undef" is returned.

        *static*
            As with *class*, but displaying *static* attributes and their
            values.

        *restricted*
            As with *class*, but displaying *restricted* attributes and
            their values.

        *public*
            As with *class*, but displaying *public* attributes and their
            values. Note that *public* attributes can only be displayed for
            class instances. Requesting the dump() of public attributes of a
            class will result in dump() die()ing with an error.

        *private*
            As with *public*, but displaying *private* attributes and their
            values.

        *protected*
            As with *public*, but displaying *protected* attributes and
            their values.

        *friends*
            If *friends* is true, then dump() will display the list of
            friends of the invoking class or object.

        *depth*
            By default, dump() operates recursively, creating a dump of all
            requested attribute values, and their attribute values (if they
            themselves are objects). If *depth* is set, then *dump()* will
            limit it's output to the given recursive depth. A depth of 0
            will display the target's attributes, but will not expand those
            attribute values.

        *indent*
            *indent* specifies the indentation used in the output of dump(),
            and defaults to 4 spaces.

        *backtrace*
            If *backtrace* is true, the *dump()* will back-trace references
            if they are encountered multiple times in the generation of
            the *dump()* output. The back-trace is similar to the default
            behaviour of Data::Dumper, where only the first instance
            of a reference is shown in full, and all other occurences are
            displayed as a link back to the original occurrence of that
            reference. By default, *backtrace* is true.


        If an attribute type parameter, such as *static* or *private*, is
        set in the call to dump() then this only has effect on the target
        object of the dump() call, and not any subsequent recursive calls to
        dump() used to display nested objects.

        The code to implement dump() is quite long, and so has been split
        into a separate module Class::Declare::Dump. The first time dump()
        is called on a Class::Declare-derived object or class,
        Class::Declare::Dump is loaded, and the dump generated. If the
        loading of Class::Declare::Dump fails, a warning is given, and
        dump() returns the stringification of the given class or instance.

    hash( [ *param* => *value* ] )
        Return a hash representing the values of the attributes of the class
        or object (depending on how hash() is called. hash() supports the
        same calling parameters as dump(), except for "friends" and "indent".
        hash() observes normal access control, only returning attributes that
        the caller would normally have access to. "abstract" attributes are
        returned with a value of "undef".

        If called in a list context, hash() will return a hash, otherwise a
        hash reference is returned.

        Note: As of v0.10, hash() supports the "depth" parameter, and will,
        by default, recurse to generate a hash of the entire object tree
        (if derived from Class::Declare. If "depth" is set, then "hash()"
        will limit it's output to the given recursive depth. A depth of 0
        will display the target's attributes, but will not expand those
        attribute values.

    arguments( *args* => *default* )
        A class helper method for handling named argument lists. In Perl,
        named argument lists are supported by coercing a list into a hash by
        assuming a key/value pairing. For example, named arguments may be
        implemented as

          sub mysub {
            my  %args = @_;
            ...
          }

        and called as

          mysub( name => 'John' , age => 34 );

        %args is now the hash with keys "name" and "age" and corresponding
        values 'John' and 34 respectively.

        So if named arguments are so easy to implement, why go to the
        trouble of calling arguments()? To make your code more robust. The
        above example failed to test whether there was an even number of
        elements in the argument list (needed to flatten the list into a
        hash), and it made no checks to ensure the supplied arguments were
        expected. Does "mysub()" really want a name and age, or does it want
        some other piece of information?

        arguments() ensures the argument list can be safely flattened into a
        hash, and raises an error indicating the point at which the original
        method was called if it can't. Also, it ensures the arguments passed
        in are those expected by the method. Note that this does not check
        the argument values themselves, but merely ensures unknown named
        arguments are flagged as errors.

        arguments() also enables you to define default values for your
        arguments. These values will be assigned when a named argument is
        not supplied in the list of arguments.

        The calling convention of arguments() is as follows (note, we assume
        here that the method is in a Class::Declare-derived class):

          sub mysub {
            ...
            my %args = $self->arguments( \@_ => { name => 'Guest user' ,
                                                  age  => undef        } );
            ...
          }

        Here, "mysub()" will accept two arguments, "name" and "age", where
        the default value for "name" is 'Guest user', while "age" defaults
        to "undef".

        Alternatively, arguments() may be called in either of the following
        ways:

            my %args = $self->arguments( \@_ => [ qw( name age ) ] );

        or

            my %args = $self->arguments( \@_ => 'name' );

        Here, the default argument values are "undef", and in the second
        example, only the the single argument *name* will be recognized.

        If *default* is not given (or is undef), then arguments() will
        simply flatten the argument list into a hash and assume that all
        named arguments are valid. If *default* is the empty hash (i.e.
        "{}"), then no named arguments will be accepted.

        If called in a list context, arguments() returns the argument hash,
        while if called in a scalar context, arguments() will return a
        reference to the hash. arguments() may be called as either a class
        or instance method.

    REVISION()
        Extract the revision number from CVS revision strings. REVISION()
        looks for the package variable $REVISION for a valid CVS revision
        strings, and if found, will return the revision number from the
        string. If $REVISION is not defined, or does not contain a CVS
        revision string, then REVISION() returns "undef".

          package My::Class;

          use strict;
          use base qw( Class::Declare );
          use vars qw( $REVISION      );
                       $REVISION = '$Revision: 1.14 $';

          ...

          1;

          print My::Class->REVISION;  # prints the revision number

    VERSION()
        Replacement for UNIVERSAL::VERSION(), that falls back to REVISION()
        to report the CVS revision number as the version number if the
        package variable $VERSION is not defined.

    has( *method* )
        If this class directly implements the given *method*(), then return
        a reference to this method. Otherwise, return false. This is similar
        to UNIVERSAL::can(), which will return a reference if this class
        either directly implements *method*(), or inherits it.

    strict()
        If this class is operating with strict access checking (i.e.
        *strict* from declare() was not explicitly set to false in this
        class or one of its parent classes) then strict() will return true,
        otherwise return false.

CAVEAT
    Class::Declare has been designed to be thread-safe, and as such is
    suitable for such environments as "mod_perl". However, it has not been
    proven to be thread-safe. If you are coding in a threaded environment,
    and experience problems with Class::Declare's behaviour, please let me
    know.

BUGS
    The name. I don't really like Class::Declare as a name, but I can't
    think of anything more appropriate. I guess it really doesn't matter too
    much. Suggestions welcome.

    Apart from the name, Class::Declare has no known bugs. That is not to
    say the bugs don't exist, rather they haven't been found. The testing
    for this module has been quite extensive (there are over 3000 test cases
    in the module's test suite), but patches are always welcome if you
    discover any problems.

SEE ALSO
    Class::Declare::Dump, Class::Declare::Attributes, Exporter, Storable,
    perlboot, perltoot.

AUTHOR
    Ian Brayshaw, <ian@onemore.org>

COPYRIGHT AND LICENSE
    Copyright 2003-2007 Ian Brayshaw. All rights reserved.

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

