view release on metacpan or  search on metacpan

lib/CGI/Simple.pm  view on Meta::CPAN

1;

=head1 NAME

CGI::Simple - A Simple totally OO CGI interface that is CGI.pm compliant

=head1 VERSION

This document describes CGI::Simple version 1.282.

=head1 SYNOPSIS

    use CGI::Simple;
    $CGI::Simple::POST_MAX = 1024;       # max upload via post default 100kB
    $CGI::Simple::DISABLE_UPLOADS = 0;   # enable uploads

    $q = CGI::Simple->new;
    $q = CGI::Simple->new( { 'foo'=>'1', 'bar'=>[2,3,4] } );
    $q = CGI::Simple->new( 'foo=1&bar=2&bar=3&bar=4' );
    $q = CGI::Simple->new( \*FILEHANDLE );

    $q->save( \*FILEHANDLE );   # save current object to a file as used by new

    @params = $q->param;        # return all param names as a list
    $value = $q->param('foo');  # return the first value supplied for 'foo'
    @values = $q->param('foo'); # return all values supplied for foo

    %fields   = $q->Vars;      # returns untied key value pair hash
    $hash_ref = $q->Vars;      # or as a hash ref
    %fields   = $q->Vars("|"); # packs multiple values with "|" rather than "\0";

    @keywords = $q->keywords;  # return all keywords as a list

    $q->param( 'foo', 'some', 'new', 'values' );      # set new 'foo' values
    $q->param( -name=>'foo', -value=>'bar' );
    $q->param( -name=>'foo', -value=>['bar','baz'] );

    $q->param( 'foo', 'some', 'new', 'values' );      # append values to 'foo'
    $q->append( -name=>'foo', -value=>'bar' );
    $q->append( -name=>'foo', -value=>['some', 'new', 'values'] );

    $q->delete('foo'); # delete param 'foo' and all its values
    $q->delete_all;    # delete everything

    <INPUT TYPE="file" NAME="upload_file" SIZE="42">

    $files    = $q->upload()                # number of files uploaded
    @files    = $q->upload();               # names of all uploaded files
    $filename = $q->param('upload_file')    # filename of uploaded file
    $mime     = $q->upload_info($filename,'mime'); # MIME type of uploaded file
    $size     = $q->upload_info($filename,'size'); # size of uploaded file

    my $fh = $q->upload($filename);         # get filehandle to read from
    while ( read( $fh, $buffer, 1024 ) ) { ... }

    # short and sweet upload
    $ok = $q->upload( $q->param('upload_file'), '/path/to/write/file.name' );
    print "Uploaded ".$q->param('upload_file')." and wrote it OK!" if $ok;

    $decoded    = $q->url_decode($encoded);
    $encoded    = $q->url_encode($unencoded);
    $escaped    = $q->escapeHTML('<>"&');
    $unescaped  = $q->unescapeHTML('&lt;&gt;&quot;&amp;');

    $qs = $q->query_string; # get all data in $q as a query string OK for GET

    $q->no_cache(1);        # set Pragma: no-cache + expires
    print $q->header();     # print a simple header
    # get a complex header
    $header = $q->header(   -type       => 'image/gif'
                            -nph        => 1,
                            -status     => '402 Payment required',
                            -expires    =>'+24h',
                            -cookie     => $cookie,
                            -charset    => 'utf-7',
                            -attachment => 'foo.gif',
                            -Cost       => '$2.00'
                        );
    # a p3p header (OK for redirect use as well)
    $header = $q->header( -p3p => 'policyref="http://somesite.com/P3P/PolicyReferences.xml' );

    @cookies = $q->cookie();        # get names of all available cookies
    $value   = $q->cookie('foo')    # get first value of cookie 'foo'
    @value   = $q->cookie('foo')    # get all values of cookie 'foo'
    # get a cookie formatted for header() method
    $cookie  = $q->cookie(  -name    => 'Password',
                            -values  => ['superuser','god','my dog woofie'],
                            -expires => '+3d',
                            -domain  => '.nowhere.com',
                            -path    => '/cgi-bin/database',
                            -secure  => 1
                         );
    print $q->header( -cookie=>$cookie );       # set cookie

    print $q->redirect('http://go.away.now');   # print a redirect header

    dienice( $q->cgi_error ) if $q->cgi_error;

=head1 DESCRIPTION

CGI::Simple provides a relatively lightweight drop in replacement for CGI.pm.
It shares an identical OO interface to CGI.pm for parameter parsing, file
upload, cookie handling and header generation. This module is entirely object
oriented, however a complete functional interface is available by using the
CGI::Simple::Standard module.

