CGI_Lite.pm

NAME

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

SYNOPSIS

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 ();

DESCRIPTION

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:

application/x-www-form-urlencoded multipart/form-data

This module is very light-weight, and can be thought of as an enhanced version of the old cgi-lib.pl library for Perl 4.0 by Steven Brenner (S.E.Brenner@bioc.cam.ac.uk).

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> <HR> <FORM ACTION="/cgi-bin/test.pl" ENCTYPE="multipart/form-data" METHOD="POST"> What is your name? <INPUT TYPE="text" NAME="username"> <P> Select a file to send: <INPUT TYPE="file" NAME="input_file"> <P> <INPUT TYPE="submit" VALUE="Send the Multipart Form"> <INPUT TYPE="reset" VALUE="Clear the Information"> </FORM> <HR>

multipart/form-data MIME header

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

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

METHODS

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

parse_form_data

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:

/some/dir/filename.timestamp

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).

Restrictions

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

set_platform

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:
PC EOL:
Macintosh EOL:

By default, ``UNIX'' is assumed.

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

set_file_type

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.

print_form_data

Used to display all of the key/value pairs.

Return Value

None

EXAMPLES

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

#!/usr/local/bin/perl5 # 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

#!/usr/local/bin/perl5 # 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

#!/usr/local/bin/perl5 # 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

#!/usr/local/bin/perl5 # 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>) { print; } # Make sure to close filehandle. close ($filename); exit (0);

Example 5

#!/usr/local/bin/perl5 # 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);

REVISION HISTORY

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 CGI_Lite.pm | 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 | test.pl

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 INFORMATION

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.