/ 
Class-NamedParms-1.08
River stage one • 1 direct dependent • 2 total dependents
/ Class::NamedParms

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(qw(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.

1.07 2020.10.10 - Relicensed under MIT License. Maintainer info updated.
                  Build tooling updated. Documentation updates

1.08 2020.10.10 - Added LICENSE file that was inadvertently omitted in 1.07

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(qw(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(qw(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(qw(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(qw(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

Jerilyn Franz <cpan@jerilyn.info>

VERSION

1.07 2020.10.10

TODO

Nothing.

COPYRIGHT

Copyright 1999-2020, Jerilyn Franz and FreeRun Technologies, Inc. All Rights Reserved.

LICENSE

MIT License

Copyright (c) 2020 Jerilyn Franz, Freerun Technologies Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.