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:
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).
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>
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--
Here are the methods you can use to process your forms:
/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.
You can specify either:
UNIX EOL: <LF>
PC EOL: <CR><LF>
Macintosh EOL: <CR>
By default, ``UNIX'' is assumed.
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
This function should be called before you call parse_form_data, or else filenames are returned.
Return Value
None
Here are four examples that illustrate some of the functions of this module. You can use these directly in your form processing programs:
#!/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);
#!/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);
#!/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);
#!/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);
#!/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);
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 (hedlund@best.com) 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 (lstein@genome.wi.mit.edu) and can be found on his WWW site:
http://www-genome.wi.mit.edu/WWW/tools/scripting
Added the function determine_package to determine the calling package.
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.
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.
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).
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
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.
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.