NAME
    Params::Registry - Housekeeping for sets of named parameters

VERSION
    Version 0.09_04

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:

    *   RT: CPAN's request tracker (report bugs here)

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Params-Registry>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/Params-Registry>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/Params-Registry>

    *   Search CPAN

        <http://search.cpan.org/dist/Params-Registry/>

SEE ALSO
    *   Params::Registry::Instance

    *   Params::Registry::Template

    *   Params::Validate

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.

