NAME
    Dpchrist::CGI - utility subroutines for CGI scripts

DESCRIPTION
    This documentation describes module revision $Revision: 1.69 $.

    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.

