Author image Dorian Taylor
and 1 contributors


Params::Registry - Housekeeping for sets of named parameters


Version 0.08


    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) };



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.


basically untouched


basically untouched


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.


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


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


When nothing else will do


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.


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)



Instantiate a new parameter registry.



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


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


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.


Return the global sequence of parameters for serialization.


Refresh the stateful components of the templates


Dorian Taylor, <dorian at>


Please report any bugs or feature requests to bug-params-registry at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc Params::Registry

You can also look for information at:



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 .

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.