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, "" BUGS Please report any bugs or feature requests to "bug-params-registry at rt.cpan.org", 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. 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) * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN 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 . 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.