.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Class::ParmList 3"
.TH Class::ParmList 3 "2008-01-01" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Class::ParmList \- Methods for processing named parameter lists
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Class::ParmList qw(simple_parms parse_parms);
.Ve
.PP
.Vb 4
\& $thingy->some_method({
\&      -bgcolor   => '#ff0000',
\&      -textcolor => '#000000'
\&      });
.Ve
.PP
.Vb 2
\& sub some_method {
\&     my ($self) = shift;
.Ve
.PP
.Vb 1
\&     my ($parm_ref) = @_;
.Ve
.PP
.Vb 9
\&     my $parms = Class::ParmList->new ({
\&            -parms    => $parm_ref,
\&            -legal    => [qw (-textcolor -border -cellpadding)],
\&            -required => [qw (-bgcolor)],
\&            -defaults => {
\&                           -bgcolor   => "#ffffff",
\&                           -textcolor => "#000000"
\&                         }
\&         });
.Ve
.PP
.Vb 4
\&     if (not defined $parms) {
\&        my $error_message = Class::ParmList->error;
\&        die ($error_message);
\&     }
.Ve
.PP
.Vb 1
\&     # Stuff...
.Ve
.PP
.Vb 1
\& }
.Ve
.PP
.Vb 3
\&  sub another_method {
\&    my $self = shift;
\&    my ($name,$rank,$serial_number) = simple_parms([qw(-name -rank -serial_number)], @_);
.Ve
.PP
.Vb 2
\&    #...
\&  }
.Ve
.PP
.Vb 14
\&  sub still_another {
\&     my $parms = parse_parms ({
\&            -parms    => \e@_,
\&            -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);
\&     }
.Ve
.PP
.Vb 2
\&     # ...
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a simple package for validating calling parameters to a subroutine or
method. It allows you to use \*(L"named parameters\*(R" 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.
.SH "CHANGES"
.IX Header "CHANGES"
.Vb 1
\& 1.00 1999.06.16 - Initial release
.Ve
.PP
.Vb 1
\& 1.01 1999.06.18 - Performance tweaks
.Ve
.PP
.Vb 3
\& 1.02 1999.06.21 - Fixing of failure to catch undeclared parm,
\&                   removal of 'use attrs qw(method)', and
\&                   extension of 'make test' support.
.Ve
.PP
.Vb 3
\& 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.
.Ve
.PP
.Vb 6
\& 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.
.Ve
.PP
.Vb 2
\& 1.05 2006.03.04 - Corrected mis-usage of Carp in error paths that
\&                   was causing less than useful error messages.
.Ve
.PP
.Vb 2
\&                   Added LICENSE and DISCLAIMER sections to
\&                   documentation.
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "new($parm_list_ref);" 4
.IX Item "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.
.Sp
Example:
.Sp
.Vb 9
\&     my $parms = Class::ParmList->new ({
\&            -parms    => $parm_ref,
\&            -legal    => [qw (-textcolor -border -cellpadding)],
\&            -required => [qw (-bgcolor)],
\&            -defaults => {
\&                           -bgcolor   => "#ffffff",
\&                           -textcolor => "#000000"
\&                         }
\&         });
.Ve
.Sp
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.
.Sp
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.
.Sp
To simplify calling routines, the '\-parms' parameters is allowed
to 'stack' anon list references: [['parm','value']]
.Sp
This gives a calling routine the ability to parse \f(CW@_\fR without
jumping through hoops to handle the cases of arrays vs hashes for
the passed parameters.
.Sp
Example:
.Sp
.Vb 6
\& sub example_sub {
\&   my $parms = Class::ParmList->new({ -parms => \e@_,
\&                                      -legal => [],
\&                                   -required => ['-file','-data'],
\&                                   -defaults => {},
\&                                  });
.Ve
.Sp
.Vb 2
\&   #...
\& }
.Ve
.Sp
This routine would accept *either*
.Sp
.Vb 1
\&   example_sub({ '-file' => 'test', '-data' => 'stuff' });
.Ve
.Sp
or
.Sp
.Vb 1
\&   example_sub( '-file' => 'test', '-data' => 'stuff' );
.Ve
.Sp
with no code changes.
.IP "parse_parms({ \-parms => \e@parms, \-legal => ['list','legal','parms'], \-required => ['list','required','parms'], \-defaults => { 'default' => 'parameter values', }, });" 4
.IX Item "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.
.Sp
Example:
.Sp
.Vb 5
\&   my $parms = parse_parms({ -parms => \e@_,
\&                             -legal => [],
\&                          -required => ['-file','-data'],
\&                          -defaults => {},
\&                         });
.Ve
.ie n .IP "get($parm_name1, $parm_name2,...);" 4
.el .IP "get($parm_name1, \f(CW$parm_name2\fR,...);" 4
.IX Item "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.
.Sp
Example:
  my ($help,$who) = \f(CW$parms\fR\->get('\-help','\-who');
.IP "exists($parm_name);" 4
.IX Item "exists($parm_name);"
Returns true if the parameter specifed by \f(CW$parm_name\fR (qv.
has been initialized), false if it does not exist.
.Sp
.Vb 3
\&  if ($parms->exists(-help) {
\&      # do stuff
\&  }
.Ve
.IP "list_parms;" 4
.IX Item "list_parms;"
Returns the list of parameter names. (Names are always
presented in lowercase).
.Sp
Example:
.Sp
.Vb 1
\&  my @parm_names = $parms->list_parms;
.Ve
.IP "all_parms;" 4
.IX Item "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.
.Sp
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.
.Sp
Example:
.Sp
.Vb 1
\&  my $parms = $parms->all_parms;
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "error;" 4
.IX Item "error;"
Returns the error message for the most recent invokation of
\&'new'.  (Static method \- does not require an object to function)
.Sp
Example:
.Sp
.Vb 2
\&     my $error_message = Class::ParmList->error;
\&     die ($error_message);
.Ve
.IP "simple_parms(['\-list','\-of','\-parameter_names'],@_);" 4
.IX Item "simple_parms(['-list','-of','-parameter_names'],@_);"
Parses the passed named parameter list (croaking/confessing if extra or
missing parameters are found).
.Sp
Examples:
.Sp
.Vb 1
\& use Class::ParmList qw(simple_parms);
.Ve
.Sp
.Vb 2
\& sub some_method {
\&    my $self = shift;
.Ve
.Sp
.Vb 3
\&    my ($name,$rank) = simple_parms([qw(-name -rank)],@_);
\&    # Now do stuff
\& }
.Ve
.Sp
.Vb 4
\& sub some_function {
\&    my $serial_number = simple_parms([qw(-serial_number)],@_);
\&    # Now do stuff
\& }
.Ve
.Sp
The passed parameter values for parsing this way may be either an anonymous hash of parameters
.Sp
Example:
   a_function({ \-parm1_name => \f(CW$parm1_value\fR, \-parm2_name => \f(CW$parm2_value\fR }) )
.Sp
or a straight list of parameters:
.Sp
Example:
  a_function(\-parm1_name => \f(CW$parm1_value\fR, \-parm2_name => \f(CW$parm2_value\fR) )
.Sp
Note that it *IS* legal for a parameter to be passed with an 'undef' value \- it
will not trigger an error.
.Sp
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).
.Sp
Its main virtues are that is is simple to use, has rugged error checking for
mis-usages and is reasonably fast.
.Sp
\&'simple_parms' can be exported by specifying it on the 'use' line.
.SH "VERSION"
.IX Header "VERSION"
1.05 2006.03.04
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright Benjamin Franz (<URL:http://www.nihongo.org/snowhare/>) and
FreeRun Technologies, Inc. (<URL:http://www.freeruntech.com/>). All Rights Reserved.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it
and/or modify it under the same terms and conditions as
Perl itself.
.PP
This means that you can, at your option, redistribute it and/or modify it under
either the terms the \s-1GNU\s0 Public License (\s-1GPL\s0) version 1 or later, or under the
Perl Artistic License.
.PP
See http://dev.perl.org/licenses/
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
\&\s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 ``\s-1AS\s0 \s-1IS\s0'' \s-1AND\s0 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1EXPRESS\s0
\&\s-1OR\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1WITHOUT\s0 \s-1LIMITATION\s0, \s-1THE\s0
\&\s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A
\&\s-1PARTICULAR\s0 \s-1PURPOSE\s0.
.PP
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.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0 I \s-1BE\s0 \s-1LIABLE\s0 \s-1TO\s0 \s-1ANY\s0 \s-1PARTY\s0 \s-1FOR\s0 \s-1DIRECT\s0, \s-1INDIRECT\s0,
\&\s-1SPECIAL\s0, \s-1INCIDENTAL\s0,  \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0
\&\s-1USE\s0 \s-1OF\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1AND\s0 \s-1ITS\s0 \s-1DOCUMENTATION\s0 (\s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0
\&\s-1LIMITED\s0 \s-1TO\s0, \s-1LOST\s0 \s-1PROFITS\s0) \s-1EVEN\s0 \s-1IF\s0 I \s-1HAVE\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0
\&\s-1POSSIBILITY\s0 \s-1OF\s0 \s-1SUCH\s0 \s-1DAMAGE\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Benjamin Franz, <snowhare@nihongo.org>
.SH "BUGS"
.IX Header "BUGS"
None known
.SH "TODO"
.IX Header "TODO"
Memoization of parameter validation for performance.