Ron Savage
and 1 contributors

NAME

MojoX::Validate::Util - A very convenient wrapper around Mojolicious::Validator

Synopsis

This program ships as scripts/synopsis.pl.

        #!/usr/bin/env perl
        #
        # This is a copy of t/01.range.t, without the Test::More parts.

        use strict;
        use warnings;

        use MojoX::Validate::Util;

        # ------------------------------------------------

        my(%count)              = (fail => 0, pass => 0, total => 0);
        my($checker)    = MojoX::Validate::Util -> new;

        $checker -> add_dimension_check;

        my(@data) =
        (
                {height => ''},          # Pass.
                {height => '1'},         # Fail. No unit.
                {height => '1cm'},       # Pass.
                {height => '1 cm'},      # Pass.
                {height => '1m'},        # Pass.
                {height => '40-70.5cm'}, # Pass.
                {height => '1.5 -2m'},   # Pass.
                {height => 'z1'},        # Fail. Not numeric.
        );

        my($expected);
        my($params);

        for my $i (0 .. $#data)
        {
                $count{total}++;

                $params   = $data[$i];
                $expected = ( ($i == 1) || ($i == $#data) ) ? 0 : 1;

                $count{fail}++ if ($expected == 0);

                $count{pass}++ if ($checker -> check_dimension($params, 'height', ['cm', 'm']) == 1);
        }

        print "Test counts: \n", join("\n", map{"$_: $count{$_}"} sort keys %count), "\n";

This is the printout of synopsis.pl:

        Test counts:
        fail: 2
        pass: 6
        total: 8

See also scripts/demo.pl and t/*.t.

Description

MojoX::Validate::Util is a wrapper around Mojolicious::Validator which provides a suite of convenience methods for validation.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

Install MojoX::Validate::Util as you would any Perl module:

Run:

        cpanm MojoX::Validate::Util

or run:

        sudo cpan Text::Balanced::Marpa

or unpack the distro, and then run:

        perl Makefile.PL
        make (or dmake or nmake)
        make test
        make install

Constructor and Initialization

new() is called as my($parser) = MojoX::Validate::Util -> new.

It returns a new object of type MojoX::Validate::Util.

new() does not take any parameters.

Methods

add_dimension_check()

Called in BEGIN(). The check itself is called dimension, and it is used by calling "check_dimension($params, $topic, $units)".

add_url_check()

Called in BEGIN(). The check itself is called url, and it is used by calling "check_url($params, $topic)".

This method uses URI::Find::Schemeless.

check_ascii_digits($params, $topic)

This test uses 2 steps:

o The length of $$params{$topic} must be > 0, and
o All digits in $$params{$topic} must be in the set [0-9]

Parameters:

o $params => A hashref

E.g.: $params = {age => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'age'.

Return value: Integer (0 or 1):

o 0 => Invalid
o 1 => Valid

See also "check_equal_to($params, $topic, $other_topic)" and "check_number($params, $topic, $expected)".

Note: This method uses neither Mojolicious::Validator nor Mojolicious::Validator::Validation.

check_dimension($params, $topic, $units)

Parameters:

o $params => A hashref

E.g.: $params = {height => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'height'.

o $value => A string containing a floating point number followed by one of the abbreviations

Or, the string can contain 2 floating point numbers separated by a hyphen, followed by one of the abbreviations.

Spaces can be used liberally within the string, but of course not within the numbers.

So the code tests $$params{$topic} = $value.

o $units => An arrayref of strings of unit names or abbreviations

E.g.: $units = ['cm', 'm'].

Return value: Integer (0 or 1) as returned by Mojolicious::Validator::Validation#is_valid:

o 0 => Invalid
o 1 => Valid

For some non-undef $topic, $value and $units, here are some sample values for the hashref and the corresponding return values (using $units = ['cm', 'm']):

o {height => ''}: returns 1 (sic)
o {height => '1'}: returns 0
o {height => '1cm'}: returns 1
o {height => '1 cm'}: returns 1
o {height => '1m'}: returns 1
o {height => '40-70.5cm'}: returns 1
o {height => '1.5 -2 m'}: returns 1

check_equal_to($params, $topic, $other_topic)

This test uses eq. For a test using ==, see "check_number($params, $topic, $other_topic)".

Parameters:

o $params => A hashref

E.g.: $params = {password => $value_1, confirm_password => $value_2, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'password'.

o $other_topic => The name of the other key within $params whose value should match $value_1

E.g.: $other_topic = 'confirm_password'.

So the code tests (using eq) $$params{$topic} = $value_1 with $$params{$other_topic} = $value_2.

Return value: Integer (0 or 1) as returned by Mojolicious::Validator::Validation#is_valid.

o 0 => Invalid
o 1 => Valid

See also "check_ascii_digits($params, $topic)" and "check_number($params, $topic, $expected)".

check_key_exists($params, $topic)

Parameters:

o $params => A hashref

E.g.: $params = {email_address => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'email_address'.

Return value: Integer (0 or 1):

o 0 => Invalid
o 1 => Valid

For some non-undef $topic, here are some sample values for $params and the corresponding return values (using $topic = 'x'):

o {}: returns 0
o {x => undef}: returns 1
o {x => ''}: returns 1
o {x => '0'}: returns 1
o {x => 0}: returns 1
o {x => 'yz'}: returns 1

This method uses neither Mojolicious::Validator nor Mojolicious::Validator::Validation.

check_member($params, $topic, $set)

Parameters:

o $params => A hashref

E.g.: $params = {love_popup_ads => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'love_popup_ads'.

o $set => An arrayref of strings

E.g.: ['Yes', 'No'].

Return value: Integer (0 or 1) as returned by Mojolicious::Validator::Validation#is_valid.

o 0 => Invalid
o 1 => Valid

check_number($params, $topic, $expected)

This test uses ==. For a test using eq, see "check_equal_to($params, $topic, $other_topic)".

Parameters:

o $params => A hashref

E.g.: $params = {age => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'age'.

o $expected => An integer

E.g.: 99.

Return value: Integer (0 or 1):

o 0 => Invalid
o 1 => Valid

For some non-undef $topic, $value and $expected, here are some sample values for $value and $expected, and the corresponding return values:

o $value == 99 and $expected != 99: returns 0
o $value == 99 and $expected == 99: returns 1

See also "check_ascii_digits($params, $topic)" and "check_equal_to($params, $topic, $other_topic)".

Note: This method uses neither Mojolicious::Validator nor Mojolicious::Validator::Validation.

check_optional($params, $topic)

Parameters:

o $params => A hashref

E.g.: $params = {email_address => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'email_address'.

Return value: Integer (0 or 1) as returned by Mojolicious::Validator::Validation#is_valid:

o 0 => Invalid
o 1 => Valid

For some non-undef $topic, here are some sample values for $params and the corresponding return values (using $topic = 'x'):

o {}: returns 0
o {x => undef}: returns 0
o {x => ''}: returns 0 (because the length is 0)
o {x => '0'}: returns 1
o {x => 0}: returns 1
o {x => 'yz'}: returns 1

See also "check_required($params, $topic)".

See scripts/demo.pl and t/03.email.address.t.

check_required($params, $topic)

Parameters:

o $params => A hashref

E.g.: $params = {email_address => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'email_address'.

Return value: Integer (0 or 1) as returned by Mojolicious::Validator::Validation#is_valid:

o 0 => Invalid
o 1 => Valid

For some non-undef $topic, here are some sample values for $params and the corresponding return values (using $topic = 'x'):

o {}: returns 0
o {x => undef}: returns 0
o {x => ''}: returns 0 (because the length is 0)
o {x => '0'}: returns 1
o {x => 0}: returns 1
o {x => 'yz'}: returns 1

See also "check_optional($params, $topic)".

See scripts/demo.pl and t/03.email.address.t.

check_url($params, $topic)

Parameters:

o $params => A hashref

E.g.: $params = {homepage => $value, ...}.

o $topic => The name of the parameter being tested

E.g.: $topic = 'homepage'.

Return value: Integer (0 or 1) as returned by Mojolicious::Validator::Validation#is_valid:

o 0 => Invalid
o 1 => Valid

For some non-undef $topic, here are some sample values for $params and the corresponding return values (using $topic = 'homepage'):

o {homepage => 'localhost'}: returns 0.
o {homepage => 'savage.net.au'}: returns 1.
o {homepage => 'http://savage.net.au'}: returns 1.
o {homepage => 'https://savage.net.au'}: returns 1.

new()

url_finder()

Returns an object of type URI::Find::Schemeless.

validation()

Returns an object of type Mojolicious::Validator::Validation

validator()

Returns an object of type Mojolicious::Validator

FAQ

Why did you prefix all the method names with 'check_'?

In order to clarify which methods are part of this module and which are within Mojolicious::Validator or Mojolicious::Validator::Validation.

Why provide both check_optional() and check_required()?

Calling either required() or optional() within Mojolicious::Validator::Validation, and then calling is_valid() can return the same value, but the difference becomes apparent after (then) calling methods such as failed(), has_error(), output() and passed().

This will be much clearer after you study the output of scripts/demo.pl and t/03.email.address.t.

Why did you not make any provision for Mojolicious-style filters?

I will add them if there is any interest, but ATM I take the attitude: Release early and release often.

Why did you not use the module boolean?

I was tempted, but it would mean 2 extra, albeit small, complexities:

o Another pre-requisite

And that conflicts with the minimalistic philosophy of Mojolicious itself.

o Handling the types of all the values returned from the Mojolicious code

See Also

Mojolicious::Validator

Mojolicious::Validator::Validation

Machine-Readable Change Log

The file Changes was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Repository

https://github.com/ronsavage/MojoX-Validate-Util

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=MojoX::Validate::Util.

Author

MojoX::Validate::Util was written by Ron Savage <ron@savage.net.au> in 2017.

My homepage: http://savage.net.au/.

Copyright and Licence

Australian copyright (c) 2017, Ron Savage.

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Perl License, a copy of which is available at:
        http://dev.perl.org/licenses/.