Class::ParmList - A collection of routines for processing named parameter lists for method calls.
$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...
}
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.
1.00 1999.06.16 - Initial release
1.01 1999.06.18 - Performance tweaks
1.02 1999.06.21 - Fixing of failure to catch undeclared parm,
removal of 'use attrs qw(method)', and
extension of 'make test' support.
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.
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);
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
}
Returns the list of parameter names. (Names are always presented in lowercase).
Example:
my (@parm_names) = $parms->list_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;
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);
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.
Benjamin Franz
Everything.