CGI::Lite - Process and decode WWW forms and cookies
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***
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.
Here are the methods you can use to process your forms and cookies:
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).
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> }
Decodes and parses cookies passed by the browser. This method works in much the same manner as parse_form_data.
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.
0 Success 1 Failure
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.
The error message.
You can use this method to return errors to the browser and exit.
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.
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.
0 Failure 1 Success
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.
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');
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');
Returns the list, either as a reference or an actual list, of the MIME types for which EOL translation is performed.
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.
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).
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; }
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.
The buffer size.
Returns either a reference to an array or an array itself consisting of the form fields/cookies in the order they were parsed.
Ordered keys.
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.
Deprecated as of v1.8, see print_data.
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.
The modified string.
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!
Array consisting of the multiple values.
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?
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.
Escaped string.
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.
URL encoded string.
You can use this method to URL decode a string.
URL decoded string.
This method checks for the existence of dangerous meta-characters.
0 Safe 1 Dangerous
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.
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@genome.wi.mit.edu) and can be found at your local CPAN mirror and at his Web site:
http://www-genome.wi.mit.edu/WWW/tools/scripting
Maintenance of this module has now been taken over by Smylers <smylers@cpan.org>.
The author thanks the following for finding bugs and offering suggestions:
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.
To install CGI::Lite, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Lite
CPAN shell
perl -MCPAN -e shell install CGI::Lite
For more information on module installation, please visit the detailed CPAN module installation guide.