/ 
CGI-Minimal-1.13
River stage one • 3 direct dependents • 5 total dependents
/ CGI::Minimal

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.

The parser accepts either '&' or ';' as CGI form field seperators.

IOW

a=b;c=d

a=b&c=d

both will decode as a=b and c=d

The module supports command line testing of scripts by letting you type a GET style argument followed by pressing the 'enter/return' key when the module is called to decode a form when running a script from the shell.

Example:

bash> ./myscript
a=b&b=d<return>

CHANGES

1.13 28 Sep 2004 - Removed support for Module::Build from module install.

1.12 25 Sep 2004 - Tweaked the default form parser to accept ';' as a field seperator
                   in addition to '&'. Change suggested by Peter Karman.
                   Eliminated the explicit application/sgml-form-urlencoded support
                   as redundant (it still works, it is just not explicitly different
                   than application/x-www-form-urlencoded support anymore).

                   Adjusted the multipart form parser to be more robust against
                   malformed MIME boundaries and the build tests to work around a
                   bug in Perl 5.8.0 UTF8ness and split.

                   Added documentation of command line script testing behavior.

                   Tightened up the code to reduce size (went from 14.9K to 11K).

                   Removed the 'sgml_safe_mode' redirect code since there
                   was no exposed interface to it anyway.

                   Squashed a bug where the global buffer might fail to initialize
                   correctly for 0 byte POST forms (only impacted  use of the 'raw'
                   method for POST use).

                   Added regression test for form truncation

                   Added LICENSE section to documentation

                   Added Module::Build installation support

1.11 28 Sep 2003 - Tweaked test script to avoid warnings about
                   opening STDIN filehandle for writing. No functional
                   changes.

1.10 04 Apr 2003 - Added 'binmode STDIN' on module load to correct for
                   windows defaulting to 7-bit filehandles. Fixed problem where
                   split would fail on unusual MIME boundary strings.
                   Problems noticed by Markus Wichitill.

                   Deferred loading of 'Carp' unless actually needed.

                   Small code cleanups. Removed big disclaimer from
                   .pm and moved in pod to 'DISCLAIMERS' section

                   Added tests


1.09 19 Mar 2002 - Exposed 'reset_globals' static method for support
                   of non-mod_perl persistent perl execution environments.

1.08 26 Jul 2001 - Added 'raw' method for obtaining a dump of the raw input buffer data
                   without any parsing. Moved documentation into seperate POD file.

1.07 01 Dec 2000 - Added capability of taking a GET style parameter string
                        via STDIN if running at the command line.

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

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

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

1.03 02 Mar 2000 - 'mod_perl' compatibility added

1.02 09 Jun 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'] });

Starting with the 1.12 version, CGI::Minimal accepts the ';' character as a form field seperator in addition to the '&'.

IOW: a=b;c=d will decode as well as a=b&c=d in form submissions. This is to provide SGML/XML compatibility for those needing it. Since ';' has always been escaped to %3e by the url_encode method, this should only affect people who are already doing the wrong thing with their forms by not escaping their data correctly. This is also compatible with what the CGI.pm module does.

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.

raw;

Returns a copy of the raw form data. Returns 'undef' if the form has not been parsed yet.

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'.

STATIC METHODS

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;
CGI::Minimal::reset_globals;

Sets the CGI::Minimal object to it's initial state (the state it is in before calling 'new' for the first time in a CGI interaction)

This static method not needed if you are running CGI::Minimal either as a traditional CGI script or under mod_perl. In other persistent execution environments you need to call this static method _before_ calling ->new or the module will not 'forget' the data parameters passed from the last time it was executed.

Ex.:

use CGI::Minimal;

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

Note: This resets the the 'max_read_size' back to its default of 1_000_000 octets ('bytes'); so if you want to use a different size, you need to restore it after you do the 'reset_globals' call.

Ex.:

use CGI::Minimal;

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

BUGS

None known.

TODO

Add more regression tests.

AUTHOR

Benjamin Franz <snowhare@nihongo.org>

VERSION

Version 1.13 28 Sep 2004

COPYRIGHT

Copyright (c) Benjamin Franz 1999-2004. All rights reserved.

LICENSE

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

This means that you can, at your option, redistribute it and/or modify it under either the terms the GNU Public License (GPL) version 1 or later, or under the Perl Artistic License.

See http://dev.perl.org/licenses/

DISCLAIMER

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Use of this software in any way or in any form, source or binary, is not allowed in any country which prohibits disclaimers of any implied warranties of merchantability or fitness for a particular purpose or any disclaimers of a similar nature.

IN NO EVENT SHALL I BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION (INCLUDING, BUT NOT LIMITED TO, LOST PROFITS) EVEN IF I HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE

SEE ALSO

CGI