view release on metacpan or  search on metacpan

lib/CGI/Lite.pm  view on Meta::CPAN

##     see separate CHANGES file for detailed history
##
##     Changes in versions 2.03 and newer copyright
##     (c) 2014-2015, 2017-2018, 2021 Pete Houston
##
##     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.
##--

###############################################################################

=head1 NAME

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

=head1 SYNOPSIS

    use CGI::Lite ();

    my $cgi = CGI::Lite->new ();

    $cgi->set_directory ('/some/dir') or die "Directory cannot be set.\n";
    $cgi->add_mime_type ('text/csv');

    my $cookies = $cgi->parse_cookies;
    my $form    = $cgi->parse_new_form_data;

    my $status  = $cgi->is_error;
    if ($status) {
        my $message = $cgi->get_error_message;
        die $message;
    }

=head1 DESCRIPTION

This module can be used to decode form data, query strings, file uploads
and cookies in a very simple manner.

It has only one dependency and is therefore relatively fast to
instantiate. This makes it well suited to a non-persistent CGI scenario.

=head1 METHODS

Here are the methods used to process the forms and cookies:



=head2 new

The constructor takes no arguments and returns a new CGI::Lite object.

=head2 parse_form_data

This handles 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, it may also be passed a valid request 
method as a scalar string to force CGI::Lite to decode the information in 
a specific manner. 

	my $params = $cgi->parse_form_data ('GET');

For multipart/form-data, uploaded files are stored in the user selected 
directory (see L<set_directory|/set_directory>). If timestamp mode is on (see 
L<add_timestamp|/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, this can be achieved by creating a subroutine and then using
the L<filter_filename|/filter_filename> method.

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 L<set_file_type|/set_file_type> method).

=head2 parse_new_form_data

As for parse_form_data, but clears the CGI object state before processing 
the request. This is useful in persistent applications (e.g. FCGI), where
the CGI object is reused for multiple requests. e.g.

    my $CGI = CGI::Lite->new ();
    while (FCGI::accept > 0)
    {
        my $query = $CGI->parse_new_form_data ();
        # process query
    }

=head2 parse_cookies

Decodes and parses cookies passed by the browser. This method works in 
much the same manner as L<parse_form_data|/parse_form_data>. As these two data sources
are treated the same internally, users who wish to extract form and
cookie data separately might find it easiest to call
parse_cookies first and then parse_new_form_data in order to retrieve
two distinct hashes (or hashrefs).

=head2 is_error

This method is used to check for any potential errors after calling
either L<parse_form_data|/parse_form_data> or L<parse_cookies|/parse_cookies>.

    my $form = $cgi->parse_form_data ();
    my $went_wrong = $cgi->is_error ();

Returns 0 if there is no error, 1 otherwise.

=head2 get_error_message

If an error occurs when parsing form/query information or cookies, this
method may be used to retrieve the error message. Remember, the presence
of any errors can be checked by calling the L<is_error|/is_error> method.

lib/CGI/Lite.pm  view on Meta::CPAN

    my $keys = $cgi->get_ordered_keys;
    my @keys = $cgi->get_ordered_keys;

=head2 print_data

Displays all the key/value pairs (either form data or cookie information)
in an ordered fashion to standard output. It is mainly useful for
debugging. There are no arguments and no return values.

=head2 wrap_textarea

This is a method to wrap a long string into one that is separated by EOL
characters (see L<set_platform|/set_platform>) at fixed lengths.  The two arguments
to be passed to this method are the string and the length at which the
line separator is to be added.

    my $new_string = $cgi->wrap_textarea ($string, $length);

Returns the modified string.

=head2 get_multiple_values

The values returned by the parsing methods in this module for multiple
fields with the same name are given as array references. This utility
method exists to convert either a scalar value or an array reference
into a list thus removing the need for the user to determine whether the
returned value for any field is a reference or a scalar.

    @all_values = $cgi->get_multiple_values ($reference);

It is only provided as a convenience to the user and is not used
internally by the module itself.

Returns a list consisting of the multiple values.

=head2 browser_escape

Certain characters have special significance within HTML. These
characters are: <, >, &, ", # and %. To display these "special"
characters, they can be escaped using the following notation "&#NNN;"
where NNN is their ASCII code.  This utility method does just that.

    $escaped_string = $cgi->browser_escape ($string);

Returns the escaped string.

=head2 url_encode

This method will URL-encode a string passed as its argument. It may be
used to encode any data to be passed as a query string to a CGI
application, for example.

    $encoded_string = $cgi->url_encode ($string);

Returns the URL-encoded string.

=head2 url_decode

This method is used to URL-decode a string. 

    $decoded_string = $cgi->url_decode ($string);

Returns the URL-decoded string.

=head2 is_dangerous

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

    $status = $cgi->is_dangerous ($string);

Returns 1 if such characters are found, 0 otherwise.



=head1 DEPRECATED METHODS

The following methods and subroutines are deprecated. Please do not use
them in new code and consider excising them from old code. They will be
removed in a future release.

=over 4

=item B<return_error>

    $cgi->return_error ('error 1', 'error 2', 'error 3');

You can use this method to print errors to standard output (ie. as part of
the HTTP response) and exit. B<This method is deprecated as of version 3.0.>
The same functionality can be achieved with:

    print ('error 1', 'error 2', 'error 3');
    exit 1;

=item B<create_variables>

B<This method is deprecated as of version 3.0.> It runs contrary to the
principles of structured programming and has really nothing to do with
CGI form or cookie handling. It is retained here for backwards
compatibility but will be removed entirely in later versions.

    %form = ('name'   => 'alan wells',
             'sport'  => 'track and field',
             'events' => '100m');

    $cgi->create_variables (\%hash);

This converts a hash ref into scalars named for its keys and this
example will create three scalar variables: $name, $sport and $events. 

=back

=head1 OBSOLETE METHODS/SUBROUTINES

The following methods and subroutines were deprecated in the 2.x branch
and have now been removed entirely from the module.

=over 4

=item B<escape_dangerous_chars>

The use of this subroutine had been strongly discouraged for more than a
decade (See
L<https://web.archive.org/web/20100627014535/http://use.perl.org/~cbrooks/journal/10542>