GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CLASS::DECLARE (3)

.ds Aq ’

NAME

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

CONTENTS

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 );



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.

<B>Class::DeclareB> 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

<B>Class::DeclareB> 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).

<B>Class::DeclareB> uses the following definitions for public, private and protected:
<B>publicB> Public attributes and methods may be accessed by anyone from anywhere. The term <B>publicB> is used by <B>Class::DeclareB> to refer to instance attributes and methods, while the equivalent for class attributes and methods are given the term <B>classB> attributes and methods.
<B>privateB> Private attributes and methods may be accessed only by the class defining them and instances of that class. The term <B>privateB> is used to refer to instance methods and attributes, while the term <B>staticB> refers to class attributes and methods that exhibit the same properties.
<B>protectedB> 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 <B>protectedB> is used to refer to protected instance methods and attributes, while protected class methods and attributes are referred to as <B>restrictedB>.

<B>Note:B> 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 <B>:sharedB>. 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 <B>B>declare()<B>B> below.

Class attributes are regarded as constant by <B>Class::DeclareB>: 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, <B>Class::DeclareB> uses hashes to represent the attributes of each of its objects, with the hashes remaining local to <B>Class::DeclareB>. To the user, the objects are represented as references to scalars which <B>Class::DeclareB> 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 <B>Class::DeclareB> 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. <B>Class::DeclareB> 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 <B>B>declare()<B>B> below for more information.

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

    Defining Classes

To define a <B>Class::DeclareB>-derived class, a package must first use <B>Class::DeclareB> and inherit from it (either by adding it to the @ISA array, or through use base). Then <B>B>Class::Declare::declare()<B>B> 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;



<B>B>Class::Declare::declare()<B>B> is a class method of <B>Class::DeclareB> and has the following call syntax and behaviour:
<B>declare(B> [ param => value ] <B>)B> <B>B>declare()<B>B>’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. <B>Class::DeclareB> constructs accessor methods within the class, with the same name as the attributes. These methods are lvalue methods by default (see also <B>Attribute ModifiersB> 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 <B>B>new()<B>B> 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 <B>B>declare()<B>B> 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 <B>B>die()<B>B>. 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 <B>Class::DeclareB>, 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 <B>B>die()<B>B>.

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 shouldnt
  }

  1;



init This defines the object initialisation code, which is executed as the last phase of object creation by <B>B>new()<B>B>. init expects a CODEREF which is called with the first argument being the new object being created by the call to <B>B>new()<B>B>. The initialisation routine is expected to return a true value to indicate success. A false value will cause <B>B>new()<B>B> to die() with an error. The initialisation routines are invoked during object creation by <B>B>new()<B>B>, 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.

<B>Class::DeclareB> 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 <B>B>new()<B>B>.

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 <B>B>new()<B>B>. 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 <B>B>declare()<B>B> then <B>onlyB> those attributes listed in the value of new may be defined in the call to the constructor <B>B>new()<B>B> (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 <B>Class::DeclareB> will define <B>B>class()<B>B>, <B>B>static()<B>B>, <B>B>restricted()<B>B>, <B>B>public()<B>B>, <B>B>private()<B>B>, and <B>B>protected()<B>B> 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 <B>Class::DeclareB> 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 <B>B>declare()<B>B> altogether), <B>Class::DeclareB> 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 <B>B>public()<B>B>, <B>B>private()<B>B>, etc methods from <B>Class::DeclareB> 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 <B>B>friends()<B>B> 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.

<B>Note:B>
o <B>B>declare()<B>B> may be called only once per class to prevent class redefinitions
o attribute names specified in the call to <B>B>declare()<B>B> may not be the same as class and instance methods already defined in the class
o attribute names must be unique for a class

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

    Creating Objects

Once a <B>Class::DeclareB>-derived class has been declared, instances of that class may be created through the <B>B>new()<B>B> method supplied by <B>Class::DeclareB>. <B>B>new()<B>B> 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 <B>B>new()<B>B> 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 <B>Class::DeclareB>-derived objects.

