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 ofHASH
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 areARRAY
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)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
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.