NAME
CGI::Utils - Utilities for retrieving information through the
Common Gateway InterfaceSYNOPSIS
use CGI::Utils;
my $utils = CGI::Utils->new;
my $fields = $utils->vars; # or $utils->Vars
my $field1 = $$fields{field1};
or
my $field1 = $utils->param('field1');
# File uploads
my $file_handle = $utils->param('file0'); # or $$fields{file0};
my $file_name = "$file_handle"; DESCRIPTION
This module can be used almost as a drop-in replacement for
CGI.pm for those of you who do not use the HTML generating
features of CGI.pm
This module provides an object-oriented interface for retrieving
information provided by the Common Gateway Interface, as well as
url-encoding and decoding values, and parsing CGI
parameters. For example, CGI has a utility for escaping HTML,
but no public interface for url-encoding a value or for taking a
hash of values and returning a url-encoded query string suitable
for passing to a CGI script. This module does that, as well as
provide methods for creating a self-referencing url, converting
relative urls to absolute, adding CGI parameters to the end of a
url, etc. Please see the METHODS section below for more
detailed descriptions of functionality provided by this module.
File uploads via the multipart/form-data encoding are supported.
The parameter for the field name corresponding to the file is a
file handle that, when evaluated in string context, returns the
name of the file uploaded. To get the contents of the file,
just read from the file handle.METHODS
new()
Returns a new CGI::Utils object.urlEncode($str)
Returns the fully URL-encoded version of the given string. It
does not convert space characters to '+' characters.urlDecode($url_encoced_str)
Returns the decoded version of the given URL-encoded string.urlEncodeVars($var_hash, $sep)
Takes a hash of name/value pairs and returns a fully URL-encoded
query string suitable for passing in a URL. By default, uses
the newer separator, a semicolon, as recommended by the W3C. If
you pass in a second argument, it is used as the separator
between key/value pairs.urlDecodeVars($query_string)
Takes a URL-encoded query string, decodes it, and returns a
reference to a hash of name/value pairs. For multivalued
fields, the value is an array of values. If called in array
context, it returns a reference to a hash of name/value pairs,
and a reference to an array of field names in the order they
appear in the query string.escapeHtml($text)
Escapes the given text so that it is not interpreted as HTML.escapeHtmlFormValue($text)
Escapes the given text so that it is valid to put in a form
field.getSelfRefHostUrl()
Returns a url referencing top level directory in the current
domain, e.g., http://mydomain.comgetSelfRefUrl()
Returns a url referencing the current script (without any query
string).getSelfRefUri()
Returns the current URI.getSelfRefUrlWithQuery()
Returns a url referencing the current script along with any
query string parameters passed via a GET method.getSelfRefUrlWithParams($params)
Returns a url reference the current script along with the given
hash of parameters added onto the end of url as a query string.getSelfRefUrlDir()
Returns a url referencing the directory part of the current url.convertRelativeUrlWithParams($relative_url, $params)
Converts a relative URL to an absolute one based on the current
URL, then adds the parameters in the given hash $params as a
query string.addParamsToUrl($url, $param_hash)
Takes a url and reference to a hash of parameters to be added
onto the url as a query string and returns a url with those
parameters. It checks whether or not the url already contains a
query string and modifies it accordingly. If you want to add a
multivalued parameter, pass it as a reference to an array
containing all the values.getParsedCookies()
Parses the cookies passed to the server. Returns a hash of
key/value pairs representing the cookie names and values.param($name)
Returns the CGI parameter with name $name. If called in array
context, it returns an array. In scalar context, it returns an
array reference for multivalued fields, and a scalar for
single-valued fields.getVars($delimiter), vars($delimiter), Vars($delimiter)
Also Vars() to be compatible with CGI.pm. Returns a reference
to a tied hash containing key/value pairs corresponding to each
CGI parameter. For multivalued fields, the value is an array
ref, with each element being one of the values. If you pass in
a value for the delimiter, multivalued fields will be returned
as a string of values delimited by the delimiter you passed in.# Other information provided by the CGI environment
getPathInfo(), path_info()
Returns additional virtual path information from the URL (if
any) after your script.getRequestMethod(), request_method()
Return the request method, i.e., GET, POST, HEAD, or PUT.getContentType(), content_type()
Return the content type.getPathTranslated(), path_translated()
Return the physical path information if provided in the CGI environment.getQueryString(), query_string()
Return a query string created from the current parameters.getHeader(@args), header(@args)
Generates HTTP headers. Standard arguments are content_type,
cookie, target, expires, and charset. These should be passed as
name/value pairs. If only one argument is passed, it is assumed
to be the 'content_type' argument. If no values are passed, the
content type is assumed to be 'text/html'. The charset defaults
to ISO-8859-1. A hash reference can also be passed. E.g.,
print $cgi_obj->getHeader({ content_type => 'text/html', expires => '+3d' });
The names 'content-type', and 'type' are aliases for
'content_type'. The arguments may also be passed CGI.pm style
with a '-' in front, e.g.
print $cgi_obj->getHeader( -content_type => 'text/html', -expires => '+3d' );uploadInfo($file_name)
Returns a reference to a hash containing the header information
sent along with a file upload.EXPORTS
You can export methods into your namespace in the usual way.
All of the util methods are available for export, e.g.,
getSelfRefUrl(), addParamsToUrl(), etc. Beware, however, that
these methods expect to be called as methods. You can also use
the tag :all_utils to import all of the util methods into your
namespace. This allows for incorporating these methods into
your class without having to inherit from CGI::Utils.AUTHOR
Don Owens <don@owensnet.com>COPYRIGHT
Copyright (c) 2003-2004 Don Owens
All rights reserved. This program is free software; you can
redistribute it and/or modify it under the same terms as Perl
itself.VERSION
0.06