<B>B>Class::Declare::new()<B>B> has the following call syntax and behaviour:
<B>new(B> [ param => value ] <B>)B> <B>B>new()<B>B> creates instances of <B>Class::DeclareB> objects. If a problem occurs during the creation of an object, such as the failure of an object initialisation routine, then <B>B>new()<B>B> will raise an error through <B>B>die()<B>B>.

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

<B>B>new()<B>B> 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 <B>B>new()<B>B> will <B>B>die()<B>B> with an error. Public attribute values specified in the call to <B>B>new()<B>B> 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).

<B>B>new()<B>B> can be extended to accept non-public instance attributes as parameters through the specification of the new attribute of <B>B>declare()<B>B> (see above). In this instance, only the attributes listed in the definition of new in <B>B>declare()<B>B> 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 <B>B>declare()<B>B>), 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 <B>B>new()<B>B> will <B>B>die()<B>B> 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, <B>B>Storable::dclone()<B>B> 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 <B>B>new()<B>B> simply copies the reference to the new object, since CODEREFs cannot be cloned.

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

    Class Access Control Methods

<B>Class::DeclareB> provides the following class methods for implementing class, static and restricted access control in class methods. These methods may be called either through a <B>Class::DeclareB>-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.
<B>abstract(B> target <B>)B> Ensure a method is implemented, but throwing a fatal error (i.e. die()’ing if called).
<B>class(B> target <B>)B> 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 <B>B>class()<B>B> is not invoked in this manner, then <B>B>class()<B>B> will <B>B>die()<B>B> with an error.

See also the strict parameter for <B>B>declare()<B>B> above.

<B>static(B> target <B>)B> 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 <B>B>static()<B>B> is not invoked in this manner, then <B>B>static()<B>B> will <B>B>die()<B>B> with an error.

See also the strict and friends parameters for <B>B>declare()<B>B> above.

<B>restricted(B> target <B>)B> 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 <B>B>restricted()<B>B> is not invoked in this manner, then <B>B>restricted()<B>B> will <B>B>die()<B>B> with an error.

See also the strict and friends parameters for <B>B>declare()<B>B> above.

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

    Instance Access Control Methods

<B>Class::DeclareB> provides the following instance methods for implementing public, private and protected access control in instance methods. These methods may only be called through a <B>Class::DeclareB>-derived instance.
<B>public(B> target <B>)B> 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 <B>B>public()<B>B> is not invoked in this manner, then <B>B>public()<B>B> will <B>B>die()<B>B> with an error.

See also the strict parameter for <B>B>declare()<B>B> above.

<B>private(B> target <B>)B> 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 <B>B>private()<B>B> is not invoked in this manner, then <B>B>private()<B>B> will <B>B>die()<B>B> with an error.

See also the strict and friends parameters for <B>B>declare()<B>B> above.

<B>protected(B> target <B>)B> 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 <B>B>protected()<B>B> is not invoked in this manner, then <B>B>protected()<B>B> will <B>B>die()<B>B> with an error.

See also the strict and friends parameters for <B>B>declare()<B>B> above.

    Destroying Objects

Object destruction is handled via the normal Perl DESTROY() method. <B>Class::DeclareB> implements a DESTROY() method that performs clean-up and house keeping, so it is important that any class derived from <B>Class::DeclareB> 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 <B>Class::DeclareB> class attributes (class, static, and restricted) are read-only, while instance attributes (public, private, and protected) are read-write. <B>Class::DeclareB> provides two attribute modifiers, <B>rwB> and <B>roB> 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 <B>rwB>, permitting it’s value to be changed at run time. The public attribute my_public has been declared read-only by <B>roB>, 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 <B>B>new()<B>B>). However, once set, the value may not be changed.
<B>rwB> 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.
<B>roB> 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

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

    Miscellaneous Methods

The following methods are class methods of <B>Class::DeclareB> provided to simplify the creation of classes. They are provided as convenience methods, and may be called as either class or instance methods.
<B>friend(B><B>)B> 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, <B>B>friend()<B>B> 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 <B>B>declare()<B>B> 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.

