view release on metacpan or  search on metacpan

lib/CGI/Minimal.pod  view on Meta::CPAN

=encoding UTF8

=head1 NAME

CGI::Minimal - A lightweight CGI form processing package

=head1 SYNOPSIS

 # use CGI::Minimal qw(:no_subprocess_env);
 # use CGI::Minimal qw(:preload);
 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');

=head1 DESCRIPTION

Provides a micro-weight alternative to the 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 I<basic> escaping and unescaping of HTMLized text.

The ':preload' use time option is used to force all sub-component
modules to load at compile time.  It is not required for
operation. It is solely a performance optimization for particular
configurations. When used, it preloads the 'dehtmlize',' param_mime',
'param_filename', 'date_rfc1123', 'url_decode', 'calling_parms_table'
and parameter setting supporting code. Those code sections
are normally loaded automatically the first time they are needed.

The ':no_subprocess_env' use time option is used under ModPerl2
to suppress populating the %ENV hash with the usual CGI environmental
variables. This is primarily a performance enhancement for some
configurations.

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>

Alternatively, you can set the environment variable REQUEST_METHOD to 'GET'
and set the environment variable QUERY_STRING to pass your CGI parameters.

Example:

bash> REQUEST_METHOD=GET QUERY_STRING='a=b' ./myscript

=head2 Performance Hints

If you are using this module as part of a conventional standalone CGI
specifically to get a speedup over using CGI.pm, don't 'use warnings', 'use vars'
or 'use Carp' in your final production code.

The problem with 'use vars' or 'use warnings' is that (unless you are using
Perl 5.8.6 or later) they add on the order of 40 kilobytes of code to your
load and you B<will> feel the slowdown. Half of that is from the Carp module (which
is used by both the 'vars' and 'warnings' modules.)

lib/CGI/Minimal.pod  view on Meta::CPAN

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

Example:

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

=back

=cut

=over 4

=item url_decode($string);

Returns URL *decoding* of input string (%xx and %uxxxx substitutions
are decoded to their actual values).

Example:

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

=back

=cut

=over 4

=item 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);

=back

=cut

=over 4

=item 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.

=back

=cut

=over 4

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

=back

=cut

=head1 STATIC METHODS

=cut

######################################################################

=over 4

=item 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;

=back

=cut

=over 4

=item CGI::Minimal::allow_hybrid_post_get(0|1);

The HTTP standard specifies that POST parameters are passed
in the body of the HTTP request while GET parameters are
passed as part of the URL. The two B<are not> supposed
to be mixed, and the semantics of doing so are undefined,
but many people have done so anyway.

By default, CGI::Minimal does not mix the two.

If you wish to do so (with a resulting speed penalty for processing
'POST' forms since it has to B<also> process the GET query string)
you can do so by setting allow hybrid post/get via the
allow_hybrid_post_get static method before calling
'new' for the first time:

Example:

  use CGI::Minimal;

  CGI::Minimal::allow_hybrid_post_get(1);
  my $cgi = CGI::Minimal->new;