CGI Lite v1.62 - Perl 5.0 module to process and decode WWW form information


    use CGI_Lite;
    $form = new CGI_Lite ();
    $form->set_platform ("UNIX" or "PC" or "Macintosh");
    $form->set_file_type ("handle" or "file");
    $status = $form->set_directory ("/some/dir");
    $form->set_directory ("/some/dir") || die "Directory doesn't exist.\n";
    $reference_to_hash = $form->parse_form_data ();
    %hash = $form->parse_form_data ();
    $form->print_form_data ();


The module can be used to handle and decode WWW form information. Both GET and POST requests can be processed. In the case of POST requests, the information can be one of two possible MIME types:


This module is very light-weight, and can be thought of as an enhanced version of the old library for Perl 4.0 by Steven Brenner (

Form Creation

Here is an example of a simple form that uses the file attribute in the input statement to present the user with the capability to upload a file:

    <TITLE>CGI Lite Test</TITLE>
    <H1>CGI Lite Test</H1>
    <FORM ACTION="/cgi-bin/"

          What is your name? <INPUT TYPE="text" NAME="username">
          Select a file to send: <INPUT TYPE="file" NAME="input_file">
          <INPUT TYPE="submit" VALUE="Send the Multipart Form">
          <INPUT TYPE="reset"  VALUE="Clear the Information">

multipart/form-data MIME header

Here is what a multipart/form-data header looks like (as of Netscape 2.0b1):

    Content-disposition: form-data; name="full_name"
    Foo Bar
    Content-disposition: form-data; name="picture"; filename="/bar.gif"
    Content-type: image/gif
    ... GIF Data ...
    Content-disposition: form-data; name="readme"; filename="/bar.txt"
    ... Text Data ...


Here are the methods you can use to process your forms:

This will handle all types of requests: GET, HEAD and POST (for both encoding methods). For multipart/form-data, uploaded files are stored in the user selected directory (see set_directory). The files are named in the following format:

where the filename is specified in the ``Content-disposition'' header.

Return Value

Returns either a reference to the hash, or the hash itself, that 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).


This module cannot handle multiple files within one field. No need to worry, Netscape 2.0 does not support this anyway.

This function will set the end of line characters for uploaded text files so that they will display properly on the specified platform (the platform your HTTP server is running on).

You can specify either:

    UNIX                EOL: <LF>       
    PC                  EOL: <CR><LF>
    Macintosh           EOL: <CR>

By default, ``UNIX'' is assumed.

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

By default, the uploaded filename is stored in the hash that is returned by the parse_form_data method. However, if you pass the string ``handle'' to this subroutine, the filehandles to the newly created files are returned.

This function should be called before you call parse_form_data, or else filenames are returned.

Used to display all of the key/value pairs.

Return Value



Here are four examples that illustrate some of the functions of this module. You can use these directly in your form processing programs:

Example 1

    # Prints out the key/value pairs using the print_form_data
    # method.
    use CGI_Lite;
    $cgi = new CGI_Lite ()
    # The return value from the method is ignored.
    $cgi->parse_form_data ();
    print "Content-type: text/plain", "\n\n";
    $cgi->print_form_data ();
    exit (0);

