.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Paranoid::Input 3pm"
.TH Paranoid::Input 3pm "2018-11-09" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Paranoid::Input \- Paranoid input functions
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR lib/Paranoid/Input.pm, 2.06 2018/08/05 01:21:48 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Paranoid::Input;
\&
\&  $rv = detaint($userInput, "login", $detainted);
\&  $rv = detaint(@userInput, "login", @detainted);
\&  $rv = detaint(%userInput, "login", %detainted);
\&
\&  $rv = detaint($input, qr#\ew+\es+\ed+#s);
\&  $rv = detaint(@input, qr#\ew+\es+\ed+#s);
\&  $rv = detaint(%input, qr#\ew+\es+\ed+#s);
\&
\&  $rv = stringMatch($input, @strings);
\&
\&  $Paranoid::Input::regexes{\*(Aqnew_type"} = qr/\ew\es+\ed+/s;
\&
\&  $rv = pchomp($lines);
\&  $rv = pchomp(@lines);
\&  $rv = pchomp(%dict);
\&
\&  # Chomp $_
\&  $rv = pchomp();
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "detaint"
.IX Subsection "detaint"
.Vb 1
\&  $rv = detaint($userInput, "login", $val);
.Ve
.PP
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.
.PP
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 \fBundef\fR is
used instead.
.PP
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 \fBParanoid::ERROR\fR.
.PP
The following regular expressions are known by name:
.PP
.Vb 10
\&    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
.Ve
.SS "stringMatch"
.IX Subsection "stringMatch"
.Vb 1
\&  $rv = stringMatch($input, @strings);
.Ve
.PP
This function does a multiline case insensitive regex match against the 
input for every string passed for matching.  This does safe quoted matches 
(\eQ$string\eE) for all the strings, unless the string is a perl Regexp 
(defined with qr//) or begins and ends with /.
.PP
\&\fB\s-1NOTE\s0\fR: this performs a study in hopes that for a large number of regexes
will be performed faster.  This may not always be the case.
.SS "pchomp"
.IX Subsection "pchomp"
.Vb 1
\&    $rv = pchomp(@lines);
.Ve
.PP
\&\fBpchomp\fR is meant to be a drop-in replacement for chomp, primarily where you
want it to work as a platform-agnostic line chomper.  If \fI$/\fR is altered in
any manner (slurp mode, fixed record length, etc.) it will assume that's not
important and automatically call \fBchomp\fR instead.  It should, then, be safe 
to be called in all instances in which you'd call \fBchomp\fR itself.
.PP
In a nutshell, this function attempts to avoid the assumption that \fBchomp\fR
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 \fBpchomp\fR in
lieu of \fBchomp\fR will allow you to treat \s-1DOS, UNIX,\s0 and Mac-authored files
identically with no additional coding.
.PP
Because it is assumed that \fBpchomp\fR will be used in potentially high
frequency scenarios no \fBpdebug\fR 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.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "o" 4
.IX Item "o"
Carp
.IP "o" 4
.IX Item "o"
Paranoid
.IP "o" 4
.IX Item "o"
Paranoid::Debug
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2005 \- 2017, Arthur Corliss (corliss@digitalmages.com)