NAME

Params::Registry::Instance - An instance of registered parameters

VERSION

Version 0.04_03

SYNOPSIS

    use Params::Registry;
    use URI;
    use URI::QueryParam;

    my $registry = Params::Registry->new(%enormous_arg_list);

    my $uri = URI->new($str);

    # The instance is created through Params::Registry, which will
    # raise different exceptions for different types of conflict in
    # the parameters.
    my $instance = eval { $registry->process($uri->query_form_hash) };

    # Contents have already been coerced
    my $thingy = $instance->get($key);

    # This will perform type validation and coercion, so if you aren't
    # certain the input is clean, you'll want to wrap this call in an
    # eval.
    eval { $instance->set($key, $val) };

    # Take a subset of parameters peculiar to a certain application.
    my $group = $instance->group($name);

    # This string is guaranteed to be consistent for a given set of
    # parameters and values.
    $uri->query($instance->as_string);

METHODS

get $KEY

Retrieve an element of the parameter instance.

set \%PARAMS | $KEY, $VAL [, $KEY2, \@VALS2 ...]

Modifies one or more of the parameters in the instance. Attempts to coerce the input according to the template. Accepts, as values, either a literal, an ARRAY reference of literals, or the target datatype. If a <Params::Registry::Template/composite> is specified for a given key, ARRAY references will be coerced into the appropriate composite datatype.

Syntax, semantics, cardinality, dependencies and conflicts are all observed, but cascading is not. This method will throw an exception if the input can't be reconciled with the Params::Registry that generated the instance.

group $KEY

Selects a subset of the instance according to the groups laid out in the Params::Registry specification, clones them, and returns them in a HASH reference, suitable for passing into another method.

template $KEY

Retrieves the template for $KEY.

clone $KEY => $VAL [...] | \%PAIRS

Produces a clone of the instance object, with the supplied parameters overwritten. Internally, this uses "set", so the input must already be clean, or wrapped in an eval.

as_where_clause

Generates a data structure suitable to pass into SQL::Abstract (e.g., via DBIx::Class).

as_string

Generates the canonical URI query string according to the template.

make_uri $URI

Accepts a URI object and returns a clone of that object with its query string overwritten with the contents of the instance. This is a convenience method for idioms like:

    my $new_uri = $instance->clone(foo => undef)->make_uri($old_uri);

As expected, this will produce a new instance with the foo parameter removed, which is then used to generate a URI, suitable for a link.

AUTHOR

Dorian Taylor, <dorian at cpan.org>

SEE ALSO

• Params::Registry

• Params::Registry::Template

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.

cpanm Params::Registry

perl -MCPAN -e shell
install Params::Registry