NAME

GT::CGI - a lightweight replacement for CGI.pm


SYNOPSIS

    use GT::CGI;
    my $in = new GT::CGI;
    foreach my $param ($in->param) {
        print "VALUE: $param => ", $in->param($param), "\n";
    }
    use GT::CGI qw/-no_parse_buttons/;


DESCRIPTION

GT::CGI is a lightweight replacement for CGI.pm. It implements most of the functionality of CGI.pm, with the main difference being that GT::CGI does not provide a function-based interface (with the exception of the escape/unescape functions, which can be called as either function or method), nor does it provide the HTML functionality provided by CGI.pm.

The primary motivation for this is to provide a CGI module that can be shipped with Gossamer products, not having to depend on a recent version of CGI.pm being installed on remote servers. The secondary motivation is to provide a module that loads and runs faster, thus speeding up Gossamer products.

Credit and thanks goes to the author of CGI.pm. A lot of the code (especially file upload) was taken from CGI.pm.

param - Accessing form input.

Can be called as either a class method or object method. When called with no arguments a list of keys is returned.

When called with a single argument in scalar context the first (and possibly only) value is returned. When called in list context an array of values is returned.

When called with two arguments, it sets the key-value pair.

header() - Printing HTTP headers

Can be called as a class method or object method. When called with no arguments, simply returns the HTTP header.

Other options include:

-force => 1

Force printing of header even if it has already been displayed.

-type => 'text/plain'

Set the type of the header to something other then text/html.

-charset => 'iso-8859-1'

Set the character set that is sent to the browser. This is only applicable to text types. If this option is not passed in, then no character set is sent.

-cookie => $cookie

Display any cookies. You can pass in a single GT::CGI::Cookie object, or an array of them.

-nph => 1

Display full headers for nph scripts.

-no-cache => 1

Send the appropriate headers to prevent the browser from caching the resulting page.

-url => $url

Redirect the user to the supplied url. By default, it performs a temporary (302) redirect. Use the -permanent option to perform a permanent (301) redirect.

-permanent => 1

Used with the -url option to perform a permanent (301) redirect.

If called with a single argument, sets the Content-Type.

redirect - Redirecting to new URL.

Returns a Location: header to redirect a user.

cookie - Set/Get HTTP Cookies.

Sets or gets a cookie. To retrieve a cookie:

    my $cookie = $cgi->cookie ('key');
    my $cookie = $cgi->cookie (-name => 'key');

or to retrieve a hash of all cookies:

    my $cookies = $cgi->cookie;

To set a cookie:

    $c = $cgi->cookie (-name => 'foo', -value => 'bar')

You can also specify -expires for when the cookie should expire, -path for which path the cookie valid, -domain for which domain the cookie is valid, -secure if the cookie is only valid for secure sites, and -httponly to prevent client side scripts from reading the cookie (for browsers that support it).

You would then set the cookie by passing it to the header function:

    print $in->header ( -cookie => $c );

url - Retrieve the current URL.

Returns the current URL of the script. It defaults to display just the script name and query string.

Options include:

absolute => 1

Return the full URL: http://domain/path/to/script.cgi

relative => 1

Return only the script name: script.cgi

query_string => 1

Return the query string as well: script.cgi?a=b

path_info => 1

Returns the path info as well: script.cgi/foobar

remove_empty => 0

Removes empty query= from the query string.

get_hash - Return all form input as hash.

This returns the current parameters as a hash. Any values that have the same key will be returned as an array reference of the multiple values.

escape - URL escape a string.

Returns the passed in value URL escaped. Can be called as class method or object method.

unescape - URL unescape a string.

Returns the passed in value URL un-escaped. Can be called as class method or object method. Optionally can take an array reference of strings instead of a string. If called in this method, the values of the array reference will be directly altered.

html_escape - HTML escape a string

Returns the passed in value HTML escaped. Translates &, <, > and `` to their html equivalants.

html_unescape - HTML unescapes a string

Returns the passed in value HTML unescaped.

post_data - Return POSTed data.

If POSTed data is not of type application/x-www-form-urlencoded or multipart/form-data, then the POSTed data will not be processed. You can retrieve this data using this method.

upload_hook - Callback for file uploads

Takes a code reference, and for every file upload, runs the code reference and passes it the filename, a reference to the data, and the total bytes read.

Must be called before any other function, or as a parameter to new.


DEPENDENCIES

Note: GT::CGI depends on the GT::Base manpage and the GT::AutoLoader manpage, and if you are performing file uploads, GT::CGI::MultiPart, GT::CGI::Fh, and the GT::TempFile manpage. The ability to set cookies requires GT::CGI::Cookie.


COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/


VERSION

Revision: $Id: CGI.pm,v 1.159 2009/04/07 22:34:18 brewt Exp $