NAME Dpchrist::CGI - utility subroutines for CGI scripts DESCRIPTION This documentation describes module revision $Revision: 1.68 $. 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_SALT $CHECKSUM_SALT = join ' ', __PACKAGE__, __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_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]*)$/; Regular expression for untainting checksum parameter values. $RX_UNTAINT_HIDDEN $RX_UNTAINT_HIDDEN = qr/^([\PC\r\n]*)$/; Regular expression used for untainting hidden field parameter values. Passes printable characters plus carriage return and linefeed. $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. 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. test_a_checkbox push @html, test_a_checkbox(NAME, HOSTPORTPATH, RA_QUERY); # NAME the name of the checkbox parameter # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML elements for testing checkbox parameters. test_a_hidden push @html, test_a_hidden(NAME, RA_VALUES, HOSTPORTPATH, RA_QUERY); # NAME the name of the hidden parameter # RA_VALUES array containing known good value(s) # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML elements for testing hidden parameters. test_a_password_field push @html, test_a_password_field(NAME, HOSTPORTPATH, RA_QUERY); # NAME the name of the password_field parameter # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML elements for testing password_field parameters. test_a_popup push @html, test_a_popup( NAME, RA_CHOICES, HOSTPORTPATH, RA_QUERY ); # NAME the name of the popup parameter # RA_CHOICES reference to array of valid choices # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML elements for testing radio group parameters. test_a_radio_group push @html, test_a_radio_group( NAME, RA_CHOICES, HOSTPORTPATH, RA_QUERY ); # NAME the name of the radio_group parameter # RA_CHOICES reference to array of valid choices # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML elements for testing radio group parameters. test_a_required push @html, test_a_required( RA_NAMES, HOSTPORTPATH, RA_QUERY ); # RA_NAMES reference to array of required parameters # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML element for testing required parameters. test_a_textarea push @html, test_a_textarea(NAME, HOSTPORTPATH, RA_QUERY); # NAME the name of the textarea parameter # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML elements for testing textarea parameters. test_a_textfield push @html, test_a_textfield(NAME, HOSTPORTPATH, RA_QUERY); # NAME the name of the textfield parameter # HOSTPORTPATH the URL host, port, and/or path # RA_QUERY URL query name and value pairs Generates anchor HTML elements for testing textfield parameters. 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_UNTAINT_HIDDEN. 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_required my $ok = validate_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_popup my $v = validate_popup(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 popup CGI parameter NAME -- is required, must have single value, must contain valid characters (calls untaint_popup()), 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_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.