.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 2024-03-07 "perl v5.38.2" "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.10 2022/03/08 00:01:04 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 "IMPORT LISTS" .IX Header "IMPORT LISTS" This module exports the following symbols by default: .PP .Vb 1 \& detaint stringMatch pchomp .Ve .PP The following specialized import lists also exist: .PP .Vb 3 \& List Members \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& all @defaults NEWLINE_REGEX .Ve .SH VARIABLES .IX Header "VARIABLES" .SS NEWLINE_REGEX .IX Subsection "NEWLINE_REGEX" This returns regular expression that matches against DOS, UNIX, and legacy Mac line terminators. This is the regular expression used internally by pchomp to perform platform-agnostic chomps. .PP This is only exported if explicity requested, or under an import target of \&\fB:all\fR. .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 \&\fBNOTE\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 DOS, UNIX, 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 free software. Similar to Perl, you can redistribute it and/or modify it under the terms of either: .PP .Vb 7 \& a) the GNU General Public License \& as published by the \& Free Software Foundation ; either version 1 \& , or any later version \& , or \& b) the Artistic License 2.0 \& , .Ve .PP subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark. .PP (c) 2005 \- 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 \- 2020, Paranoid Inc. (www.paranoid.com)