Provided by: libdata-validate-perl_0.09-3_all bug

NAME

       Data::Validate - common data validation methods

SYNOPSIS

         use Data::Validate qw(:math);

         if(defined(is_integer($suspect))){
               print "Looks like an integer\n";
         }

         my $name = is_alphanumeric($suspect);
         if(defined($name)){
               print "$name is alphanumeric, and has been untainted\n";
         } else {
               print "$suspect was not alphanumeric"
         }

         # or as an object
         my $v = Data::Validate->new();

         die "'foo' is not an integer" unless defined($v->is_integer('foo'));

DESCRIPTION

       This module collects common validation routines to make input validation, and untainting
       easier and more readable.  Most of the functions are not much shorter than their direct
       perl equivalent (and are much longer in some cases), but their names make it clear what
       you're trying to test for.

       Almost all functions return an untainted value if the test passes, and undef if it fails.
       This means that you should always check for a defined status explicitly.  Don't assume the
       return will be true. (e.g. is_integer(0))

       The value to test is always the first (and often only) argument.

FUNCTIONS

           new - constructor for OO usage

             new();

           Description
               Returns a Data::Validator object.  This lets you access all the validator function
               calls as methods without importing them into your namespace or using the clumsy
               Data::Validate::function_name() format.

           Arguments
               None

           Returns
               Returns a Data::Validate object

           is_integer - is the value an integer?

             is_integer($value);

           Description
               Returns the untainted number if the test value is an integer, or can be cast to
               one without a loss of precision.  (i.e. 1.0 is considered an integer, but 1.0001
               is not.)

           Arguments
               $value
                   The potential integer to test.

           Returns
               Returns the untainted integer on success, undef on failure.  Note that the return
               can be 0, so always check with defined()

           Notes, Exceptions, & Bugs
               Number translation is done by POSIX casting tools (strtol).

           is_numeric - is the value numeric?

             is_numeric($value);

           Description
               Returns the untainted number if the test value is numeric according to Perl's own
               internal rules.  (actually a wrapper on Scalar::Util::looks_like_number)

           Arguments
               $value
                   The potential number to test.

           Returns
               Returns the untainted number on success, undef on failure.  Note that the return
               can be 0, so always check with defined()

           Notes, Exceptions, & Bugs
               Number translation is done by POSIX casting tools (strtol).

           is_hex - is the value a hex number?

             is_hex($value);

           Description
               Returns the untainted number if the test value is a hex number.

           Arguments
               $value
                   The potential number to test.

           Returns
               Returns the untainted number on success, undef on failure.  Note that the return
               can be 0, so always check with defined()

           Notes, Exceptions, & Bugs
               None

           is_oct - is the value an octal number?

             is_oct($value);

           Description
               Returns the untainted number if the test value is a octal number.

           Arguments
               $value
                   The potential number to test.

           Returns
               Returns the untainted number on success, undef on failure.  Note that the return
               can be 0, so always check with defined()

           Notes, Exceptions, & Bugs
               None

           is_between - is the value between two numbers?

             is_between($value, $min, $max);

           Description
               Returns the untainted number if the test value is numeric, and falls between $min
               and $max inclusive.  Note that either $min or $max can be undef, which means
               'unlimited'.  i.e. is_between($val, 0, undef) would pass for any number zero or
               larger.

           Arguments
               $value
                   The potential number to test.

               $min
                   The minimum valid value.  Unlimited if set to undef

               $max
                   The maximum valid value.  Unlimited if set to undef

           Returns
               Returns the untainted number on success, undef on failure.  Note that the return
               can be 0, so always check with defined()

           is_greater_than - is the value greater than a threshold?

             is_greater_than($value, $threshold);

           Description
               Returns the untainted number if the test value is numeric, and is greater than
               $threshold. (not inclusive)

           Arguments
               $value
                   The potential number to test.

               $threshold
                   The minimum value (non-inclusive)

           Returns
               Returns the untainted number on success, undef on failure.  Note that the return
               can be 0, so always check with defined()

           is_less_than - is the value less than a threshold?

             is_less_than($value, $threshold);

           Description
               Returns the untainted number if the test value is numeric, and is less than
               $threshold. (not inclusive)

           Arguments
               $value
                   The potential number to test.

               $threshold
                   The maximum value (non-inclusive)

           Returns
               Returns the untainted number on success, undef on failure.  Note that the return
               can be 0, so always check with defined()

           is_equal_to - do a string/number neutral ==

             is_equal_to($value, $target);

           Description
               Returns the target if $value is equal to it.  Does a math comparison if both
               $value and $target are numeric, or a string comparison otherwise.  Both the $value
               and $target must be defined to get a true return.  (i.e.  undef != undef)

           Arguments
               $value
                   The  value to test.

               $target
                   The value to test against

           Returns
               Unlike most validator routines, this one does not necessarily untaint its return
               value, it just returns $target.  This has the effect of untainting if the target
               is a constant or other clean value.  (i.e. is_equal_to($bar, 'foo')).  Note that
               the return can be 0, so always check with defined()

           is_even - is a number even?

             is_even($value);

           Description
               Returns the untainted $value if it's numeric, an integer, and even.

           Arguments
               $value
                   The  value to test.

           Returns
               Returns $value (untainted). Note that the return can be 0, so always check with
               defined().

           is_odd - is a number odd?

             is_odd($value);

           Description
               Returns the untainted $value if it's numeric, an integer, and odd.

           Arguments
               $value
                   The value to test.

           Returns
               Returns $value (untainted). Note that the return can be 0, so always check with
               defined().

           is_alphanumeric - does it only contain letters and numbers?

             is_alphanumeric($value);

           Description
               Returns the untainted $value if it is defined and only contains letters (upper or
               lower case) and numbers.  Also allows an empty string - ''.

           Arguments
               $value
                   The value to test.

           Returns
               Returns $value (untainted). Note that the return can be 0, so always check with
               defined().

           is_printable - does it only contain printable characters?

             is_alphanumeric($value);

           Description
               Returns the untainted $value if it is defined and only contains printable
               characters as defined by the composite POSIX character class [[:print:][:space:]].
               Also allows an empty string - ''.

           Arguments
               $value
                   The value to test.

           Returns
               Returns $value (untainted). Note that the return can be 0, so always check with
               defined().

           length_is_between - is the string length between two limits?

             length_is_between($value, $min, $max);

           Description
               Returns $value if it is defined and its length is between $min and $max inclusive.
               Note that this function does not untaint the value.

               If either $min or $max are undefined they are treated as no-limit.

           Arguments
               $value
                   The value to test.

               $min
                   The minimum length of the string (inclusive).

               $max
                   The maximum length of the string (inclusive).

           Returns
               Returns $value.  Note that the return can be 0, so always check with defined().
               The value is not automatically untainted.

AUTHOR

       Richard Sonnen <sonnen@richardsonnen.com>.

COPYRIGHT

       Copyright (c) 2004 Richard Sonnen. All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 89:
           You can't have =items (as at line 97) unless the first thing after the =over is an
           =item