NAME

Puma::Core - an abstract base class for all Puma classes

SYNOPSIS

 use ibase Puma::Core;

 sub construct {
    my ($self, %args) = @_;
    $self->stripArgs(\%args, qw( NamedArg1 NamedArg2 ... ));
    return $self->SUPER::construct(%args);
 }

DESCRIPTION

The Puma::Core package provides a unified construction mechanism with full inheritance support for all subclasses.

Subclasses should not define a new() constructor but should instead rely on the construct() mechanism as defined below.

METHODS

`new()` and `construct()`

Any subclasses of Puma::Core should not implement new() as a constructor. The construct() method has been specifically created as a replacement for new() and should be implemented as follows:

   sub construct {
      my $self = shift;

      my %arg = $self->SUPER::construct(@_);

      # ... insert your code here ...

      return %arg;
   }

%arg represents a hash of named parameters that were passed in as the arguments for the new() constructor. Puma::Core presumes that all parameters passed into the constructor are named (i.e. not positional).

The example above uses a methodology that allows superconstructors to extract (and remove) their parameters from the parameter list before the local construction process begins. If you desire to process the parameter list before the superconstructor gets its grubby hands on it, see the example in the synopsis above.

Note that it is possible to re-implement the new() constructor in a subclass if absolutely necessary, but care should be taken to ensure that the inheritance cycle is not broken. It is useful to refer to the original new() method in Puma/Core.pm when doing this.

stripArgs(\%args, @arglist)

This method extracts from \%args the keys listed in @arglist and inserts them into the object. It is intended to be used for extracting key-value pairs from a named parameter list during the cascading constructors established by this class.

Although the method was designed to be used during the object construction process, it can be used to extract values from any named parameter list into the object anywhere.

Parameters

\%args: An hashref of named parameters
@arglist: A list of keys to extract from \%args

Return Value

\%args: The trimmed hashref of arguments catching this value is usually unnecessary because it returns the same hash reference as was originally passed in.

Example

This method is usually implemented within a constructor as follows

   sub construct {
      my ($self, %args) = @_;

      $self->stripArgs(
         \%args,
         qw( Rules Text )
      );

      return $self->SUPER::construct(%args);
   }

The method performs the following operation:

   $self->{Rules} = delete $args{Rules} if exists $args{LabelRules};
   $self->{Text}  = delete $args{Text}  if exists $args{Text};

Another cool trick is to coerce the argument list into a case insensitive hash to make case insensitive parameters:

   use Puma::Util::NCHash qw( nchash );
   my ($self, $args) = (shift, nchash(@_));
   $self->stripArgs($args, qw( Rules Text ));

COPYRIGHT

Distributed under The Artistic License. For the text of this license, see http://puma.site42.com/license.psp or read the file LICENSE in the root of the distribution.