NAME Dpchrist::CGI - utility subroutines for CGI scripts DESCRIPTION This documentation describes module revision $Revision: 1.50 $. 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_field(). $RX_PASSTHROUGH $RX_PASSTHROUGH => qr/^(.*)$/; Pass-through regular expression for testing. $RX_UNTAINT_CHECKBOX $RX_UNTAINT_CHECKBOX = qr/^(on)$/; Regular expression used for untainting checkbox parameter values. $RX_UNTAINT_PASSWORD_FIELD $RX_UNTAINT_PASSWORD_FIELD = qr/^([\PC]*)$/; Regular expression used for untainting password field parameter values. $RX_UNTAINT_PATH $RX_UNTAINT_PATH = qr/^([^\x00]*)$/; Regular expression used for untainting paths. $RX_UNTAINT_RADIO_GROUP $RX_UNTAINT_RADIO_GROUP = qr/^([\PC]*)$/; Regular expression used for untainting radio group parameter values. $RX_UNTAINT_TEXTAREA $RX_UNTAINT_TEXTAREA = qr/^([\PC\n\r]*)$/; Regular expression used for untainting textarea parameter values. $RX_UNTAINT_TEXTFIELD $RX_UNTAINT_TEXTFIELD = qr/^([\PC]*)$/; Regular expression used for untainting textfield parameter values. %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. 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 zero or more non-breaking space HTML character entities. Call without arguments returns one non-breaking space. 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_password_field my @untainted = untaint_password_field(LIST); # LIST are strings to be untainted Passes through call to untaint_regex() using a RX suitable for password fields (printable characters). 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_radio_group my @untainted = untaint_radio_group(LIST); # LIST are strings to be untainted Passes through call to untaint_regex() using a RX suitable for radio groups (printable characters). 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 returns list of first captured substrings for each LIST item. In scalar context, process first LIST item and returns 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 If CGI parameter NAME has a defined value, verifies that its value matches its untainted value. Returns list of error messages, if any. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_hidden push @errors, validate_hidden(NAME); # NAME is a CGI parameter name If CGI parameter NAME has a defined value, looks for corresponding checksum CGI parameter and verifies checksum. Returns list of error messages, if any. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_parameter_present push @errors, validate_required_parameters(LIST); # LIST are CGI parameter names Verifies that CGI parameters named in LIST have defined values. Returns list of error messages, if any. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_password_field push @errors, validate_password_field(NAME); # NAME is a CGI parameter name If CGI parameter NAME has a defined value, verifies that length does not exceed $PASSWORD_FIELD_ARGS{-maxlength} and that value matches its untainted value. Returns list of error messages, if any. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_radio_group push @errors, validate_radio_group(NAME, VALUES); # NAME is a CGI parameter nameo # VALUES is list (or arrayref) of allowed values If CGI parameter NAME has a defined value, verifies that value matches untainted value and that value is one of listed VALUES. Returns list of error messages, if any. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_textarea push @error, validate_textarea(NAME); # NAME is a CGI parameter name If CGI parameter NAME has a defined value, verifies that length does not exceed $TEXTAREA_ARGS{-maxlength} and that value matches its untainted value. Returns list of error messages, if any. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_textfield push @errors, validate_textfield(NAME); # NAME is a CGI parameter name If CGI parameter NAME has a defined value, verifies that length does not exceed $TEXTFIELD_ARGS{-maxlength} and that value matches its untainted value. Returns list of error messages, if any. Returns empty list if no CGI parameters exist (e.g. fresh hit). 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 ); INSTALLATION Old school: $ perl Makefile.PL $ make $ make test $ make install Minimal: $ cpan Dpchrist::CGI Complete: $ cpan Bundle::Dpchrist PREREQUISITES See Makefile.PL in the 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.