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.\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_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.

    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.