CGI::Base - HTTP Daemon Common Gateway Interface (CGI) Base Class
use CGI::Base;
$cgi = new CGI::Base; # reads vars from environment
$cgi->var($name); # get CGI variable value
$cgi->var($name, $value); # set CGI variable value
@names = $cgi->vars; # lists standard CGI variables
$mime_type = $cgi->accept_best(@mime_types);
$preference = $cgi->accept_type($mime_type);
$cgi->pass_thru($host, $port); # forward request to server
$cgi->redirect($url); # redirect client
$cgi->done($dump); # end response, does NOT send </BODY>
$cgi->exit(@log_msgs); # exit, optionally logging messages
# Other functions:
@escaped_texts = html_escape(@texts); # '>' -> '<' etc
@texts = html_br_lines(@texts); # \n -> '<BR>'
SendHeaders(); # send and flush HTTP header(s)
CGI::Base::Debug($level);
This module implements a CGI::Base object. This object represents the interface between the application and an HTTP deamon.
In a typical CGI scenario the interface is just a collection of
environment variables. This module makes those variables available
either via a $cgi->var() method or optionally as plain perl variables
(see IMPORTING CGI VARIABLES below). Small scripts will tend to use
the imported variables, larger scripts may prefer to use the var
method.
By default the CGI::Base class will transparently deal with POST and PUT submissions by reading STDIN into $QUERY_STRING.
The CGI::Base module simplifies CGI debugging by providing logging methods (which redirect STDERR to a file) and a very handy test mode. The test mode automatically detects that the script is not being run by a HTTP server and requests test input from the user (or command line).
Users of this module can optionally import the CGI values as ordinary perl variables of the same name into their package. For example, saying:
use CGI::Base qw(:DEFAULT QUERY_STRING REQUEST_METHOD);
will allow you to refer to the CGI query string and request method as
simply $QUERY_STRING and $REQUEST_METHOD. Any changes made to these
variables will be reflected in the values returned by the var() method.
To import all the fixed CGI variables (excludes optional variables string with HTTP_) use:
use CGI::Base qw(:DEFAULT :CGI);
The CGI::Base class has been specifically designed to enable it to be subclassed to implement alternative interfaces. For example the CGI::MiniSvr class implements a 'mini http daemon' which can be spawned from a CGI script in order, for example, to maintain state information for a client 'session'.
The CGI::Base class (and classes derived from it) are not designed to understand the contents of the data they are handling. Only basic data acquisition tasks and basic metadata parsing are performed by CGI::Base. The QUERY_STRING is not parsed.
Higher level query processing (parsing of QUERY_STRING and handling of form fields etc) is performed by the CGI::Request module.
Note that CGI application developers will generally deal with the CGI::Request class and not directly with the CGI::Base class.
Object oriented and sub-classable.
Exporting of CGI environment variables as plain perl variables.
Supports pass_thru and redirection of URL's.
Extensible attribute system for CGI environment variables.
Very handy automatic test mode if script is run manually.
These basic principles and assumptions apply to CGI::Base and can be built into any application using CGI::Base. Any subclass of CGI::Base, such as CGI::MiniSvr, must uphold these principles.
STDIN, STDOUT are connected to the client, possibly via a server.
STDERR can be used for error logging (see open_log method).
%ENV should not be used to access CGI parameters. See ENVIRONMENT section below.
The CGI::Base module copies all the CGI/1.1 standard environment variables into internal storage. See the definition of %CgiEnv and @CgiObj. The stored values are available either via the var method or as exported variables.
It is recommended that $ENV{...} is not used to access the CGI variables because alternative CGI interfaces, such as CGI::MiniSvr, may not bother to maintain %ENV consistent with the internal values. The simple scalar variables are also much faster to access.
Changes to create compatability with CGI::Form.
Miscellaneous small bug fixes.
get_url() now adds SERVER_PORT to the url. pass_thru() split into
component methods forward_request() and pass_back(). The new
forward_request method can shutdown() the sending side of the socket.
SendHeaders does nothing and returns undef if called more than once.
All these changes are useful for sophisticated applications.
Slightly improved documentation. Added html_br_lines() to purify
html_escape(). Added SIGPIPE handling (not used by default).
Documented the automatic test mode. Assorted other minor clean ups.
Added support for any letter case in HTTP headers. Fixed (worked around) a perl/stdio bug which affected POST handling in the MiniSvr. Added $ENTITY_BODY to hold the Entity-Body for PUT, POST and CHECKIN methods. $QUERY_STRING now only set from $ENTITY_BODY if CONTENT_TYPE is application/x-www-form-urlencoded. Changed some uses of map to foreach. Slight improved performance of pass_thru.