Essentially everything in CGI.pm that relates to the CGI (not HTML) side of
things is available. There are even a few new methods and additions to old
ones! If you are interested in what has gone on under the hood see the
Compatibility with CGI.pm section at the end.

In practical testing this module loads and runs about twice as fast as CGI.pm
depending on the precise task.

=head1 CALLING CGI::Simple ROUTINES USING THE OBJECT INTERFACE

Here is a very brief rundown on how you use the interface. Full details
follow.

=head2 First you need to initialize an object

lib/CGI/Simple.pm  view on Meta::CPAN

    use CGI::Simple;
    $CGI::Simple::DISABLE_UPLOADS = 0;
    $q = CGI::Simple->new;

If you wish to set $DISABLE_UPLOADS you must do this *after* the
use statement and *before* the new constructor call as shown above.

The maximum acceptable data via post is capped at 102_400kB rather than
infinity which is the CGI.pm default. This should be ample for most tasks
but you can set this to whatever you want using the $POST_MAX global.

    use CGI::Simple;
    $CGI::Simple::DISABLE_UPLOADS = 0;      # enable uploads
    $CGI::Simple::POST_MAX = 1_048_576;     # allow 1MB uploads
    $q = CGI::Simple->new;

If you set to -1 infinite size uploads will be permitted, which is the CGI.pm
default.

    $CGI::Simple::POST_MAX = -1;            # infinite size upload

Alternatively you can specify all the CGI.pm default values which allow file
uploads of infinite size in one easy step by specifying the '-default' pragma
in your use statement.

    use CGI::Simple qw( -default ..... );

=head2 binmode() and Win32

If you are using CGI::Simple be sure to call B<binmode()> on any handle that
you create to write the uploaded file to disk. Calling B<binmode()> will do
no harm on other systems anyway.

=cut

################ Miscellaneous Methods ################

=head1 MISCELANEOUS METHODS

=head2 escapeHTML() Escaping HTML special characters

In HTML the < > " and & chars have special meaning and need to be
escaped to &lt; &gt; &quot; and &amp; respectively.

    $escaped = $q->escapeHTML( $string );

    $escaped = $q->escapeHTML( $string, 'new_lines_too' );

If the optional second argument is supplied then newlines will be escaped to.

=head2 unescapeHTML() Unescape HTML special characters

This performs the reverse of B<escapeHTML()>.

    $unescaped = $q->unescapeHTML( $HTML_escaped_string );

=head2 url_decode() Decode a URL encoded string

This method will correctly decode a url encoded string.

    $decoded = $q->url_decode( $encoded );

=head2 url_encode() URL encode a string

This method will correctly URL encode a string.

    $encoded = $q->url_encode( $string );

=head2 parse_keywordlist() Parse a supplied keyword list

    @keywords = $q->parse_keywordlist( $keyword_list );

This method returns a list of keywords, correctly URL escaped and split out
of the supplied string

=head2 put() Send output to browser

CGI.pm alias for print. $q->put('Hello World!') will print the usual

=head2 print() Send output to browser

CGI.pm alias for print. $q->print('Hello World!') will print the usual

=cut

################# Cookie Methods ################

=head1 HTTP COOKIES

CGI.pm has several methods that support cookies.

A cookie is a name=value pair much like the named parameters in a CGI
query string.  CGI scripts create one or more cookies and send
them to the browser in the HTTP header.  The browser maintains a list
of cookies that belong to a particular Web server, and returns them
to the CGI script during subsequent interactions.

In addition to the required name=value pair, each cookie has several
optional attributes:

=over 4

=item 1. an expiration time

This is a time/date string (in a special GMT format) that indicates
when a cookie expires.  The cookie will be saved and returned to your
script until this expiration date is reached if the user exits
the browser and restarts it.  If an expiration date isn't specified, the cookie
will remain active until the user quits the browser.

=item 2. a domain

This is a partial or complete domain name for which the cookie is
valid.  The browser will return the cookie to any host that matches
the partial domain name.  For example, if you specify a domain name
of ".capricorn.com", then the browser will return the cookie to
Web servers running on any of the machines "www.capricorn.com",
"www2.capricorn.com", "feckless.capricorn.com", etc.  Domain names
must contain at least two periods to prevent attempts to match
on top level domains like ".edu".  If no domain is specified, then
the browser will only return the cookie to servers on the host the