On Apache
Under GNU General Public License
2012-05-21 23:19 @38.107.179.237 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
Lite(3pm) User Contributed Perl Documentation Lite(3pm)
NAME
CGI::Lite - 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.\n";
$cgi->close_all_files;
$cgi->add_mime_type ('application/mac-binhex40');
$status = $cgi->remove_mime_type ('application/mac-binhex40');
@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); # ***use is discouraged***
DESCRIPTION
You can use this module to decode form and query information, 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 environment variable REQUEST_METHOD to determine the manner 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 manner.
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-disposition" 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 information to translate end-of-line (EOL) characters for uploaded
files (see the add_mime_type and remove_mime_type methods) so that they display
properly on that platform.
You can specify either (case insensitive):
Unix EOL: \012 = \n
Windows, Windows95, DOS, NT, PC EOL: \015\012 = \r\n
Mac or Macintosh EOL: \015 = \r
"Unix" is the default.
set_directory
Used to set the directory where the uploaded files will be stored (only applies to the
multipart/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 directory 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 example, 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 completely 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 versions.
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 delimited by
the null character ("\0"). 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. The use of this
function is strongly discouraged. See http://use.perl.org/~cbrooks/journal/10542 and
http://msgs.securepoint.com/cgi-bin/get/bugtraq0302/94.html for an advisory by Ronald
F. Guilmette. Ronald's patch to make this function more safe is applied, but as has
been pointed out on the bugtraq mailing list, it is still much better to run no
external shell at all when executing commands. Please read the advisory and the WWW
security FAQ.
Return Value
Escaped string.
SEE ALSO
If you're looking for more comprehensive CGI modules, you can either use the CGI::*
modules or CGI.pm. Both are maintained by Dr. Lincoln Stein (lstein AT genome.edu) and
can be found at your local CPAN mirror and at his Web site:
http://www-genome.wi.mit.edu/WWW/tools/scripting
MAINTAINER
Maintenance of this module has now been taken over by Smylers <smylers AT cpan.org>.
ACKNOWLEDGMENTS
The author thanks the following for finding bugs and offering suggestions:
Eric D. Friedman (friedman AT uci.edu)
Thomas Winzig (tsw AT pvo.com)
Len Charest (len AT cogent.net)
Achim Bohnet (ach AT rosat.de)
John E. Townsend (John.E.Townsend AT BST.com)
Andrew McRae (mcrae AT internet.com)
Dennis Grant (dg50 AT chrysler.com)
Scott Neufeld (scott.neufeld AT mis.com)
Raul Almquist (imrs AT ShadowMAC.org)
and many others!
COPYRIGHT INFORMATION
Copyright (c) 1995, 1996, 1997 by Shishir Gundavaram
All Rights Reserved
Permission to use, copy, and distribute is hereby granted,
providing that the above copyright notice and this permission
appear in all copies and in supporting documentation.
perl v5.10.0 2003-08-19 Lite(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-21 23:19 @38.107.179.237 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)