lite(3)

NAME

CGI::Lite - Perl module to process and decode WWW forms
and cookies.

SYNOPSIS

use CGI::Lite;
$cgi = new CGI::Lite;
$cgi->set_platform ($platform);
    where $platform can be one of (case insensitive):
    Unix, Windows, Windows95, DOS, NT, PC, Mac or Macintosh
$cgi->set_file_type ('handle' or 'file');
$cgi->add_timestamp (0, 1 or 2);
    where 0 = no timestamp
          1 = timestamp all files (default)
          2 = timestamp only if file exists
$cgi->filter_filename (subroutine);
$size = $cgi->set_buffer_size ($some_buffer_size);
$status = $cgi->set_directory ('/some/dir');
$cgi->set_directory  ('/some/dir')  ||  die "Directory
doesn't exist.0;
$cgi->close_all_files;
$cgi->add_mime_type ('application/mac-binhex40');
$status  =  $cgi->remove_mime_type  ('application/macbinhex40');
@list = $cgi->get_mime_types;
$form = $cgi->parse_form_data;
%form = $cgi->parse_form_data;
or
$form   =   $cgi->parse_form_data  ('GET',  'HEAD'  or
'POST');
$cookies = $cgi->parse_cookies;
%cookies = $cgi->parse_cookies;
$status  = $cgi->is_error;
$message = $cgi->get_error_message;
$cgi->return_error ('error 1', 'error 2', ...);
$keys = $cgi->get_ordered_keys;
@keys = $cgi->get_ordered_keys;
$cgi->print_data;
$cgi->print_form_data;   (deprecated as of v1.8)
$cgi->print_cookie_data; (deprecated as of v1.8)
$new_string = $cgi->wrap_textarea ($string, $length);
@all_values = $cgi->get_multiple_values ($reference);
$cgi->create_variables (form);
$cgi->create_variables ($form);
$escaped_string = browser_escape ($string);
$encoded_string = url_encode ($string);
$decoded_string = url_decode ($string);
$status = is_dangerous ($string);
$safe_string = escape_dangerous_chars ($string);

DESCRIPTION

You can use this module to decode form and query informa
tion, including file uploads, as well as cookies in a very
simple manner; you need not concern yourself with the
actual details behind the decoding process.

METHODS

Here are the methods you can use to process your forms and
cookies:

parse_form_data: This will handle the following types of requests: GET,
HEAD and POST. By default, CGI::Lite uses the envi
ronment variable REQUEST_METHOD to determine the man
ner in which the query/form information should be
decoded. However, as of v1.8, you are allowed to pass
a valid request method to this function to force
CGI::Lite to decode the information in a specific man
ner.; For multipart/form-data, uploaded files are stored in
the user selected directory (see set_directory). If timestamp mode is on (see add_timestamp), the files are named in the following format:

timestamp__filename; where the filename is specified in the "Content-dispo
sition" header. NOTE:, the browser URL encodes the
name of the file. This module makes no effort to
decode the information for security reasons. However,
you can do so by creating a subroutine and then using
the filter_filename method.; Return Value; Returns either a hash or a reference to the hash,
which contains all of the key/value pairs. For fields
that contain file information, the value contains
either the path to the file, or the filehandle (see
the set_file_type method).
parse_new_form_data: As for parse_form_data, but clears the CGI object
state before processing the request. This is useful in
persistant application (e.g. FCGI), where the CGI
object is reused for multiple requests. e.g.

$CGI = new CGI::Lite;
while (FCGI::accept > 0)
{
$Query = $CGI->parse_new_form_data();
<process query>

}
parse_cookies: Decodes and parses cookies passed by the browser. This
method works in much the same manner as
parse_form_data.
is_error: As of v1.8, errors in parsing are handled differently.
You can use this method to check for any potential
errors after you've called either parse_form_data or parse_cookies.; Return Value

0 Success
1 Failure
get_error_message: If an error occurs when parsing form/query information
or cookies, you can use this method to retrieve the
error message. Remember, you can check for errors by
calling the is_error method.; Return Value; The error message.
return_error: You can use this method to return errors to the
browser and exit.
set_platform: You can use this method to set the platform on which
your Web server is running. CGI::Lite uses this infor
mation to translate end-of-line (EOL) characters for
uploaded files (see the add_mime_type and remove_mime_type methods) so that they display prop erly on that platform.; You can specify either (case insensitive):

Unix EOL: 12

=
Windows, Windows95, DOS, NT, PC EOL: 15 12

=
Mac or Macintosh EOL: 15

=; "Unix" is the default.
set_directory: Used to set the directory where the uploaded files
will be stored (only applies to the multi_
part/form-data encoding scheme).; This function should be called before you call
parse_form_data, or else the directory defaults to "/tmp". If the application cannot write to the direc
tory for whatever reason, an error status is returned.; Return Value

