.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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 turned on, 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CGI::ValidOp::Check 3pm" .TH CGI::ValidOp::Check 3pm "2009-11-30" "perl v5.20.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" CGI::ValidOp::Check \- base class for CGI::ValidOp checks .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& package CGI::ValidOp::Check::demo; \& use base qw/ CGI::ValidOp::Check /; \& \& sub default { \& ( \& qr/^demo$/, # validator \& \*(Aq$label must equal "demo."\*(Aq, # error message \& ) \& } \& \& sub color { \& my $self = shift; \& ( \& sub { \& my( $value, $color ) = @_; \& $self\->pass( $1 ) if $value =~ /^($color)$/i; \& $self\->fail( "\e$label must be the color: $color." ); \& }, \& ) \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" CGI::ValidOp::Check contains all the code to validate data from CGI::ValidOp::Param objects, and enables simple creation your own checks. Unless you're creating or testing your own checks, you should use and read the documentation for CGI::ValidOp instead. .SS "How checks are used" .IX Subsection "How checks are used" Each check module must contain at least one check, and can contain as many as you care to create. This document walks through the creation of one module containing mutliple checks. Some of ValidOp's default checks are organized by types of data (e.g. 'text', 'number'), but there's nothing to say you must also do this. You may find it convenient to package all the checks for one project in a single module. .PP Your check can be used in three ways. The first is with a simple scalar corresponding to the module name: .PP .Vb 1 \& $validop\->param( \*(Aqprice\*(Aq, [ \*(Aqmychecks\*(Aq ]); .Ve .PP The second is by calling a particular check within the package: .PP .Vb 1 \& $validop\->param( \*(Aqprice\*(Aq, [ \*(Aqmychecks::robot\*(Aq ]); .Ve .PP The third is by passing parameters to either the module or a check: .PP .Vb 2 \& $validop\->param( \*(Aqprice\*(Aq, [ \*(Aqmychecks(3,6)\*(Aq ]); \& $validop\->param( \*(Aqprice\*(Aq, [ \*(Aqmychecks::robot("Robbie")\*(Aq ]); .Ve .SH "METHODS" .IX Header "METHODS" Unless you're creating or testing your own checks, this reference is not likely to help you. You can use ValidOp's public \s-1API\s0 without knowing a thing about ValidOp::Check's internals. .SS "\fIparams()\fP" .IX Subsection "params()" The 'params' method returns a list passed to the check by the user: .PP .Vb 1 \& $validop\->param( \*(Aqprice\*(Aq, [ \*(Aqmychecks(3,6)\*(Aq ]); .Ve .PP These parameters are captured by splitting the contents of the parenthesis on commas. The resulting list is made available with the 'params' method. .ie n .SS "validator( $regexp_or_coderef )" .el .SS "validator( \f(CW$regexp_or_coderef\fP )" .IX Subsection "validator( $regexp_or_coderef )" Sets or returns the validator. .ie n .SS "errmsg( $error_message )" .el .SS "errmsg( \f(CW$error_message\fP )" .IX Subsection "errmsg( $error_message )" Sets or returns the error message. When CGI::ValidOp::Param parses these error messages, it replaces every isntance of \f(CW$label\fR with the parameter's 'label' property or, if that does not exist, with the parameter's 'name'. .ie n .SS "check( $tainted_value )" .el .SS "check( \f(CW$tainted_value\fP )" .IX Subsection "check( $tainted_value )" \&\fIcheck()\fR runs its calling object's validator against the incoming tainted value. It returns the resulting value on success, or \f(CW\*(C`undef\*(C'\fR on failure. \fIcheck()\fR itself does very little work; it finds what type of validator it has (regex and coderef are the only types currently allowed) and farms out the work to the appropriate method. .ie n .SS "check_regexp( $tainted, $validator )" .el .SS "check_regexp( \f(CW$tainted\fP, \f(CW$validator\fP )" .IX Subsection "check_regexp( $tainted, $validator )" \&\fIcheck_regexp()\fR captures the result of matching \f(CW$tainted\fR against \f(CW$validator\fR, using code similar to this: .PP .Vb 2 \& $tainted =~ /($validator)/; \& return $1; .Ve .PP Note that the return value is untainted. Also note that the code does \fBnot\fR anchor the regular expression with ^ (at the beginning) or $ (at the end). In other words, if you used this quoted regex as a check: .PP .Vb 1 \& qr/demo/ .Ve .PP any string containing \*(L"demo\*(R" (e.g. \*(L"demographics,\*(R" \*(L"modemophobia\*(R") would pass. This may or may not be what you intend. .ie n .SS "check_code( $tainted, $validator )" .el .SS "check_code( \f(CW$tainted\fP, \f(CW$validator\fP )" .IX Subsection "check_code( $tainted, $validator )" \&\fIcheck_code()\fR passes \f(CW$tainted\fR to the anonymous subroutine referenced by \f(CW$validator\fR and returns the result. The two most notable differences from regex checks are that the value of \fIparams()\fR is passed into the validator subroutine and that the entire thing croaks if the return value is tainted. .PP ValidOp's default behavior is to die like a dog if your coderef returns a tainted value. This safe default can be changed by returning a third list item from your check subroutine, a hashref of additional properties: .PP .Vb 5 \& sub should_allow_tainted {( \& sub { $_[ 0 ] }, \& \*(AqThis should be an error message\*(Aq, \& { allow_tainted => 1, } \& )} .Ve .SS "is_tainted" .IX Subsection "is_tainted" .SH "CREATING A CHECK MODULE" .IX Header "CREATING A CHECK MODULE" .SS "Starting a check module" .IX Subsection "Starting a check module" For the moment, your check module must be in the CGI::ValidOp::Check namespace; future versions will allow more flexibility. The module must be in Perl's search path. .PP .Vb 1 \& package CGI::ValidOp::Check::demo; .Ve .PP You must subclass CGI::ValidOp::Check for your module. It contains methods that the rest of the code uses to perform the validation. .PP .Vb 1 \& use base qw/ CGI::ValidOp::Check /; .Ve .SS "Creating checks" .IX Subsection "Creating checks" Each check is completely defined by a single subroutine. If you define only one check in your module, it should be called 'default'. Using only the module name as a check, the 'default' subroutine is called. There's nothing to stop you calling your single check something else, but it does mean less intuitive use. .PP Checks return one to three scalar values. The first value is the check itself, and is required. The second value is an optional error message. The third is an optional list of additional properties, defined for the check and made available as methods. .PP .Vb 3 \& sub check_name { \& ( $check, $errmsg, \e%options ) \& } .Ve .SS "Types of checks" .IX Subsection "Types of checks" \fIQuoted regular expression\fR .IX Subsection "Quoted regular expression" .PP The simplest checks are quoted regular expressions. These are perfect for relatively static data. This one checks that the incoming value is \*(L"demo\*(R" and sets a custom error message. Any instance of '$label' in an error message is substituted with the parameter's 'label' property, if you define one, or the parameter's 'name' property (which is required and thus guaranteed to exist). .PP .Vb 6 \& sub default { \& ( \& qr/^demo$/, # validator \& \*(Aq$label must equal "demo."\*(Aq, # error message \& ) \& } .Ve .PP Parameters are validated against Regex checks with the check_regexp method. .PP You cannot pass parameters to a regex check (more to the point you can, but they'll be ignored). .PP \fISubroutine reference\fR .IX Subsection "Subroutine reference" .PP These checks can be much more powerful and flexible, but require a little extra work. .PP .Vb 11 \& sub color { \& my $self = shift; \& ( \& sub { \& my( $value, $color ) = @_; \& return $1 if $value =~ /^($color)$/i; \& $self\->errmsg( "\e$label must be the color: $color." ); \& return; \& }, \& ) \& } .Ve .PP You'll note that the check only returns one item, an anonymous subroutine. This coderef sets the check's error message with the 'errmsg' method, allowing it to pass incoming parameters into the error message. (You could supply an error message here as the second array element, but it would be overridden.) .PP Parameters are validated against coderef checks with the check_code method: .PP Right now the only additional property available ValidOp checks is 'allow_tainted.' ValidOp's stock 'length' check uses this, reasoning that just knowing the length of an incoming value isn't reason enough to trust it. .PP .Vb 1 \& package Main; \& \& my $demo = CGI::ValidOp::Check::demo\->new; \& is( $demo\->check( \*(Aqfailure\*(Aq ), undef ); \& is( $demo\->check( \*(Aqdemo\*(Aq ), \*(Aqdemo\*(Aq ); \& my $value = $demo\->check( \*(Aqdemo\*(Aq ); \& ok( ! $demo\->is_tainted( $value )); \& \& my $demo_color = CGI::ValidOp::Check::demo\->new( \*(Aqcolor\*(Aq, \*(Aqred\*(Aq ); \& is( $demo_color\->check( \*(Aqgreen\*(Aq ), undef ); \& is( $demo_color\->errmsg, \*(Aq$label must be the color: red.\*(Aq ); \& is( $demo_color\->check( \*(Aqred\*(Aq ), \*(Aqred\*(Aq ); .Ve .SH "AUTHOR" .IX Header "AUTHOR" Randall Hansen .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2003\-2005 Randall Hansen. All rights reserved. .PP This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. .PP See http://www.perl.com/perl/misc/Artistic.html