NAME

Class::ParamParser - Provides complex parameter list parsing

DEPENDENCIES

Perl Version

        5.004

Standard Modules

        I<none>

Nonstandard Modules

        I<none>

SYNOPSIS

        use Class::ParamParser;
        @ISA = qw( Class::ParamParser );

PARSING PARAMS INTO NAMED HASH

        sub textfield {
                my $self = shift( @_ );
                my $rh_params = $self->params_to_hash( \@_, 0, 
                        [ 'name', 'value', 'size', 'maxlength' ], 
                        { 'default' => 'value' } );
                $rh_params->{'type'} = 'text';
                return( $self->make_html_tag( 'input', $rh_params ) );
        }

        sub textarea {
                my $self = shift( @_ );
                my $rh_params = $self->params_to_hash( \@_, 0, 
                        [ 'name', 'text', 'rows', 'cols' ], { 'default' => 'text', 
                        'value' => 'text', 'columns' => 'cols' }, 'text', 1 );
                my $ra_text = delete( $rh_params->{'text'} );
                return( $self->make_html_tag( 'textarea', $rh_params, $ra_text ) );
        }

        sub AUTOLOAD {
                my $self = shift( @_ );
                my $rh_params = $self->params_to_hash( \@_, 0, 'text', {}, 'text' );
                my $ra_text = delete( $rh_params->{'text'} );
                $AUTOLOAD =~ m/([^:]*)$/;
                my $tag_name = $1;
                return( $self->make_html_tag( $tag_name, $rh_params, $ra_text ) );
        }

PARSING PARAMS INTO POSITIONAL ARRAY

        sub property {
                my $self = shift( @_ );
                my ($key,$new_value) = $self->params_to_array(\@_,1,['key','value']);
                if( defined( $new_value ) ) {
                        $self->{$key} = $new_value;
                }
                return( $self->{$key} );
        }

        sub make_html_tag {
                my $self = shift( @_ );
                my ($tag_name, $rh_params, $ra_text) = 
                        $self->params_to_array( \@_, 1, 
                        [ 'tag', 'params', 'text' ],
                        { 'name' => 'tag', 'param' => 'params' } );
                ref($rh_params) eq 'HASH' or $rh_params = {};
                ref($ra_text) eq 'ARRAY' or $ra_text = [$ra_text];
                return( join( '', 
                        "<$tag_name", 
                        (map { " $_=\"$rh_params->{$_}\"" } keys %{$rh_params}),
                        ">",
                        @{$ra_text},
                        "</$tagname>",
                ) );
        }

DESCRIPTION

This Perl 5 object class implements two methods which inherited classes can use to tidy up parameter lists for their own methods and functions. The two methods differ in that one returns a HASH ref containing named parameters and the other returns an ARRAY ref containing positional parameters.

Both methods can process the same kind of input parameter formats:

• empty list
• value
• value1, value2, ...
• name1 => value1, name2 => value2, ...
• -name1 => value1, -NAME2 => value2, ...
• { -Name1 => value1, NAME2 => value2, ... }
• { name1 => value1, -Name2 => value2, ... }, valueR
• { name1 => value1, -Name2 => value2, ... }, valueR1, valueR2, ...

Those examples included single or multiple positional parameters, single or multiple named parameters, and a HASH ref containing named parameters (with optional "remaining" values afterwards). That list of input variations is not exhaustive. Named parameters can either be prefixed with "-" or left natural.

We assume that the parameters are named when either they come as a HASH ref or the first parameter begins with a "-". We assume that they are positional if there is an odd number of them. Otherwise we are in doubt and rely on an optional argument to the tidying method that tells us which to guess by default.

We assume that any "value" may be an array ref (aka "multiple" values under the same name) and hence we don't do anything special with them, passing them as is. The only exception to this is with "remaining" values; if there is more than one of them and the first isn't an array ref, then they are all put in an array ref.

If the source and destination are both positional, then they are identical.

SYNTAX

This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $self->method(). Note that this class doesn't have any properties of its own.

FUNCTIONS AND METHODS

params_to_hash( SOURCE, DEF, NAMES[, RENAME[, REM[, LC]]] )

See below for argument descriptions.

params_to_array( SOURCE, DEF, NAMES[, RENAME[, REM[, LC]]] )

See below for argument descriptions.

ARGUMENTS

The arguments for the above methods are the same, so they are discussed together here:

1. The first argument, SOURCE, is an ARRAY ref containing the original parameters that were passed to the method which calls this one. It is safe to pass "\@_" because we don't modify the argument at all. If SOURCE isn't a valid ARRAY ref then its default value is [].
2. The second argument, DEF, is a boolean/scalar that tells us whether, when in doubt over whether SOURCE is in positional or named format, what to guess by default. A value of 0, the default, means we guess named, and a value of 1 means we assume positional.
3. The third argument, NAMES, is an ARRAY ref (or SCALAR) that provides the names to use when SOURCE and our return value are not in the same format (named or positional). This is because positional parameters don't know what their names are and named parameters (hashes) don't know what order they belong in; the NAMES array provides the missing information to both. The first name in NAMES matches the first value in a positional SOURCE, and so-on. Likewise, the order of argument names in NAMES determines the sequence for positional output when the SOURCE is named.
4. The optional fourth argument, RENAME, is a HASH ref that allows us to interpret a variety of names from a SOURCE in named format as being aliases for one enother. The keys in the hash are names to look for and the values are what to rename them to. Keys are matched regardless of whether the SOURCE names have "-" in front of them or not. If several SOURCE names are renamed to the same hash value, then all but one are lost; the SOURCE should never contain more than one alias for the same parameter anyway. One way to explicitely delete a parameter is to rename it with "", as parameters with that name are discarded.
5. The optional fifth argument, REM, is only used in circumstances where the first element of SOURCE is a HASH ref containing the actual named parameters that SOURCE would otherwise be. If SOURCE has extra, "remaining" elements following the HASH ref, then REM says what its name is. Remaining parameters with the same name as normal parameters (post renaming and "-" substitution) take precedence. The default value for REM is "", and it is discarded unless renamed. Note that the value returned with REM can be either a single scalar value, when the "remaining" is a single scalar value, or an array ref, when there are more than one "remaining" or the first "remaining" is an array ref (passed as is).
6. The optional sixth argument, LC, is a boolean/scalar that forces named parameters in SOURCE to be lowercased; by default this is false, meaning that the original case is preserved. Use this when you want your named parameters to have case-insensitive names, for accurate matching by your own code or RENAME. If you use this, you must provide lowercased keys and values in your RENAME hash, as well as lowercased NAMES and REM; none of these are lowercased for you.

AUTHOR

Copyright (c) 1999-2003, Darren R. Duncan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. However, I do request that this copyright information and credits remain attached to the file. If you modify this module and redistribute a changed version then please attach a note listing the modifications. This module is available "as-is" and the author can not be held accountable for any problems resulting from its use.

I am always interested in knowing how my work helps others, so if you put this module to use in any of your own products or services then I would appreciate (but not require) it if you send me the website url for said product or service, so I know who you are. Also, if you make non-proprietary changes to the module because it doesn't work the way you need, and you are willing to make these freely available, then please send me a copy so that I can roll desirable changes into the main release.

Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.

CREDITS

Thanks to Laurie Shammel <lshammel@imt.net> for alerting me to some warnings that occur when converting a positional SOURCE to named where SOURCE has more array elements than NAMES. While the correct result was returned all along, warnings can be annoying in this context.

SEE ALSO

perl(1), HTML::FormTemplate, Class::ParmList, Class::NamedParms, Getargs::Long, Params::Validate, CGI.