0 Failure
1 Success
close_all_files: All uploaded files that are opened as a result of
calling set_file_type with the "handle" argument can be closed in one shot by calling this method.
add_mime_type: By default, EOL characters are translated for all
uploaded files with specific MIME types (i.e
text/plain, text/html, etc.). You can use this method
to add to the list of MIME types. For example, if you
want CGI::Lite to translate EOL characters for
uploaded files of application/mac-binhex40, then you would do this:

$cgi->add_mime_type ('application/mac-binhex40');
remove_mime_type: This method is the converse of add_mime_type. It allows you to remove a particular MIME type. For exam
ple, if you do not want CGI::Lite to translate EOL
characters for uploaded files of text/html, then you would do this:

$cgi->remove_mime_type ('text/html');; Return Value

0 Failure
1 Success
get_mime_types: Returns the list, either as a reference or an actual
list, of the MIME types for which EOL translation is
performed.
set_file_type: The names of uploaded files are returned by default,
when you call the parse_form_data method. But, if pass the string "handle" to this method, the handles to the files are returned. However, the name of the
handle corresponds to the filename.; This function should be called before you call
parse_form_data, or else it will not work.
add_timestamp: By default, a timestamp is added to the front of
uploaded files. However, you have the option of com
pletely turning off timestamp mode (value 0), or
adding a timestamp only for existing files (value 2).
filter_filename: You can use this method to change the manner in which
uploaded files are named. For example, if you want
uploaded filenames to be all upper case, you can use
the following code:

$cgi->filter_filename (make_uppercase);
$cgi->parse_form_data;

.
.
.

sub make_uppercase
{
my $file = shift;

$file =~ tr/a-z/A-Z/;
return $file;

}
set_buffer_size: This method allows you to set the buffer size when
dealing with multipart form data. However, the actual
buffer size that the algorithm uses can be up to 3x
the value you specify. This ensures that boundary
strings are not "split" between multiple reads. So,
take this into consideration when setting the buffer
size.; You cannot set a buffer size below 256 bytes and above
the total amount of multipart form data. The default
value is 1024 bytes.; Return Value; The buffer size.
get_ordered_keys: Returns either a reference to an array or an array
itself consisting of the form fields/cookies in the
order they were parsed.; Return Value; Ordered keys.
print_data: Displays all the key/value pairs (either form data or
cookie information) in a ordered fashion. The methods
print_form_data and print_cookie_data are deprecated as of version v1.8, and will be removed in future ver
sions.
print_form_data: Deprecated as of v1.8, see print_data.
print_cookie_data (deprecated as of v1.8): Deprecated as of v1.8, see print_data.
wrap_textarea: You can use this function to "wrap" a long string into
one that is separated by a combination of carriage
return and newline (see set_platform) at fixed lengths. The two arguments that you need to pass to
this method are the string and the length at which you
want the line separator added.; Return Value; The modified string.
get_multiple_values: One of the major changes to this module as of v1.7 is
that multiple values for a single key are returned as
an reference to an array, and not as a string delim
ited by the null character (" "). You can use this
function to return the actual array. And if you pass a
scalar value to this method, it will simply return
that value.; There was no way I could make this backward compatible
with versions older than 1.7. I apologize!; Return Value; Array consisting of the multiple values.
create_variables: Sometimes, it is convenient to have scalar variables
that represent the various keys in a hash. You can use
this method to do just that. Say you have a hash like
the following:

%form = ('name' => 'shishir gundavaram',
'sport' => 'track and field',
'events' => '100m');
If you call this method in the following manner:: $cgi->create_variables (hash);
it will create three scalar variables: $name, $sport and $events. Convenient, huh?
browser_escape: Certain characters have special significance to the
browser. These characters include: "<" and ">". If you
want to display these "special" characters, you need
to escape them using the following notation:

&#ascii;; This method does just that.; Return Value; Escaped string.
url_encode: This method will URL encode a string that you pass it.
You can use this to encode any data that you wish to
pass as a query string to a CGI application.; Return Value; URL encoded string.
url_decode: You can use this method to URL decode a string.; Return Value; URL decoded string.
is_dangerous: This method checks for the existence of dangerous
meta-characters.; Return Value

0 Safe
1 Dangerous
escape_dangerous_chars: You can use this method to "escape" any dangerous
meta-characters.; Return Value; Escaped string.

ACKNOWLEDGMENTS

I'd like to thank the following for finding bugs and
offering suggestions:

Eric D. Friedman (friedman@uci.edu)
Thomas Winzig (tsw@pvo.com)
Len Charest (len@cogent.net)
Achim Bohnet (ach@rosat.mpe-garching.mpg.de)
John E. Townsend (John.E.Townsend@BST.BLS.com)
Andrew McRae (mcrae@internet.com)
Dennis Grant (dg50@chrysler.com)
Scott Neufeld (scott.neufeld@mis.ussurg.com)
Raul Almquist (imrs@ShadowMAC.org)
and many others!

COPYRIGHT INFORMATION

Permission to use, copy, and distribute is hereby
granted, providing that the above copyright notice and this per
mission appear in all copies and in supporting documentation.

docs.sk

comprehensive documentation repository

Most Viewed