NAME Dpchrist::CGI - utility subroutines for CGI scripts DESCRIPTION This documentation describes module revision $Revision: 1.43 $. This is alpha test level software and may change or disappear at any time. GLOBALS %CHECKBOX_ARGS %CHECKBOX_ARGS = (); Default argments used by gen_checkbox(). $CHECKSUM_SALT $CHECKSUM_SALT = join ' ', __PACKAGE__, __FILE__, __LINE__; Default hashing salt used by gen_hidden_checksum(). Caller should set this value after use'ing this module. %PASSWORD_FIELD_ARGS %PASSWORD_FIELD_ARGS = ( -size => 70, -maxlength => 80, ); Default argments used by gen_password(). $RX_UNTAINT_CHECKBOX $RX_UNTAINT_CHECKBOX = qr/(on)/; Regular expression used for untainting paths. $RX_UNTAINT_PATH $RX_UNTAINT_PATH = qr/([^\x00]+)/; Regular expression used for untainting paths. $RX_UNTAINT_TEXTAREA $RX_UNTAINT_TEXTAREA = qr/([\PC\n\r]+)/; Regular expression used for untainting textareas. $RX_UNTAINT_TEXTFIELD $RX_UNTAINT_TEXTFIELD = qr/([\PC]+)/; Regular expression used for untainting textfields and password fields. %TD_ATTR %TD_ATTR = ( -align => 'LEFT', -valign => 'TOP', ); Default attributes used by gen_td(). %TEXTAREA_ARGS TEXTAREA_ARGS = ( -maxlength => 32*1024, -columns => 80, -rows => 24, -wrap => 'physical', ); Default arguments used by gen_textarea(). %TEXTFIELD_ARGS %TEXTFIELD_ARGS = ( -size => 70, -maxlength => 80, ); Default arguments used by gen_textfield(). %TH_ATTR %TH_ATTR = ( -align => 'LEFT', -valign => 'TOP', -width => '20%', ); Default attributes used by gen_th(). SUBROUTINES calc_checksum my $md5 = calc_checksum(LIST); # LIST are items to be fed into the checksum Walks list and expands array references. Passes through call to Digest::MD5::md5_hex() using $CHECKSUM_SALT and walked list. LIST items, and referenced array items, should be strings, otherwise the checksum seems to be different for each hit (?). Calls Carp::confess() on error. dump_cookies push @debug_html, pre(escapeHTML(dump_cookies())); Calls get_cookies_as_rhh() (see below), feeds the returned reference to Data::Dumper->Dump(), and returns the result. dump_params push @debug_html, pre(escapeHTML(dump_params())); push @debug_html, pre(escapeHTML(dump_params(OBJECT))); # OBJECT (optional) is a CGI object or CGI-derived object Calls get_params_as_rha() (see below), feeds the returned reference to Data::Dumper->Dump(), and returns the result. gen_checkbox push @html, gen_checkbox(ARGS); # ARGS are named arguments Merges named arguments ARGS with default arguments %CHECKBOX_ARGS (ARGS have priority), and passes through call with net arguments to CGI::checkbox(). gen_hidden push @html, gen_hidden(-name => NAME, -value => VALUE); # NAME is a CGI parameter name # VALUE is the parameter value, or a reference to a list of values Returns an array of HTML elements: [0] A hidden control with name NAME and value VALUE. [1] A hidden control with name given by NAME with '_ck' suffix and value given by calling calc_checksum() with $CHECKSUM_SALT and incoming arguments. Calls Carp::confess() on error. gen_password_field push @html, gen_password_field(ARGS); # ARGS are named arguments Merges named arguments ARGS with default arguments %PASSWORD_FIELD_ARGS (ARGS have priority), and passes through call with net arguments to CGI::password_field(). gen_td push @html, table( Tr([ th('one') . gen_td(ARGS), th('two') . gen_td(ATTR, ARGS), ])); # ARGS are named arguments # ATTR (optional) is a reference to a hash of attributes Merges named attributes ATTR with default attributes %TD_ATTR (ATTR has priority) and passes through call with net attributes and arguments to CGI::td(). gen_textarea push @html, gen_textarea(ARGS); # ARGS is a list of named arguments Merges name arguments ARGS with default arguments %TEXTAREA_ARGS (ARGS has priority) and passes through call with net arguments to CGI::textarea(). gen_textfield push @html, gen_textfield(ARGS); # ARGS is a list of named arguments Merges named arguments ARGS with default arguments %TEXTAREA_ARGS (ARGS has priority) and passes through call with net attributes and arguments to CGI::textfield(). gen_th push @html, table( Tr([ gen_th(ARGS) . td(1), gen_th(ATTR, ARGS) . td(2), ])); # ARGS is a list of arguments # ATTR (optional) is a reference to a hash of named attributes Merges named attributes ATTR with default attributes %TH_ATTR (ATTR has priority) and passes through call with net attributes and arguments to CGI::th(). get_cookies_as_rhh my $cookies = get_cookies_as_rhh(); Calls CGI::cookie() in list context for all CGI cookies and returns a reference to a hash-of-hashes data structure. get_params_as_rha my $params = get_params_as_rha(); my $params = get_params_as_rha(OBJECT); # OBJECT (optional) is a CGI object or CGI-derived object Calls CGI::param() in list context for all CGI parameters and returns a hash-of-arrays data structure. Calls Carp::confess() on error. merge_args merge_args(ARRAYREF, ARGS); # ARRAYREF is a reference to an array # ARGS is a reference to a hash of named arguments Inserts or merges named arguments ARGS into array referenced by ARRAYREF. Typically used with CGI.pm widget generating functions, such as textarea(). Referenced array is modified in the process, and key/value pairs may be reordered. Returns void. Calls Carp::confess() on error. merge_attr merge_attr(ARRAYREF, ATTR); # ARRAYREF is a reference to an array # ATTR is a reference to a hash of named attributes Inserts or merges named attributes ATTR into array referenced by ARRAYREF. Attributes in first element of referenced array take precedence over attributes in ATTR. Typically used with CGI.pm tag generating functions, such as td(). First element of referenced array may be created or modified in the process. Returns void. Doesn't bother to merge if reference array is empty. Returns void. Calls Carp::confess() on error. nbsp push @html, nbsp(); push @html, nbsp(EXPR); # EXPR (optional) is a whole number Returns one or more nonbreaking space HTML character entities. Calls Carp::confess() on error. untaint_checkbox my @untainted = untaint_checkbox(LIST); # LIST are strings to be untainted Passes through call to untaint_regex() using a RX suitable for checkboxs ('on'). untaint_path my @untainted = untaint_path(LIST); # LIST are strings to be untainted Passes through call to untaint_regex() using a RX suitable for Unix paths (everying except NULL). untaint_regex my @untainted = untaint_regex(RX, LIST); # RX is a regular epxression # LIST are strings to be untainted Applies regular expression to each element in LIST. If LIST is empty, returns void. In list context, process LIST and return first captured substrings for each LIST item. In scalar context, process first LIST item and return first captured substring. Caller usually creates RX with the quote regular expression operator 'qr()'. Returns undef for LIST elements that are references. Calls Carp::confess() on error. Calls Carp::cluck() if LIST contains undefined values or references. untaint_textarea my @untainted = untaint_textarea(LIST); # LIST are strings to be untainted Passes through call to untaint_regex() using a RX suitable for text areas (printable characters plus carriage return and line feed). untaint_textfield my @untainted = untaint_textfield(LIST); # LIST are strings to be untainted Passes through call to untaint_regex() using a RX suitable for textfields (printable characters). validate_checkbox push @errors, validate_checkbox(NAME); # NAME is a CGI parameter name Performs checkbox checks on CGI parameter with name NAME. Skips checks if CGI parameter does not exist (e.g. empty or fresh hit). Returns error strings if problems found. Calls Carp::confess() on error. validate_hidden push @errors, validate_hidden(NAME); # NAME is a CGI parameter name Performs hidden field checks on CGI parameter with name NAME. Skips checks if no CGI parameters exist (e.g. fresh hit). Returns error strings if problems found. Calls Carp::confess() on error. validate_parameter_present push @errors, validate_required_parameters(LIST); # LIST are CGI parameter names Checks that the CGI parameters with names in LIST are defined and have values. Skips checks if no CGI parameters exist (e.g. fresh hit). Returns list of error strings if problems found. Calls Carp::confess() on error. validate_password_field push @errors, validate_password_field(NAME); # NAME is a CGI parameter name Performs password field checks on CGI parameter with name NAME. Skips checks if CGI parameter does not exist (e.g. empty or fresh hit). Returns error strings if problems found. Calls Carp::confess() on error. validate_textarea push @error, validate_textarea(NAME); # NAME is a CGI parameter name Performs textarea checks on CGI parameter with name NAME. Skips checks if parameter does not exist (e.g. empty or fresh hit). Returns error strings if problems found. Calls Carp::confess() on error. validate_textfield push @errors, validate_textfield(NAME); # NAME is a CGI parameter name Performs textfield checks on CGI parameter with name NAME. Skips checks if parameter does not exist (e.g. empty or fresh hit). and returns error strings if problems found. Calls Carp::confess() on error. EXPORT None by default. All of the subroutines may be imported by using the ':all' tag: use Dpchrist::CGI qw( :all ); See 'perldoc Export' for everything in between. INSTALLATION Old school: perl Makefile.PL make make test make install Minimal: cpan Dpchrist::CGI Complete: cpan Bundle::Dpchrist DEPENDENCIES See Makefile.PL in source distribution root directory. SEE ALSO CGI.pm AUTHOR David Paul Christensen dpchrist@holgerdanske.com COPYRIGHT AND LICENSE Copyright (C) 2010 by David Paul Christensen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.