CGI::Minimal(3)

NAME
CGI::Minimal - A lightweight CGI form processing pacakge

SYNOPSIS
 use CGI::Minimal;

 my $cgi = CGI::Minimal->new;
 if ($cgi->truncated) {
    &scream_about_bad_form;
    exit;
 }
 my ($form_field_value) = $cgi->param('some_field_name');

DESCRIPTION
Provides a micro-weight alternative to the CPAN CGI.pm module

Rather than attempt to address every possible need of a CGI programmer, it provides the _minimum_ functions needed for CGI such as form decoding (including file upload forms), URL encoding and decoding, HTTP usable date generation (RFC1123 compliant dates) and _basic_ escaping and unescaping of HTMLized text.

The form decoding interface is somewhat compatible with the CGI.pm module. No provision is made for generating HTTP or HTML on your behalf - you are expected to be conversant with how to put together any HTML or HTTP you need.

CHANGES
 1.06 10 April 2000 - 'Unfixed' use of 'quotemeta' for multipart
                       boundaries. 'split' is doing the 'wrong thing'
                       according to the specs...

 1.05 03 April 2000 - Fixed breakage in 'param;' from 1.04 changes

 1.04 03 April 2000 - Added capability to set params via the param() method
                      like 'CGI.pm' plus general code cleanup

 1.03 02 March 2000 - 'mod_perl' compatibility added

 1.02 09 June 1999  - Initial public release.

METHODS

new;
    Creates a new instance of the CGI::Minimal object and decodes any type of form (GET/POST). Only one 'true' object is generated - all subsequent calls return an alias of the one object (a 'Singleton' pattern).

    Example:

     use CGI::Minimal;

     my $cgi = CGI::Minimal->new;

param([$fieldname]);
    Called as "$cgi->param();" it returns the list of all defined form fields in the same order they appear in the data from the user agent.

    Called as "$cgi->param($fieldname);" it returns the value (or array of values for multiple occurances of the same field name) assigned to that $fieldname. If there is more than one value, the values are returned in the same order they appeared in the data from user agent.

    Examples:

      my (@form_fields) = $cgi->param;

      my (@multi_pick_field) = $cgi->param('pick_field_name');

      my ($form_field_value) = $cgi->param('some_field_name');

    You can also use the param method to set param values to new values. These values will be returned by any invokation of a CGI::Minimal object as if they had been found in the original passed data.

    Examples:

        $cgi->param( 'name' => 'Joe Shmoe' );

        $cgi->param({ 'name' => 'Joe Shmoe', 'birth_date' => '06/25/1966' });

        $cgi->param({ 'pick_list' => ['01','05','07'] });

param_mime([$fieldname]);
    Called as "$cgi->param_mime();" it returns the list of all defined form fields in the same order they appear in the data from the user agent.

    Called as "$cgi->param_mime($fieldname);" it returns the MIME type (or array of MIME types for multiple occurances of the same field name) assigned to that $fieldname. If there is more than one value, the values are returned in the same order they appeared in the data from user agent.

    This is only meaningful when doing Form Based File Uploads and should probably not be trusted even then since it depends on the _browser_ correctly identifying what it is sending.

param_filename([$fieldname]);
    Called as "$cgi->param_filename();" it returns the list of all defined form fields in the same order they appear in the data from the user agent.

    Called as "$cgi->param_filename($fieldname);" it returns the file name (or array of file names for multiple occurances of the same field name) assigned to that $fieldname. If there is more than one value, the values are returned in the same order they appeared in the data from user agent.

    This is only meaningful when doing Form Based File Uploads.

date_rfc1123($time);
    Takes a unix time tick value and returns a RFC1123 compliant date as a formatted text string suitable for direct use in Expires, Last-Modified or other HTTP headers (with the exception of 'Set-Cookie', which requires a different format not generated here. See 'CGI::Cookie' for cookie generation).

    Example:

     print "Expires: ",$cgi->date_rfc1123(time + 3600),"\015\012";

calling_parms_table;
    Returns a formatted HTML table containing all the form and environment variables for debugging purposes

    Example:

      print $cgi->calling_parms_table;

url_encode($string);
    Returns URL encoding of input string (URL unsafe codes are escaped to %xx form)

    Example:

     my $url_encoded_string = $cgi->url_encode($string);

url_decode($string);
    Returns URL *decoding* of input string (%xx substitutions are decoded to their actual values).

    Example:

     my $url_decoded_string = $cgi->url_decode($string);

htmlize($string);
    Returns HTML 'safe' encoding of input string. Replaces &,>,< and " with their named entity codes (&amp, &gt; &lt; and &quot;)

    Example:

     my $html_escaped_string = $cgi->htmlize($string);

dehtmlize($string);
    Undoes basic HTML encoding of input string. Replaces &amp;, &gt;, &lt; and &quot; named entity codes with their actual values. NOT a general purpose entity decoder.

truncated;
    Returns '1' if the read form was shorter than the Content-Length that was specified by the submitting user agent (ie the data from a form uploaded by a web browser was cut off before all the data was received).

    Returns '0' if the form was NOT truncated.

    Example:

      use CGI::Minimal;

      my $cgi = CGI::Minimal->new;
      if ($cgi->truncated) {
        &bad_form_upload;
      } else {
        &good_form_upload;
      }

    'truncated' will also return '1' if the form length received would have exceeded the set 'max_read_length'.

CGI::Minimal::max_read_size($size);
    Sets the maximum number of bytes/octets that the CGI decoder will accept. By default, 1000000 bytes/octets. This must be called *BEFORE* calling 'new' for the first time for it to actually affect form decoding.

    Example:

      use CGI::Minimal;

      CGI::Minimal::max_read_size(1000000);
      my $cgi = CGI::Minimal->new;

BUGS
None known.

TODO
Who knows?

AUTHORS
Benjamin Franz <snowhare@nihongo.org>

VERSION
Version 1.06 April 2000

COPYRIGHT
Copyright (c) Benjamin Franz 1999,2000. All rights reserved.

 This program is free software; you can redistribute it
 and/or modify it under the same terms as Perl itself.

SEE ALSO
CGI