view release on metacpan or  search on metacpan

CGI_Lite.pm  view on Meta::CPAN

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

=head1 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. 

=head1 METHODS

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

=over 4

=item B<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 B<set_directory>). If timestamp mode is on (see 
B<add_timestamp>), the files are named in the following format:

    timestamp__filename

where the filename is specified in the "Content-disposition" header.
I<NOTE:>, the browser URL encodes the name of the file. This module
makes I<no> effort to decode the information for security reasons.
However, you can do so by creating a subroutine and then using
the B<filter_filename> method.

I<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 B<set_file_type> method).

=item B<parse_cookies>

Decodes and parses cookies passed by the browser. This method works in 
much the same manner as B<parse_form_data>. 

=item B<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
B<parse_form_data> or B<parse_cookies>.

I<Return Value>

    0 Success
    1 Failure

=item B<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 B<is_error> method.

I<Return Value>

The error message.

=item B<return_error>

You can use this method to return errors to the browser and exit. 

=item B<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 B<add_mime_type> and
B<remove_mime_type> methods) so that they display properly on that
platform.

CGI_Lite.pm  view on Meta::CPAN

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 
I<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!

I<Return Value>

Array consisting of the multiple values.

=item B<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? 

=item B<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.

I<Return Value>

Escaped string.

=item B<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.

I<Return Value>

URL encoded string.

=item B<url_decode>

You can use this method to URL decode a string. 

I<Return Value>

URL decoded string.

=item B<is_dangerous>

This method checks for the existence of dangerous meta-characters.

I<Return Value>

    0 Safe
    1 Dangerous

=item B<escape_dangerous_chars>

You can use this method to "escape" any dangerous meta-characters.

I<Return Value>

Escaped string.

=back

=head1 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 I<(lstein@genome.wi.mit.edu)> and can be found at your local
CPAN mirror and at his Web site:

I<http://www-genome.wi.mit.edu/WWW/tools/scripting>

=head1 ACKNOWLEDGMENTS

I'd like to thank the following for finding bugs and offering 
suggestions:

=over 4

=item Eric D. Friedman (friedman@uci.edu)   

=item Thomas Winzig (tsw@pvo.com)

=item Len Charest (len@cogent.net)

=item Achim Bohnet (ach@rosat.mpe-garching.mpg.de)

=item John E. Townsend (John.E.Townsend@BST.BLS.com)

=item Andrew McRae (mcrae@internet.com)

=item Dennis Grant (dg50@chrysler.com)

=item Scott Neufeld (scott.neufeld@mis.ussurg.com)

=item Raul Almquist (imrs@ShadowMAC.org)

=item and many others!

=back

=head1 COPYRIGHT INFORMATION