CGI::Request - Parse client request via a CGI interface

    use CGI::Request;

    # Simple interface: (combines SendHeaders, new and import_names)

    $req = GetRequest($pkg);

    print FmtRequest();            # same as: print $req->as_string

    # Full Interface:

    $req = new CGI::Request;       # fetch and parse request

    $field_value = $req->param('FieldName');
    @selected    = $req->param('SelectMultiField');
    @keywords    = $req->keywords; # from ISINDEX

    print $req->as_string;         # format Form and CGI variables

    # import form fields into a package as perl variables!
    $req->import_names('R');
    print "$R::FieldName";
    print "@R::SelectMultiField";

    @value = $req->param_or($fieldname, $default_return_value);

    # Access to CGI interface (see CGI::Base)

    $cgi_obj = $req->cgi;
    $cgi_var = $req->cgi->var("REMOTE_ADDR");

    # Other Functions:

    CGI::Request::Interface($cgi);  # specify alternative CGI

    CGI::Request::Debug($level);    # log to STDERR (see CGI::Base)

    # Cgi-lib compatibility functions
    # use CGI::Request qw(:DEFAULT :cgi-lib); to import them

    &ReadParse(*input);
    &MethGet;
    &PrintHeader;
    &PrintVariables(%input);

This module implements the CGI::Request object. This object represents a single query / request / submission from a WWW user. The CGI::Request class understands the concept of HTML forms and fields, specifically how to parse a CGI QUERY_STRING.

This is the smallest useful CGI::Request script:

    use CGI::Request;
    GetRequest();
    print FmtRequest();

This example demonstrates a simple ISINDEX based query, importing results into a package namespace and escaping of text:

    #!/usr/bin/perl  # add -T to test tainted behaviour

    use CGI::Base;
    use CGI::Request;

    GetRequest('R');       # get and import request into R::...

    # Just to make life more interesting add an ISINDEX.
    # Try entering: "aa bb+cc dd=ee ff&gg hh<P>ii"
    print "<ISINDEX>\r\n";

    print "<B>You entered:</B> ", # print results safely
          join(', ', CGI::Base::html_escape(@R::KEYWORDS))."\r\n";

    print FmtRequest();    # show formatted version of request

A CGI::Request object contains a reference to a CGI::Base object (or an object derived from CGI::Base). It uses the services of that object to get the raw request information.

Note that CGI::Request does not inherit from CGI::Base it just uses an instance of a CGI::Base object.

See the cgi method description for more information.

Is object oriented and sub-classable.

Can export form field names as normal perl variables.

Integrates with CGI::MiniSvr.

2.75

Fixed bug in import_names(). Now works properly with both scalar and array elements.

2.4 through 2.74

Minor changes to accomodate Forms interface.

2.1 thru 2.3

Minor enhancements to documentation and debugging. Added notes about relationship with CGI and how to access CGI variables.

2.0

Updates for changed CGI:Base export tags. No longer setting CW@CGI::Request::QUERY_STRING. Added param_or() method. The module file can be run as a cgi script to execute a demo/test. You may need to chmod +x this file and teach your httpd that it can execute *.pm files (or create a copy/symlink with another name).

1.8

GetRequest now call SendHeaders (in CGI::Base) for you. This works *much* better than the old 'print PrintHeaders;'. PrintHeaders is no longer exported by default. as_string now uses the new html_escape method (in CGI::Base) to safely format strings with embedded html. Debugging now defaults to off. New Debug function added. Image map coords are automatically recognised and stored as parameters X and Y. Added a sequence number mechanism to assist debugging MiniSvr applications (does not impact/cost anything for non minisvr apps).

1.7

Default package for import_names() removed, you must supply a package name. GetRequest() won't call import_names unless a package name has been given, thus GetRequest no longer defaults to importing names. Added as_string() method (which automatically calls cgi->as_string). param() will croak if called in a scalar context for a multi-values field.

None of this is perfect. All suggestions welcome.

Note that this module is *not* the place to put code which generates HTML. We'll need separate modules for that (which are being developed).

This code is Copyright (C) Tim Bunce 1995. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The cgi-lib functions are based on cgi-lib.pl version 1.7 which is Copyright 1994 Steven E. Brenner.

IN NO EVENT SHALL THE AUTHORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION (INCLUDING, BUT NOT LIMITED TO, LOST PROFITS) EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CGI::Base, URI::Escape

Please use comp.infosystems.www.* and comp.lang.perl.misc for support. Please do _NOT_ contact the author directly. I'm sorry but I just don't have the time.

    GetRequest();
    GetRequest($package_name);
    $req = GetRequest(...);

