The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Params-Registry-0.08
River stage zero No dependents
++
/ Params::Registry

NAME

Params::Registry - Housekeeping for sets of named parameters

VERSION

Version 0.08

SYNOPSIS

    use Params::Registry;

    my $registry = Params::Registry->new(
        # express the global parameter sequence with an arrayref
        params => [
            {
                # see Params::Registry::Template for the full list of
                # attributes
                name => 'foo',
            },
        ],
        # specify groups containing potentially-overlapping subsets of
        # parameters for different aspects of your system
        groups => {
            stuff => [qw(foo)],
        },
        # override the name of the special 'complement' parameter
        complement => 'negate',
    );

    my $instance = eval { $registry->process(\%params) };

    $uri->query($instance->as_string);

DESCRIPTION

The purpose of this module is to handle a great deal of the housekeeping around sets of named parameters and their values, especially as they pertain to web development. Modules like URI::QueryParam and Catalyst will take a URI query string and turn it into a HASH reference containing either scalars or ARRAY references of values, but further processing is almost always needed to validate the parameters, normalize them, turn them into useful compound objects, and last but not least, serialize them back into a canonical string representation. It is likewise important to be able to encapsulate error reporting around malformed or conflicting input, at both the syntactical and semantic levels.

While this module was designed with the web in mind, it can be used wherever a global registry of named parameters is deemed useful.

Scalar

basically untouched

List

basically untouched

Tuple

A tuple can be understood as a list of definite length, for which each position has its own meaning. The contents of a tuple can likewise be heterogeneous.

Set

A standard mathematical set has no duplicate elements and no concept of sequence.

Range

A range can be understood as a span of numbers or number-like objects, such as DateTime objects.

Object

When nothing else will do

Cascading

There are instances, for example in the case of supporting a legacy HTML form, when it is useful to combine input parameters. Take for instance the practice of using drop-down boxes for the year, month and day of a date in lieu of support for the HTML5 datetime form field, or access to custom form controls. One would specify year, month and day parameters, as well as a date parameter which consumes the former three, using a subroutine reference to do it. Consumed parameters are deleted from the set.

Complement

A special parameter, complement, is defined to signal parameters in the set itself which should be treated as complements to what have been expressed in the input. This module makes no prescriptions about how the complement is to be interpreted, with the exception of parameters whose values are bounded sets or ranges: if a shorter query string can be achieved by negating the set and removing (or adding) the parameter's name to the complement, that is what this module will do.

    # universe of foo = (a .. z)
    foo=a&foo=b&foo=c&complement=foo -> (a .. z) - (a b c)

METHODS

new

Instantiate a new parameter registry.

Arguments

params

An ARRAY reference of HASH references, containing the specs to be passed into Params::Registry::Template objects.

groups

A HASH reference such that the keys are names of groups, and the values are ARRAY references of parameters to include in each group.

complement

This is the name of the special parameter used to indicate which other parameters should have a "complement" in Params::Registry::Template operation run over them. The default name, naturally, is complement. This parameter will always be added to the query string last.

process $STR | $URI | \%PARAMS

Turn a URI, query string or HASH reference (such as those found in Catalyst or URI::QueryParam) into a Params::Registry::Instance. May croak.

template $KEY

Return a particular template from the registry.

sequence

Return the global sequence of parameters for serialization.

refresh

Refresh the stateful components of the templates

AUTHOR

Dorian Taylor, <dorian at cpan.org>

BUGS

Please report any bugs or feature requests to bug-params-registry at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Registry. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Params::Registry

You can also look for information at:

SEE ALSO

LICENSE AND COPYRIGHT

Copyright 2013 Dorian Taylor.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 .

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.