<B>B>friend()<B>B> 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, <B>B>friend()<B>B> will return false.



  package Class::A;

  my $object = Class::B;

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



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

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

<B>B>dump()<B>B> 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 <B>B>dump()<B>B> 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 <B>B>dump()<B>B> will be displayed.
class If class is true, then <B>B>dump()<B>B> will display only class attributes of the invocant and their values, and all other types of attributes explicitly requested in the call to <B>B>dump()<B>B> (the all parameter is ignored). If the caller doesn’t have access to class methods, then <B>B>dump()<B>B> will <B>B>die()<B>B> 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 <B>B>dump()<B>B> of public attributes of a class will result in <B>B>dump()<B>B> <B>B>die()<B>B>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 <B>B>dump()<B>B> will display the list of friends of the invoking class or object.
depth By default, <B>B>dump()<B>B> 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 <B>B>dump()<B>B>, and defaults to 4 spaces.
backtrace If backtrace is true, the <B>B>dump()<B>B> will back-trace references if they are encountered multiple times in the generation of the <B>B>dump()<B>B> 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 <B>B>dump()<B>B> then this only has effect on the target object of the <B>B>dump()<B>B> call, and not any subsequent recursive calls to <B>B>dump()<B>B> used to display nested objects.

<B>hash(B> [ param => value ] <B>)B> Return a hash representing the values of the attributes of the class or object (depending on how <B>B>hash()<B>B> is called. <B>B>hash()<B>B> supports the same calling parameters as <B>B>dump()<B>B>, except for friends and indent). <B>B>hash()<B>B> 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, <B>B>hash()<B>B> will return a hash, otherwise a hash reference is returned.

<B>Note:B> As of v0.10, <B>B>hash()<B>B> supports the depth parameter, and will, by default, recurse to generate a hash of the entire object tree (if derived from <B>Class::DeclareB>). 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. <B>B>hash()<B>B> will descend ARRAY and HASH references if asked to recurse.

<B>arguments(B> args => default <B>)B> 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 <B>B>arguments()<B>B>? 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?

<B>B>arguments()<B>B> 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.

<B>B>arguments()<B>B> 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 <B>B>arguments()<B>B> is as follows (note, we assume here that the method is in a <B>Class::DeclareB>-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, <B>B>arguments()<B>B> 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 <B>B>arguments()<B>B> 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, <B>B>arguments()<B>B> returns the argument hash, while if called in a scalar context, <B>B>arguments()<B>B> will return a reference to the hash. <B>B>arguments()<B>B> may be called as either a class or instance method.

<B>REVISION(B><B>)B> Extract the revision number from CVS revision strings. <B>B>REVISION()<B>B> 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 <B>B>REVISION()<B>B> returns undef.



  package My::Class;

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

  ...

  1;


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



<B>VERSION(B> [ required ] <B>)B> Replacement for <B>B>UNIVERSAL::VERSION()<B>B>, that falls back to <B>B>REVISION()<B>B> to report the CVS revision number as the version number if the package variable $VERSION is not defined. If required is given, then <B>B>VERSION()<B>B> will die if the required version is not less than or equal to the current package version (or revision, if <B>B>VERSION()<B>B> falls back to <B>B>REVISION()<B>B>). <B>B>VERSION()<B>B> will die if required is not a valid version string.
<B>has(B> method <B>)B> If this class directly implements the given method(), then return a reference to this method. Otherwise, return false. This is similar to <B>UNIVERSAL::B><B>B>can()<B>B>, which will return a reference if this class either directly implements method(), or inherits it.
<B>strict(B><B>)B> If this class is operating with strict access checking (i.e. strict from <B>B>declare()<B>B> was not explicitly set to false in this class or one of its parent classes) then <B>B>strict()<B>B> will return true, otherwise return false.

CAVEAT

<B>Class::DeclareB> 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 <B>Class::DeclareB>’s behaviour, please let me know.

BUGS

The name. I don’t really like <B>Class::DeclareB> 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, <B>Class::DeclareB> 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-2010 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DECLARE (3) 2015-10-05

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.