GetRequest is the main entry point for simple (non-object oriented) use of the CGI::Request module. It combines output (and flushing) of the standard Content-Type header, request processing and optional importing of the resulting values into a package (see import_names).

This function also enables autoflush on stdout. This has a slight efficiency cost but huge benefits in reduced frustration by novice users wondering why, for example, the output of system(foo) appears before their own output.

See CWnew CGI::Request for more details.

    print FmtRequest();

Return a HTML string which describes the last (current) client request parameters and the current raw CGI parameters. Designed to be used for debugging purposes.

    $cgi = Interface();

Return the default CGI interface object. Rarely used by applications.

If no interface has been defined yet it will automatically create a new CGI::Base object, set that as the default interface and return it. This is the mechanism by which simple applications get to use the CGI::Base interface without knowing anything about it.

This function can also be use to define a new default interface (such as CGI::MiniSvr) by passing a reference to a CGI::Base object or a object derived from CGI::Base.

    $old_level = CGI::Request::Debug();
    $old_level = CGI::Request::Debug($new_level);

Set debug level for the CGI::Request module. Debugging info is logged to STDERR (see CGI::Base for examples of how to redirect STDERR).

    $req = new CGI::Request;
    $req = new CGI::Request $cgi_interface;
    $req = new CGI::Request $cgi_interface, $timeout_in_seconds;

CGI::Request object constructor. Only the first form listed above should be used by most applications.

Note that, unlike GetRequest, new CGI::Request does not call SendHeaders for you. You have the freedom to control how you send your headers and what headers to send.

The returned CW$req CGI::Request object stores the request parameter values. Parameters can be retrieved using the CWparam method.

Index keywords (ISINDEX) are automatically recognised, parsed and stored as values of the 'KEYWORDS' parameter. The CWkeywords method provides an easy way to retrieve the list of keywords.

Image Map (ISMAP) coordinates are automatically recognised, parsed and stored as parameters 'X' and 'Y'.

    print $req->as_string;

Return an HTML string containing all the query parameters and CGI parameters neatly and safely formatted. Very useful for debugging.

    $req->extract_values($QUERY_STRING)

This method extracts parameter name/value pairs from a string (typically QUERY_STRING) and stores them in the objects hash. Not normally called by applications, new() calls it automatically.

The parameter names and values are individually unescaped using the uri_unescape() function in the URI::URL module.

For ISINDEX keyword search requests (QUERY_STRING contains no '=' or '&') the string is split on /+/ and the keywords are then individually unescaped and stored. Either the keywords() method (or param('KEYWORDS')) can be used to recover the values.

    @words = $req->keywords

Return the keywords associated with an ISINDEX query.

    @names = $req->params

Return a list of all known parameter names in the order in which they're defined

    $value  = $req->param('field_name1');
    @values = $req->param('field_name2');       # e.g. select multiple
    $req->param('field_name3', $new_value);
    $req->param('field_name4', @new_values);

Returns the value(s) of a named parameter. Returns an empty list/undef if the parameter name is not known. Returns '' for a parameter which had no value.

If invoked in a list context param returns the list of values in the same order they were returned by the client (typically from a select multiple form field).

Warning: If invoked in a scalar context and the parameter has more than one value the param method will die. This catches badly constructed forms where a field may have been copied but its name left unchanged.

If more than one argument is provided, the second and subsequent arguments are used to set the value of the parameter. The previous values, if any, are returned. Note that setting a new value has no external effect and is only included for completeness.

Note that param does not return CGI variables (REMOTE_ADDR etc) since those are CGI variables and not form parameters. To access CGI variables see the cgi method in this module and the CGI::Base module documentation.

    $req->delete('field_name1');

Remove the specified field name from the parameter list

    $value  = $req->param_or('field_name1', $default);
    @values = $req->param_or('field_name2', @defaults);

If the current request was a query (QUERY_STRING defined) then this method is identical to the param method with only one argument.

If the current request was not a query (QUERY_STRING undefined) then this method simply returns its second and subsequent parameters.

The method is designed to be used as a form building utility.

    $req->import_names('R')

Convert all request parameters into perl variables in a specified package. This avoids the need to use CW$req->param('name'), you can simply sat CW$R::name ('R' is the recommended package names).

Note: This is a convenience function for simple CGI scripts. It should not be used with the MiniSvr since there is no way to reset or unimport the values from one request before importing the values of the next.

    $cgi = $req->cgi;

This method returns the current CGI::Request default CGI interface object. It is primarily intended as a handy shortcut for accessing CGI::Base methods: CW$req->cgi->done(), CW$req->cgi->var(REMOTE_ADDR);