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.\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); 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_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. *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@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* 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 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.