/ 
Params-Registry-0.01
River stage zero No dependents
/ Params::Registry::Template

NAME

Params::Registry::Template - Template class for an individual parameter

VERSION

Version 0.01

SYNOPSIS

my $registry = Params::Registry->new(
    params => [
        # These constructs are passed into
        # the parameter template module.
        {
            # The name is consumed before
            # the object is constructed.
            name       => 'foo',

            # the type of individual values
            type       => 'Num',

            # the composite type with coercion
            composite  => 'NumberRange',

            # format string or sub for individual values
            format     => '%0.2f',

            # do not delete empty values
            empty      => 1,

            # For sets and ranges:
            # fetch range extrema or universal set
            universe   => \&_extrema_from_db,

            # supply an operation that complements the given
            # set/range against the extrema/universe
            complement => \&_range_complement,

            # supply a serialization function
            unwind     => \&_range_to_arrayref,
        },
        {
            name => 'bar',
            # Lengthy definitions can be reused.
            use  => 'foo',
        },
    ],
);

METHODS

new

This constructor is invoked by a factory method in Params::Registry. All arguments are optional unless specified otherwise.

registry

This back-reference to the registry is the only required argument. Since the template objects are constructed from a factory inside Params::Registry, it will be supplied automatically.

type

The Moose type of the individual values of the parameter. The default is Str.

composite

Specifies a composite type to envelop one or more distinct parameter values. If a composite type is specified, even single-valued parameters will be coerced into that composite type as if it was an ArrayRef. As such, composite types used in this field should be specified with coercions that expect ArrayRef, like so:

coerce FooBar => from ArrayRef => via { Foo::Bar->new(@{$_[0]}) };

# ...
{
    name      => 'foo',
    type      => 'Str',
    composite => 'FooBar',
    # ...
},
# ...
format

Either a format string or a subroutine reference depicting how scalar values ought to be serialized. The default value is %s.

depends

An ARRAY reference containing a list of parameters which must accompany this one.

conflicts

An ARRAY reference containing a list of parameters which must not be seen with this one.

consumes

For cascading parameters, an ARRAY reference containing a list of subsidiary parameters which are consumed to create it. All consumed parameters are automatically assumed to be in conflict, i.e., it makes no sense to have both a subsidiary parameter and one that consumes it in the input at the same time.

consumer

For cascading parameters, a CODE reference to operate on the consumed parameters in order to produce the desired atomic value. To produce a composite parameter value from multiple existing values, define a coercion from ArrayRef to the type supplied to the "composite" property.

The default consumer function, therefore, simply returns an ARRAY reference that collates the values from the parameters defined in the "consumes" property.

Once again, this functionality exists primarily for the purpose of interfacing with HTML forms that lack the latest features. Consider the following example:

# ...
{
    name => 'year',
    type => 'Int',
    max  => 1,
},
{
    name => 'month',
    type => 'Int',
    max  => 1,
},
{
    name => 'day',
    type => 'Int',
    max  => 1,
},
{
    name => 'date',

    # this would be defined elsewhere with coercion from a
    # string that matches 'YYYY-MM-DD', for direct input.
    type => 'MyDateTimeType',

    # we don't want multiple values for this parameter.
    max  => 1,

    # in lieu of being explicitly defined in the input, this
    # parameter will be constructed from the following:
    consumes => [qw(year month day)],

    # and this is how it will happen:
    consumer => sub {
        DateTime->new(
            year  => $_[0],
            month => $_[1],
            day   => $_[2],
        );
    },
},
# ...

Here, we may have a form which contains a date field for the newest browsers that support the new form control, or otherwise generated via JavaScript. As a fallback mechanism (e.g. for an older browser, robot, or paranoid person), form fields for the year, month, and day can also be specified in the markup, and used to generate date.

min

The minimum number of values required for the given parameter. Set to 1 or higher to signal that the parameter is required. The default value is 0, meaning that the parameter is optional.

max

The maximum number of values acknowledged for the given parameter. Subsequent values will either be truncated to the right or shifted to the left, depending on the value of the "shift" property. Setting this property to 1 will force parameters to be scalar. The default is undef, which accepts an unbounded list of values.

shift

This boolean value determines the behaviour of input parameter values that exceed the parameter's maximum cardinality. The default behaviour is to truncate the list of values at the upper bound. Setting this bit instead causes the values for the ascribed parameter to be shifted off the left side of the list. This enables, for instance, dumb web applications to simply tack additional parameters onto the end of a query string without having to parse it.

empty

If a parameter value is undef or the empty string, the default behaviour is to act like it didn't exist in the input, thus pruning it from the resulting data and from the serialization. In the event that an empty value for a given parameter is meaningful, such as in expressing a range unbounded on one side, this bit can be set, and the "default" can be set to either undef or the empty string (or anything else).

default

This default value is passed through to the application only if the parameter in question is either missing or empty (if empty is set). Likewise if the final translation of the input value matches the default, it will not show up in the canonical serialization. Like Moose, is expected to be a CODE reference.

default => sub { 1 },
universe

For "Set" and "Range" parameters, this is a CODE reference which produces a universal set against which the input can be negated. In parameter serialization, there are often cases wherein a shorter string can be achieved by presenting the negated set and adding the parameter's name to the special parameter "complement" in Params::Registry. The subroutine can, for instance, query a database for the full set in question and return a type compatible with the parameter instance.

If you specify a universe, you must also specify a "complement".

complement

For "Set" and "Range" parameters, this CODE reference will need to do the right thing to produce the inverse set.

{
    # ...
    complement => sub {
        # assuming Set::Scalar
        my ($me, $universe) = @_;
        $me->complement($universe); },
    # ...
}

This field expects to be used in conjunction with "universe".

unwind

For composite object parameters, specify a CODE reference to a subroutine which will turn the object into either a scalar, an ARRAY reference of scalars, or an unblessed HASH reference containing valid parameter keys to either scalars or ARRAY references of scalars. In the case the subroutine returns a HASH reference, the registry will replace the parameter in context with the parameters supplied, effectively performing the inverse of a composite type coercion function. To encourage code reuse, this function is applied before "reverse" despite the ability to reverse the resulting list in the function.

The first argument to the subroutine is the template object itself, and the second is the value to be unwound. If you don't need any state data from the template, consider the following idiom:

{
    # ...
    # assuming Set::Scalar
    unwind => sub { [sort $_[1]->elements] },
    # ...
}

An optional second return value can be used to indicate that the special complement parameter should be set for this parameter. This is applicable, for instance, to the complement of a range, which would otherwise be impossible to serialize into a string.

reverse

For "Range" parameters, this bit indicates whether the input values should be interpreted and/or serialized in reverse order. This also governs the serialization of "Set" parameters.

process

Validate a set of individual parameter values and (optionally) construct a composite value.

unprocess

Apply "unwind" to get an arrayref, then "format" to get strings. In list context it will also return the flag from "unwind" indicating that the complement parameter should be set.

refresh

Refreshes stateful information like the universal set, if present.

AUTHOR

Dorian Taylor, <dorian at cpan.org>

SEE ALSO

Params::Registry

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.