NAME Dpchrist::CGI - utility subroutines for CGI scripts DESCRIPTION This documentation describes module revision $Revision: 1.58 $. This is alpha test level software and may change or disappear at any time. GLOBALS %CHECKBOX_ARGS %CHECKBOX_ARGS = ( -value => 'on', ); Default argments used by gen_checkbox(). $CHECKSUM_LENGTH $CHECKSUM_LENGTH = 32; Length of checksum strings. $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/^(.*)$/; Regular expression for testing untaint_*() subroutines. Passes all characters. $RX_UNTAINT_CHECKBOX $RX_UNTAINT_CHECKBOX = qr/^([\PC]*)$/; Regular expression for untainting checkbox parameter values. Passes printable characters. $RX_UNTAINT_CHECKSUM $RX_UNTAINT_CHECKSUM = qr/^[0-9a-f]{32}$/; Regular expression for untainting checksum parameter values. $RX_UNTAINT_PASSWORD_FIELD $RX_UNTAINT_PASSWORD_FIELD = qr/^([\PC]*)$/; Regular expression used for untainting password field parameter values. Passes printable characters. $RX_UNTAINT_PATH $RX_UNTAINT_PATH = qr/^([^\x00]*)$/; Regular expression used for untainting paths. Passes all characters except NUL. $RX_UNTAINT_POPUP $RX_UNTAINT_POPUP = qr/^([\PC]*)$/; Regular expression used for untainting popup parameter values. Passes printable characters. $RX_UNTAINT_RADIO_GROUP $RX_UNTAINT_RADIO_GROUP = qr/^([\PC]*)$/; Regular expression used for untainting radio group parameter values. Passes printable characters. $RX_UNTAINT_TEXTAREA $RX_UNTAINT_TEXTAREA = qr/^([\PC\r\n]*)$/; Regular expression used for untainting textarea parameter values. Passes printable characters plus carriage return and linefeed. $RX_UNTAINT_TEXTFIELD $RX_UNTAINT_TEXTFIELD = qr/^([\PC]*)$/; Regular expression used for untainting textfield parameter values. Passes printable characters. %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 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 md5_hex() checksum value given by $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_regexp() using $RX_UNTAINT_CHECKBOX. untaint_hidden my @untainted = untaint_hidden(LIST); # LIST are strings to be untainted Passes through call to _untaint_regexp() using $RX_PASSTHROUGH. untaint_password_field my @untainted = untaint_password_field(LIST); # LIST are strings to be untainted Passes through call to _untaint_regexp() using $RX_UNTAINT_PASSWORD_FIELD. untaint_path my @untainted = untaint_path(LIST); # LIST are strings to be untainted Passes through call to _untaint_regexp() using $RX_UNTAINT_PATH. untaint_popup my @untainted = untaint_popup(LIST); # LIST are strings to be untainted Passes through call to _untaint_regexp() using $RX_UNTAINT_POPUP. untaint_radio_group my @untainted = untaint_radio_group(LIST); # LIST are strings to be untainted Passes through call to _untaint_regexp() using $RX_UNTAINT_RADIO_GROUP. untaint_textarea my @untainted = untaint_textarea(LIST); # LIST are strings to be untainted Passes through call to _untaint_regexp() using $RX_UNTAINT_TEXTAREA. untaint_textfield my @untainted = untaint_textfield(LIST); # LIST are strings to be untainted Passes through call to _untaint_regexp() using $RX_UNTAINT_TEXTFIELD. validate_checkbox my $v = validate_checkbox(RA_ERRORS, NAME); # RA_ERRORS is reference to array of error messages # NAME is a CGI parameter name Untaints, validates, and returns value of checkbox CGI parameter NAME -- must have single value, must contain valid characters (calls untaint_checkbox()), and must contain valid value (compares to $CHECKBOX_ARGS{-value}). If any problems found, pushes error messages onto @RA_ERRORS and returns undef. Per CGI.pm, note that return value will also be undef when checkbox is unchecked. Calls Carp::confess() on error. validate_hidden my $v = validate_hidden(RA_ERRORS, NAME); # RA_ERRORS is reference to array of error messages # NAME is a CGI parameter name Untaints, validates, and returns value of hidden CGI parameter NAME -- hidden parameter(s) required if any parameters exist, checksum parameter is required, checksum parameter must validate as textual field, hidden parameter(s) must contain valid characters, and hidden parameter(s) checksum must match checksum parameter. If any problems found, pushes error messages onto @RA_ERRORS and returns undef. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_parameter_is_required my $ok = validate_parameter_is_required(RA_ERRORS, LIST); # RA_ERRORS is reference to array of error messages # LIST are CGI parameter names Verifies that CGI parameters named in LIST exist, including the undefined value. If any problems found, pushes error messages onto @RA_ERRORS and returns undef. Returns empty list if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_password_field my $v = validate_password_field(RA_ERRORS, NAME); # RA_ERRORS is reference to array of error messages # NAME is a CGI parameter name Untaints, validates, and returns value of password field CGI parameter NAME -- must have single value, must contain valid characters (calls untaint_password_field()), and length must be n characters or less (compares to $PASSWORD_FIELD_ARGS{-maxlength}). If any problems found, pushes error messages onto @RA_ERRORS and returns undef. Calls Carp::confess() on error. validate_radio_group my $v = validate_radio_group(RA_ERRORS, NAME, RA_VALUES); # RA_ERRORS is reference to array of error messages # NAME is a CGI parameter nameo # RA_VALUES is reference to array of allowed values Untaints, validates, and returns radio group CGI parameter NAME -- is required, must have single value, must contain valid characters (calls untaint_radio_group()), and must contain valid value (be in @RA_VALUES). If any problems are found, pushes error messages onto @RA_ERRORS and returns undef. Returns undef if no CGI parameters exist (e.g. fresh hit). Calls Carp::confess() on error. validate_textarea my $v = validate_textarea(RA_ERRORS, NAME); # RA_ERRORS is reference to array of error messages # NAME is a CGI parameter name Untaints, validates, and returns value of textarea CGI parameter NAME -- must have single value, must contain valid characters (calls untaint_textarea()), and length must be n characters or less (compares to $TEXTAREA_ARGS{-maxlength}). If any problems found, pushes error messages onto @RA_ERRORS and returns undef. Calls Carp::confess() on error. validate_textfield my $v = validate_textfield(RA_ERRORS, NAME); # RA_ERRORS is reference to array of error messages # NAME is a CGI parameter name Untaints, validates, and returns value of textfield CGI parameter NAME -- must have single value, must contain valid characters (calls untaint_textfield()), and length must be n characters or less (compares to $TEXTFIELD_ARGS{-maxlength}). If any problems found, pushes error messages onto @RA_ERRORS and returns undef. 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.