CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)NAMECGI::Request - Parse client request via a CGI interface
SYNOPSIS
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);
24/Aug/1997 perl 5.005, patch 03 1
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)DESCRIPTION
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.
SMALLEST EXAMPLE
This is the smallest useful CGI::Request script:
use CGI::Request;
GetRequest();
print FmtRequest();
SIMPLE EXAMPLE
This example demonstrates a simple ISINDEX based query,
importing results into a package namespace and escaping of
text:
#!/usr/local/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
CGI
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.
24/Aug/1997 perl 5.005, patch 03 2
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)
FEATURES
Is object oriented and sub-classable.
Can export form field names as normal perl variables.
Integrates with CGI::MiniSvr.
RECENT CHANGES
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 @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.
24/Aug/1997 perl 5.005, patch 03 3
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)
FUTURE DEVELOPMENTS
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).
AUTHOR, COPYRIGHT and ACKNOWLEDGEMENTS
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.
SEE ALSO
CGI::Base, URI::Escape
SUPPORT
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.
FUNCTIONS
GetRequest
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,
24/Aug/1997 perl 5.005, patch 03 4
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)
the output of system("foo") appears before their own
output.
See new CGI::Request for more details.
FmtRequest
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.
Interface
$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.
Debug
$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).
METHODS
new
24/Aug/1997 perl 5.005, patch 03 5
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)
$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 $req CGI::Request object stores the request
parameter values. Parameters can be retrieved using the
param method.
Index keywords (ISINDEX) are automatically recognised,
parsed and stored as values of the 'KEYWORDS' parameter.
The keywords 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'.
as_string
print $req->as_string;
Return an HTML string containing all the query parameters
and CGI parameters neatly and safely formatted. Very
useful for debugging.
extract_values
$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.
24/Aug/1997 perl 5.005, patch 03 6
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)
keywords
@words = $req->keywords
Return the keywords associated with an ISINDEX query.
params
@names = $req->params
Return a list of all known parameter names in the order in
which they're defined
param
$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.
24/Aug/1997 perl 5.005, patch 03 7
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)
delete
$req->delete('field_name1');
Remove the specified field name from the parameter list
param_or
$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.
import_names
$req->import_names('R')
Convert all request parameters into perl variables in a
specified package. This avoids the need to use
$req->param('name'), you can simply sat $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
$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:
$req->cgi->done(), $req->cgi->var("REMOTE_ADDR");
24/Aug/1997 perl 5.005, patch 03 8
CGI::Request(3)User Contributed Perl DocumentationCGI::Request(3)24/Aug/1997 perl 5.005, patch 03 9
