NAME
     CGI::Utils - Utilities for retrieving information through the
     Common Gateway Interface

SYNOPSIS
     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.

     mod_perl is supported if a value for apache_request is passed to
     new(), or if the apache request object is available via
     Apache->request, or if running under HTML::Mason.  See the
     documentation for the new() method for details.

     If not running in a mod_perl or CGI environment, @ARGV will be
     searched for key/value pairs in the format

         key1=val1 key2=val2

     If all command-line arguments are in this format, the key/value
     pairs will be available as if they were passed via a CGI or
     mod_perl interface.

METHODS
  new(\%params)
     Returns a new CGI::Utils object.  Parameters are optional.
     CGI::Utils supports mod_perl if the Apache request object is
     passed as $params{apache_request}, or if it is available via
     Apache->request, or if running under HTML::Mason.

     You may also pass max_post_size in %params.

  urlEncode($str)
     Returns the fully URL-encoded version of the given string.  It
     does not convert space characters to '+' characters.

  urlUnicodeEncode($str)
     Returns the fully URL-encoded version of the given string as
     unicode characters.  It does not convert space characters to '+'
     characters.

  urlDecode($url_encoded_str)
     Returns the decoded version of the given URL-encoded string.

  urlUnicodeDecode($url_encoded_str)
     Returns the decoded version of the given URL-encoded string,
     with unicode support.

  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.com

  getSelfRefUrl()
     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)
     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.

     Aliases: vars(), Vars(), get_args(), args()

    # Other information provided by the CGI environment

  getPathInfo(), path_info(), get_path_info();
     Returns additional virtual path information from the URL (if
     any) after your script.

  getRemoteAddr(), remote_addr(), get_remote_addr()
     Returns the dotted decimal representation of the remote client's
     IP address.

  getRemoteHost(), remote_host(), get_remote_host()
     Returns the name of the remote host, or its IP address if the
     name is unavailable.

  getHost(), host(), virtual_host(), get_host()
     Returns the name of the host in the URL being accessed.  This is
     sent as the Host header by the web browser.

  getReferer(), referer(), get_referer(), getReferrer(), referrer(), get_referrer()
     Returns the referring URL.

  getProtocol(), protocol(), get_protocol()
     Returns the protocol, i.e., http or https.

  getRequestMethod(), request_method(), get_request_method()
     Returns the request method, i.e., GET, POST, HEAD, or PUT.

  getContentType(), content_type(), get_content_type()
     Returns the content type.

  getPathTranslated(), path_translated(), get_path_translated()
     Returns the physical path information if provided in the CGI environment.

  getQueryString(), query_string(), get_query_string()
     Returns a query string created from the current parameters.

  getHeader(@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' );

     Cookies may be passed with the 'cookies' key either as a string,
     a hash ref, or as a CGI::Cookies object, e.g.

        my $cookie = { name => 'my_cookie', value => 'cookie_val' };
        print $cgi_obj->getHeader(cookies => $cookie);

     You may also pass an array of cookies, e.g.,

        print $cgi_obj->getHeader(cookies => [ $cookie1, $cookie2 ]);

     Aliases: header(), get_header

  sendHeader(@args)
     Like getHeader() above, except sends it.  Under mod_perl, this
     sends the header(s) via the Apache request object.  In a CGI
     environment, this prints the header(s) to STDOUT.

     Aliases: send_header()

  getRedirect($url)
     Returns the header required to do a redirect.  This method also
     accepts named arguments, e.g.,

         print $cgi_obj->getRedirect(url => $url, status => 302,
                                     cookie => \%cookie_params);

     You may also pass a cookies argument as in getHeader().

     Aliases: redirect()

  sendRedirect($url)
     Like getRedirect(), but in a CGI environment the output is sent
     to STDOUT, and in a mod_perl environment, the appropriate
     headers are set.  The return value is 1 for a CGI environment
     when successful, and Apache::Constants::REDIRECT in a mod_perl
     environment, so you can do something like

     return $utils->sendRedirect($url)

     in a mod_perl handler.

     Aliases: send_redirect()

  getLocalRedirect(), local_redirect(), get_local_redirect()
     Like getRedirect(), except that the redirect URL is converted
     from relative to absolute, including the host.

  getCookieString(\%hash), get_cookie_string(\%hash);
     Returns a string to pass as the value of a 'Set-Cookie' header.

  getSetCookieString(\%params), getSetCookieString([ \%params1, \%params2 ])
     Returns a string to pass as the 'Set-Cookie' header(s), including
     the line ending(s).  Also accepts a simple hash with key/value pairs.

  setCookie(\%params), set_cookie(\%params);
     Sets the cookie generated by getCookieString.  That is, in a
     mod_perl environment, it adds an outgoing header to set the
     cookie.  In a CGI environment, it prints the value of
     getSetCookieString to STDOUT (including the end-of-line
     sequence).

  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.

ACKNOWLEDGEMENTS
     Other people who have contributed ideas and/or code for this module:

        Kevin Wilson

AUTHOR
     Don Owens <don@owensnet.com>

COPYRIGHT
     Copyright (c) 2003-2005 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.08

