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:

   *   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.