NAME

Class::NamedParms - A lightweight base class for checked get/set property accessors

SYNOPSIS

 package SomePackage;

 use Class::NamedParms;
 use vars qw (@ISA);
 @ISA=qw(Class::NamedParms);
 
 sub new {
    my $proto = shift;
    my $class = ref ($proto) || $proto;
 
    my $self = Class::NamedParms->new(-benefits,-costs);
    $self    = bless $self,$class;
 
    return $self;
 }


 $thingy = SomePackage->new;
 $thingy->set({ -benefits => 1, -costs => 0.5 });
 my ($costs,$benefits) = $thingy->get(-costs,-benefits);

DESCRIPTION

Provides key name checking for named accessor parameters. This allows the use of a generic 'get/set' type parameterized accessor while automatically catching accidental mis-spellings and usage of uninitialized parameters. This catches a large class of programming errors without requiring a new accessor for every object parameter.

It can also be used as a standalone generic 'container' object.

Example:

  my $plant = Class::NamedParms->new(qw(phylum family genera species));
  $plant->set({ species => 'Homo Sapiens Sapiens' });

CHANGES

 1.00 1999.06.16 - Initial release.

 1.01 1999.06.17 - Bug fix to 'clear' method. Added 'make test' support.

 1.02 1999.06.18 - Performance tweak to 'get' method.

 1.03 1999.06.21 - Minor docs tweaks. Removal of 'use attrs' for portability

 1.04 1999.10.08 - Bug fix to 'all_parms' method

 1.05 2005.09.19 - Added GPL_License.txt, Artistic_License.txt, LICENSE,
                   Changes, Build.PL. Added pod build tests.
                   Split documentation into .pod file. Extended build
                   tests to 100% code coverage. Refactored code to make
                   it more inheritance friendly. Updated documentation.

 1.06 2005.09.20 - Fixed bad pod coverage build test.

METHODS

new;

Creates a new instance of a NamedParms object.

You can optionally 'declare' the legal parameter keys at the same time.

Example:

     my $obj = Class::NamedParms->new('benefits', 'costs', 'other');

list_declared_parms;

Returns a list of all parm names that have been declared for this NamedParms object. List is unsorted.

Example:

 my @declared_parms = $obj->list_declared_parms;

list_initialized_parms;

Lists all parms that have had values initialized for this NamedParms object Returns a list of the parameter names. List is unsorted.

 my @parms = $obj->list_initialized_parms;

declare($parmname,[$parmname1,...]);

Declares one or more parameters for use with the NamedParms object.

Example:

   $self->declare(-moved_in,-car_key,-house_key,-relationship);

This *does not* initialize the parameters - only declares them to be legal for use.

undeclare($parmname,$parmname1,...);

'undeclares' one or more parameters for use with the NamedParms object. This also deletes any values assigned to those parameters.

Example:

   $self->undeclare(-house_key,-car_key,-relationship);

exists($parmname);

Returns true if the specified parmname has been initialized via 'set'.

Example:

 if ($obj->exists('height')) {
    #....
 }

set($parm_ref);

Sets one or more named parameter values.

Example:

  $self->set({ -thingy => 'test', -other_thingy => 'more stuff' });

Will 'confess' if an attempt is made to set an undeclared parameter key.

clear(@parm_names);

Clears (deletes) one or more named parameter values.

Example:

     $self->clear(-this,-that,-the_other_thing);

Note: A 'cleared' value returns undef from 'get'.

get(@parm_names);

Gets one or more named parameter values.

Screams and dies (well, 'confess'es) if you attempt to read a value that has not been initialized. Results are returned in the same order as the parameter names passed.

In a scalar context, the _last_ result is what is returned.

Example:

   my ($age,$gender) = $self->get(-age,-gender);

Will 'confess' if an attempt is made to access an undeclared key or if the requested value has not been initialized.

all_parms;

Returns an anonymous hash containing all the currently set keys and values. This hash is suitable for usage with Class::NamedParms or Class::ParmList for setting keys/values with their 'set' methods.

It works by making a shallow copy of the data. This means that it copies the values. In the case of simple numbers and strings, this produces a new copy, in the case of references to hashes and arrays or objects, it returns a reference to the original object such that alterations of the returned object are reflected in the live copy.

Example:

  my $parms = $parms->all_parms;

AUTHOR

Benjamin Franz <snowhare@nihongo.org>

VERSION

1.06 2005.09.20

TODO

Nothing.

COPYRIGHT

Copyright 1999-2005, Benjamin Franz (<URL:http://www.nihongo.org/snowhare/>) and FreeRun Technologies, Inc. (<URL:http://www.freeruntech.com/>). All Rights Reserved. This software may be copied or redistributed under the same terms as Perl itelf.

LICENSE

This module is licensed under the same terms and conditions as Perl itself.

This means that you can, at your option, redistribute is and/or modify it under either the terms the GNU Public License (GPL) version 1 or later, or under the Perl Artistic License.

See http://dev.perl.org/licenses/

cpanm Class::NamedParms

perl -MCPAN -e shell
install Class::NamedParms