NAME
Class::ParmList - Methods for processing named parameter lists
SYNOPSIS
use Class::ParmList qw(simple_parms parse_parms);
$thingy->some_method({
bgcolor => '#ff0000',
textcolor => '#000000'
});
sub some_method {
my ($self) = shift;
my ($parm_ref) = @_;
my $parms = Class::ParmList->new ({
-parms => $parm_ref,
-legal => [qw (textcolor border cellpadding)],
-required => [qw (bgcolor)],
-defaults => {
bgcolor => "#ffffff",
textcolor => "#000000"
}
});
if (not defined $parms) {
my $error_message = Class::ParmList->error;
die ($error_message);
}
# Stuff...
}
sub another_method {
my $self = shift;
my ($name,$rank,$serial_number) = simple_parms([qw(name rank serial_number)], @_);
#...
}
sub still_another {
my $parms = parse_parms ({
-parms => \@_,
-legal => [qw (textcolor border cellpadding)],
-required => [qw (bgcolor)],
-defaults => {
bgcolor => "#ffffff",
textcolor => "#000000"
}
});
if (not defined $parms) {
my $error_message = Class::ParmList->error;
die ($error_message);
}
# ...
}DESCRIPTION
This is a simple package for validating calling parameters to a subroutine or method. It allows you to use "named parameters" while providing checking for number and naming of parameters for verifying inputs are as expected and meet any minimum requirements. It also allows the setting of default values for the named parameters if omitted.
METHODS
- new($parm_list_ref);
-
Returns a reference to an object that can be used to return values. If an improper specification is passed, returns 'undef'. Otherwise returns the reference.
Example:
my $parms = Class::ParmList->new ({ -parms => $parm_ref, -legal => [qw (-textcolor -border -cellpadding)], -required => [qw (-bgcolor)], -defaults => { -bgcolor => "#ffffff", -textcolor => "#000000" } });All four parameters (-parms, -legal, -required, and -defaults) are optional. It is liberal in that anything defined for a -default or -required is automatically added to the '-legal' list.
If the '-legal' parameter is not _explicitly_ called out, no checking against the legal list is done. If it _is_ explicitly called out, then all -parms are checked against it and it will fail with an error if a -parms parameter is present but not defined in the -legal explict or implict definitions.
To simplify calling routines, the '-parms' parameters is allowed to 'stack' anon list references: [['parm','value']]
This gives a calling routine the ability to parse @_ without jumping through hoops to handle the cases of arrays vs hashes for the passed parameters.
Example:
sub example_sub { my $parms = Class::ParmList->new({ -parms => \@_, -legal => [], -required => ['-file','-data'], -defaults => {}, }); #... }This routine would accept *either*
example_sub({ '-file' => 'test', '-data' => 'stuff' });or
example_sub( '-file' => 'test', '-data' => 'stuff' );with no code changes.
- parse_parms({ -parms => \@parms, -legal => ['list','legal','parms'], -required => ['list','required','parms'], -defaults => { 'default' => 'parameter values', }, });
-
This is a functional equivalent to the 'new' method. Calling parameters are identical, but it is called as a class function that may be exported.
Example:
my $parms = parse_parms({ -parms => \@_, -legal => [], -required => ['-file','-data'], -defaults => {}, });
- get($parm_name1, $parm_name2,...);
-
Returns the parameter value(s) specified in the call line. If a parameter is not defined, it returns undef. If a set of '-legal' parameters were declared, it croaks if a parameter not in the '-legal' set is asked for.
Example: my ($help,$who) = $parms->get('-help','-who');
- exists($parm_name);
-
Returns true if the parameter specifed by $parm_name (qv. has been initialized), false if it does not exist.
if ($parms->exists(-help) { # do stuff }
- list_parms;
-
Returns the list of parameter names. (Names are always presented in lowercase).
Example:
my @parm_names = $parms->list_parms;
- 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. 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 references to the original objects.
Example:
my $parms = $parms->all_parms;
FUNCTIONS
- error;
-
Returns the error message for the most recent invokation of 'new'. (Static method - does not require an object to function)
Example:
my $error_message = Class::ParmList->error; die ($error_message);
- simple_parms(['-list','-of','-parameter_names'],@_);
-
Parses the passed named parameter list (croaking/confessing if extra or missing parameters are found).
Examples:
use Class::ParmList qw(simple_parms); sub some_method { my $self = shift; my ($name,$rank) = simple_parms([qw(-name -rank)],@_); # Now do stuff } sub some_function { my $serial_number = simple_parms([qw(-serial_number)],@_); # Now do stuff }The passed parameter values for parsing this way may be either an anonymous hash of parameters
Example: a_function({ -parm1_name => $parm1_value, -parm2_name => $parm2_value }) )
or a straight list of parameters:
Example: a_function(-parm1_name => $parm1_value, -parm2_name => $parm2_value) )
Note that it *IS* legal for a parameter to be passed with an 'undef' value - it will not trigger an error.
If you need optional parameters, this function is not well suited. You should use the object methods above instead for that case - they are much more flexible (but quite a bit slower and slightly more complex to use).
Its main virtues are that is is simple to use, has rugged error checking for mis-usages and is reasonably fast.
'simple_parms' can be exported by specifying it on the 'use' line.
VERSION
1.06 2020.10.11
CHANGES
1.00 1999.06.15 - Initial release
1.01 1999.06.18 - Performance tweaks. Addition of 'make test' support
1.02 1999.06.21 - Fixed '-legal' (broken by performance tweaks in 1.01),
removed use of 'use attrs' for portability, extended
'make test' tests.
1.03 2000.12.06 - Added exportable class functions 'simple_parms'
and 'parse_parms' and allowed 'stacking' references
for parms to the object to improve calling usage.
1.04 2005.09.18 - Added META.yml, Build.PL, Artistic_License.txt
GPL_License.txt, LICENSE to distribution. Renamed
CHANGES to Changes. Extended build tests to 100%
coverage. Minor refactoring of module for speed.
Seperated documentation into .pod file.
Added POD/POD Coverage tests.
1.05 2006.03.04 - Corrected mis-usage of Carp in error paths that
was causing less than useful error messages.
Added LICENSE and DISCLAIMER sections to
documentation.
1.06 2020.10.11 - Relicensed under the MIT License. Cleanup of test reporting.
Updating of build configurations. Addition of GitHub repo
information to meta data. Updating of maintainer information.
Small changes to examples in POD documentation.COPYRIGHT
Copyright Jerilyn Franz and FreeRun Technologies, Inc. All Rights Reserved.
LICENSE
MIT License
Copyright (c) 2020 Jerilyn Franz and 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.
DISCLAIMER
THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Use of this software in any way or in any form, source or binary, is not allowed in any country which prohibits disclaimers of any implied warranties of merchantability or fitness for a particular purpose or any disclaimers of a similar nature.
IN NO EVENT SHALL I BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION (INCLUDING, BUT NOT LIMITED TO, LOST PROFITS) EVEN IF I HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
AUTHOR
Jerilyn Franz, <cpan@jerilyn.info>
BUGS
None known
TODO
Memoization of parameter validation for performance.