NAME

       Paranoid::Input - Paranoid input functions

VERSION

       $Id: lib/Paranoid/Input.pm, 2.05 2017/02/06 01:48:57 acorliss Exp $

SYNOPSIS

         use Paranoid::Input;

         $rv = detaint($userInput, "login", $detainted);
         $rv = detaint(@userInput, "login", @detainted);
         $rv = detaint(%userInput, "login", %detainted);

         $rv = detaint($input, qr#\w+\s+\d+#s);
         $rv = detaint(@input, qr#\w+\s+\d+#s);
         $rv = detaint(%input, qr#\w+\s+\d+#s);

         $rv = stringMatch($input, @strings);

         $Paranoid::Input::regexes{'new_type"} = qr/\w\s+\d+/s;

         $rv = pchomp($lines);
         $rv = pchomp(@lines);
         $rv = pchomp(%dict);

         # Chomp $_
         $rv = pchomp();

DESCRIPTION

       This provides some generic functions for working with text-based input.  The main
       benefirst of this module is a relatively simple way of validating and detainting formatted
       text and performing platform-agnostic chomps.

SUBROUTINES/METHODS

   detaint
         $rv = detaint($userInput, "login", $val);

       This function populates the passed data object with the detainted input from the first
       argument.  The second argument specifies the type of data in the first argument, and is
       used to validate the input before detainting.  If you don't want to use one of the built-
       in regular expressions you can, instead, pass your own custom regular expression.

       The third argument is optional, but if used, must match the first argument's data type.
       If it is omitted all detainted values are used to overwrite the contents of the first
       argument.  If detaint fails for any reason undef is used instead.

       If the first argument fails to match against these regular expressions the function will
       return 0.  If the string passed is either undefined or a zero-length string it will also
       return 0.  And finally, if you attempt to use an unknown (or unregistered) data type it
       will also return 0, and log an error message in Paranoid::ERROR.

       The following regular expressions are known by name:

           Name            Description
           =========================================================
           alphabetic      Alphabetic characters
           alphanumeric    Alphabetic/numeric characters
           alphawhite      Alphabetic/whitespace characters
           alnumwhite      Alphabetic/numeric/whitespace characters
           email           RFC 822 Email address format
           filename        Essentially no-metacharacters
           fileglob        Same as filename, but with glob meta-
                           character support
           hostname        Alphanumeric/hyphenated host names
           ipv4addr        IPv4 address
           ipv4netaddr     IPv4 network address (CIDR/dotted quad)
           ipv6addr        IPv6 address
           ipv6netaddr     IPv6 network address (CIDR)
           login           UNIX login format
           nometa          Everything but meta-characters
           number          Integer/float/signed/unsigned
           int             Integer/signed/unsigned
           uint            Integer/unsigned
           float           Float/signed/unsigned
           ufloat          Float/unsigned
           bin             binary
           octal           octal
           hex             hexadecimal

   stringMatch
         $rv = stringMatch($input, @strings);

       This function does a multiline case insensitive regex match against the input for every
       string passed for matching.  This does safe quoted matches (\Q$string\E) for all the
       strings, unless the string is a perl Regexp (defined with qr//) or begins and ends with /.

       NOTE: this performs a study in hopes that for a large number of regexes will be performed
       faster.  This may not always be the case.

   pchomp
           $rv = pchomp(@lines);

       pchomp is meant to be a drop-in replacement for chomp, primarily where you want it to work
       as a platform-agnostic line chomper.  If $/ is altered in any manner (slurp mode, fixed
       record length, etc.) it will assume that's not important and automatically call chomp
       instead.  It should, then, be safe to be called in all instances in which you'd call chomp
       itself.

       In a nutshell, this function attempts to avoid the assumption that chomp makes in that the
       latter assumes that all input it works upon was authored on the same system, using the
       same input record separators.  Using pchomp in lieu of chomp will allow you to treat DOS,
       UNIX, and Mac-authored files identically with no additional coding.

       Because it is assumed that pchomp will be used in potentially high frequency scenarios no
       pdebug calls are made within it to avoid exercising the stack any more than necessary.  It
       is hoped that the relative simplicity of the subroutine should make debug use unnecessary.

DEPENDENCIES

       o   Carp

       o   Paranoid

       o   Paranoid::Debug

BUGS AND LIMITATIONS

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is licensed under the same terms as Perl, itself.  Please see
       http://dev.perl.org/licenses/ for more information.

       (c) 2005 - 2017, Arthur Corliss (corliss@digitalmages.com)