CGI::Lite - Process and decode WWW forms and cookies

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.

MAINTAINER

Maintenance of this module has now been taken over by Smylers <smylers@cpan.org>.

ACKNOWLEDGMENTS

The author thanks 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.

CGI::Lite - Process and decode WWW forms and cookies