Example 2

    # Simple example that performs the same function as the
    # print_form_data method.
    use CGI_Lite;
    $cgi = new CGI_Lite ();
    # The return value is stored in $data, which contains a
    # reference to the hash. In order to access an element, you have
    # to dereference it (i.e: $$data{'readme'} or %$data).
    $data = $cgi->parse_form_data ();
    print "Content-type: text/plain", "\n\n";
    foreach $key (keys %$data) {
        print $key, " = ", $$data{$key}, "\n";
    exit (0);

Example 3

    # Very much like the previous example, except for the fact that
    # the context of the parse_form_data method is an associative
    # array (no need to dereference!)
    use CGI_Lite;
    $cgi = new CGI_Lite ();
    %data = $cgi->parse_form_data ();
    print "Content-type: text/plain", "\n\n";
    foreach $key (keys %data) {
        print $key, " = ", $data{$key}, "\n";
    exit (0);

Example 4

    # Simple example that displays the filename associated with
    # the "readme" field in a multiform/form-data request.
    use CGI_Lite;
    $cgi = new CGI_Lite ();

    # Die if the directory is invalid (i.e doesn't exist, can't
    # read or write to it, or is not a directory)
    $cgi->set_directory ("/usr/shishir")
        || die "Directory doesn't exist.\n";

    # Set the platform (UNIX is the default, anyway)
    $cgi->set_platform ("UNIX");
    # Tell the module to return filehandles
    $cgi->set_file_type ("handle");
    $data = $cgi->parse_form_data ();
    print "Content-type: text/plain", "\n\n";
    # Dereferences the variable to get a filehandle. Then,
    # iterates through the file, displaying each line to STDOUT.
    # NOTE: $filename also contains the name of the file.
    $filename = $$data{'readme'};
    while (<$filename>) {
    # Make sure to close filehandle.
    close ($filename);
    exit (0);

Example 5

    # Simply displays the key/value pairs. Here is how the output
    # would look like for multipart/form-data requests:
    #    Content-type: text/plain
    #    full_name = Foo Bar
    #    picture = /usr/shishir/bar.gif_812186386
    #    readme = /usr/shishir/bar.txt_812186386
    use CGI_Lite;
    $cgi = new CGI_Lite ();
    $cgi->set_directory ("/usr/shishir")
        || die "Directory doesn't exist.\n";
    $data = $cgi->parse_form_data ();
    print "Content-type: text/plain", "\n\n";
    $cgi->print_form_data ();
    exit (0);


You should look at the various other Perl 5.0 CGI modules, and use the one that best suites you. For more information, you can subscribe to the CGI Module Development List at:

Contact: Marc Hedlund ( for more information. This list is not for general CGI support. It only deals with Perl 5.0 CGI module development.

The CGI modules are maintained by Lincoln Stein ( and can be found on his WWW site:


v1.62 - January 17, 1996
Modified the parse_multipart_data subroutine so that it returns the name of the file as the filehandle -- if set_file_type function is called with the ``handle'' parameter.

Added the function determine_package to determine the calling package.

v1.61 - January 1, 1996
Fixed a minor bug that resulted in end of line characters being removed from certain binary files.

v1.6 - December 30, 1995
Added code to handle other header information that the browser might send after the ``Content-Disposition'' header.

Added set_platform function so that uploaded text files display properly.

The function set_file_type no longer returns a status.

Fixed spacing within code.

v1.5 - November 13, 1995
Corrected two major bugs that caused several fields to be lost (when the fields before them were either too small or too large).

Added code to make sure that there are no ``\r\n'' characters in the regular form fields. Textarea elements and fields that contain uploaded information from different platforms (i.e Macintosh and PC) will contain ``\r'' characters.

v1.4 - October 15, 1995
Added pod style documentation. Now you can see this manual page by doing the following:
    pod2man | nroff -man | more

Also, modified the parse_form_data method so that it can return the actual associative array (if called within an array context).

v1.3 - October 12, 1995
Completely modified the parse_multipart_data method. It no longer reads the multipart message line by line, but rather in small size blocks (or ``chunks''). This also eliminated a major bug that caused Netscape to hang.

Since some browsers do not send a ``\r\n'' character string at the end of header lines, the parse_multipart_data method conditionally checks for and removes them. This also allows you to emulate a multipart/form-data request by storing a sample request in a file and piping it to your program:

    cat multipart.txt |

v1.2 - October 12, 1995
Added the set_file_type method to return filehandles for the stored files.

v1.1 - October 10, 1995
The environment variable CONTENT_TYPE is used to determine the type of encoding scheme. In v1.0, the body of the POST request was parsed.

This module no longer outputs an error message if an invalid directory is passed to the set_directory method. Instead, it returns a status of 0 to indicate failure.

v1.0 - September 26, 1995
Initial Release


           Copyright (c) 1995 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.