NAME

Brannigan::Validations - Built-in validation methods for Brannigan.

DESCRIPTION

This module contains all built-in validation methods provided natively by the Brannigan input validation/parsing system.

GENERAL PURPOSE VALIDATION METHOD

All these methods receive the value of a parameter, and other values that explicilty define the requirements. They return a true value if the parameter's value passed the test, or a false value otherwise.

required( $value, $boolean )

If $boolean has a true value, this method will check that a required parameter was indeed provided; otherwise (i.e. if $boolean is not true) this method will simply return a true value to indicate success.

You should note that if a parameter is required, and a non-true value is received (i.e. 0 or the empty string ""), this method considers the requirement as fulfilled (i.e. it will return true). If you need to make sure your parameters receive true values, take a look at the "is_true()" validation method.

Please note that if a parameter is not required and indeed isn't provided with the input parameters, any other validation methods defined on the parameter will not be checked.

forbidden( $value, $boolean )

If $boolean has a true value, this method will check that a forbidden parameter was indeed NOT provided; otherwise (i.e. if $boolean has a false value), this method will do nothing and simply return true.

is_true( $value, $boolean )

If $boolean has a true value, this method will check that $value has a true value (so, $value cannot be 0 or the empty string); otherwise (i.e. if $boolean has a false value), this method does nothing and simply returns true.

length_between( $value, $min_length, $max_length )

Makes sure the value's length (stringwise) is inside the range of $min_length-$max_length, or, if the value is an array reference, makes sure it has between $min_length and $max_length items.

min_length( $value, $min_length )

Makes sure the value's length (stringwise) is at least $min_length, or, if the value is an array reference, makes sure it has at least $min_length items.

max_length( $value, $max_length )

Makes sure the value's length (stringwise) is no more than $max_length, or, if the value is an array reference, makes sure it has no more than $max_length items.

exact_length( $value, $length )

Makes sure the value's length (stringwise) is exactly $length, or, if the value is an array reference, makes sure it has exactly $exact_length items.

integer( $value, $boolean )

If boolean is true, makes sure the value is an integer.

value_between( $value, $min_value, $max_value )

Makes sure the value is between $min_value and $max_value.

min_value( $value, $min_value )

Makes sure the value is at least $min_value.

max_value( $value, $max )

Makes sure the value is no more than $max_value.

array( $value, $boolean )

If $boolean is true, makes sure the value is actually an array reference.

hash( $value, $boolean )

If $boolean is true, makes sure the value is actually a hash reference.

one_of( $value, @values )

Makes sure a parameter's value is one of the provided acceptable values.

matches( $value, $regex )

Returns true if $value matches the regular express ("qr//") provided. Will return false if $regex is not a regular expression.

USEFUL PASSPHRASE VALIDATION METHODS

The following validations are useful for passphrase strength validations:

min_alpha( $value, $integer )

Returns a true value if $value is a string that has at least $integer alphabetic ("A-Z" and "a-z") characters.

max_alpha( $value, $integer )

Returns a true value if $value is a string that has at most $integer alphabetic ("A-Z" and "a-z") characters.

min_digits( $value, $integer )

Returns a true value if $value is a string that has at least $integer digits ("0-9").

max_digits( $value, $integer )

Returns a true value if $value is a string that has at most $integer digits ("0-9").

min_signs( $value, $integer )

Returns a true value if $value has at least $integer special or sign characters (e.g. "%^&!@#", or basically anything that isn't "A-Za-z0-9").

max_signs( $value, $integer )

Returns a true value if $value has at most $integer special or sign characters (e.g. "%^&!@#", or basically anything that isn't "A-Za-z0-9").

max_consec( $value, $integer )

Returns a true value if $value does not have a sequence of consecutive characters longer than $integer. Consequtive characters are either alphabetic (e.g. "abcd") or numeric (e.g. 1234).

max_reps( $value, $integer )

Returns a true value if $value does not contain a sequence of a repeated character longer than $integer. So, for example, if $integer is 3, then "aaa901" will return true (even though there's a repetition of the 'a' character it is not longer than three), while "9bbbb01" will return false.

max_dict( $value, $integer, [ \@dict_files ] )

Returns a true value if $value does not contain a dictionary word longer than $integer. By default, this method will look for the Unix dict files "/usr/dict/words", "/usr/share/dict/words" and "/usr/share/dict/linux.words". You can supply more dictionary files to look for with an array reference of full paths.

So, for example, if $integer is 3, then "a9dog51" will return true (even though "dog" is a dictionary word, it is not longer than three), but "a9punk51" will return false, as "punk" is longer.

WARNING: this method is known to not work properly when used in certain environments such as "PSGI", I'm investigating the issue.

AUTHOR

Ido Perlmuter, "<ido at ido50 dot net>"

BUGS

Please report any bugs or feature requests to "bug-brannigan at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Brannigan>. 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 Brannigan::Validations

You can also look for information at:

RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Brannigan>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Brannigan>
CPAN Ratings
<http://cpanratings.perl.org/d/Brannigan>
Search CPAN
<http://search.cpan.org/dist/Brannigan/>

LICENSE AND COPYRIGHT

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.