view release on metacpan or  search on metacpan

lib/FormValidator/Tiny.pm  view on Meta::CPAN

    my ($params, $errors) = validate_form $spec, $input_parameters;

Compares the given parameters against the named spec. The C<$input_parameters>
may be provided as either a hash or an array of alternating key-value pairs. All
keys and values must be provided as strings.

The method returns two values. The first, C<$params>, is the parameters as far
as they have been validated so far. The second, C<$errors> is the errors that
have been detected.

The C<$params> will be provided as a hash. The keys of this hash will match the
keys given in the spec. Some keys may be missing if the provided
C<$input_parameters> did not contain values or those values are invalid.

If there are no errors, the C<$errors> value will be set to C<undef>. With
errors, this will be hash of arrays. The keys of the hash will also match the
keys in the spec. Only fields with a validation error will be set. Each value
is an array of strings, with each string being an error message describing a
validation failure.

=head2 limit_character_set

    must => limit_character_set(@sets)
    must => limit_character_set(\@fc_sets, \@rc_sets);

This returns a subroutine that limits the allowed characters for an input. In
the first form, the character set limits are applied to all characters in the
value. In the second, the first array limits the characters permitted for the
first character and the second limits the characters permitted for the rest.

Character sets may be provided as single letters (e.g., "_"), as named unicode
character properties wrapped in square brackets (e.g., "[Uppercase_Letter]"), or
as ranges connected by a hyphen (e.g., "a-z").

=head2 length_in_range

    must => length_in_range('*', 10)
    must => length_in_range(10, '*')
    must => length_in_range(10, 100)

This returns a subroutine for use with C<must> declarations that asserts the
minimum and maximum string character length permitted for a value. Use an
asterisk to define no limit.

=head2 equal_to

    must => equal_to('field')

This returns a subroutine for use with C<must> declarations that asserts that
the value must be exactly equal to another field in the input.

=head2 number_in_range

    must => number_in_range('*', 100)
    must => number_in_range(100, '*')
    must => number_in_range(100, 500)
    must => number_in_range(exclusive => 100, exclusive => 500)

Returns a predicate for must that requires the integer to be within the given
range. The endpoints are inclusive by default. You can add the word "exclusive"
before a value to make the comparison exclusive instead. Using a '*' indicates
no limit at that end of the range.

=head2 one_of

    must => one_of(qw( a b c )),

Returns a predicate that requires the value to exactly match one of the
enumerated values.

=head2 split_by

    into => split_by(' ')
    into => split_by(qr/,\s*/)
    into => split_by(' ', 2)
    into => split_by(qr/,\s*/, 10)

Returns an into filter that splits the string into an array. The arguments are
similar to those accepted by Perl's built-in C<split>.

=head2 trim

    into => trim
    into => trim('left')
    into => trim('right')

Returns an into filter that trims whitespace from the input value. You can
provide an argument to trim only the left whitespace or the right whitespace.

=head1 VALIDATION SPECIFICATIONS

The validation specification is an array reference. Each key names a field to
validate. The value is an array of processing declarations. Each processing
declaration is a key-value pair. The inputs will be processed in the order they
appear in the spec. The key names the type of processing. The value describes
arguments for the processing. The processing declarations will each be executed
in the order they appear. The same processor may be applied multiple times.

=head2 Input Declarations

Input declarations modify the initial value and must be given at the very top of
the list of declarations for a field before all others.

=head3 from

    from => 'input_parameter_name'

Without this declaration, the validator pulls input from the parameter with the
same name as the key named in the validation spec. This input declaration
changes the key used for input.

=head3 as

    multiple => 1

The multiple input declaration tells the validator whether to interpret the
input parameter as a multiple input or not. Without this declaration or with it
set to 0, the validator will interpret multiple inputs as a single value,
ignoring all but the last. With this declaration, it treat the input as multiple
items, even if there are 0 or 1.