NAME

Class::NamedParms - A lightweight named parameter handling system.

SYNOPSIS

 package SomePackage;
 use Class::NamedParms;
 use vars qw (@ISA);
 @ISA=qw(Class::NamedParms);

 sub new {	

	my ($proto) = shift;
    my ($class) = ref ($proto) || $proto;
	
    $self = Class::NamedParms->new(-benefits,-costs);
	$self = bless $self,$class;

	$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.

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 

Initialization

new;

Creates a new instance of a NamedParms object.

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

Example:

my $self = Class::NamedParms(-benefits,-costs,-other);

list_declared_parms;

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

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.

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'.

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 scalar 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 the reference to the original object such that alterations of the returned object are reflected in the live copy.

Example:

my $parms = $parms->all_parms;

COPYRIGHT

Copyright 1999, 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.

AUTHOR

Benjamin Franz

VERSION

1.04

TODO

Debugging.