.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::Simple::Standard 3pm"
.TH CGI::Simple::Standard 3pm 2024-02-04 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
CGI::Simple::Standard \- a wrapper module for CGI::Simple that provides a
function style interface
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&    use CGI::Simple::Standard qw( \-autoload );
\&    use CGI::Simple::Standard qw( :core :cookie :header :misc );
\&    use CGI::Simple::Standard qw( param upload );
\&
\&    $CGI::Simple::Standard::POST_MAX = 1024;       # max upload via post 1kB
\&    $CGI::Simple::Standard::DISABLE_UPLOADS = 0;   # enable uploads
\&
\&    @params = param();        # return all param names as a list
\&    $value =  param(\*(Aqfoo\*(Aq);   # return the first value supplied for \*(Aqfoo\*(Aq
\&    @values = param(\*(Aqfoo\*(Aq);   # return all values supplied for foo
\&
\&    %fields   = Vars();       # returns untied key value pair hash
\&    $hash_ref = Vars();       # or as a hash ref
\&    %fields   = Vars("|");    # packs multiple values with "|" rather than "\e0";
\&
\&    @keywords = keywords();   # return all keywords as a list
\&
\&    param( \*(Aqfoo\*(Aq, \*(Aqsome\*(Aq, \*(Aqnew\*(Aq, \*(Aqvalues\*(Aq );        # set new \*(Aqfoo\*(Aq values
\&    param( \-name=>\*(Aqfoo\*(Aq, \-value=>\*(Aqbar\*(Aq );
\&    param( \-name=>\*(Aqfoo\*(Aq, \-value=>[\*(Aqbar\*(Aq,\*(Aqbaz\*(Aq] );
\&
\&    append( \-name=>\*(Aqfoo\*(Aq, \-value=>\*(Aqbar\*(Aq );          # append values to \*(Aqfoo\*(Aq
\&    append( \-name=>\*(Aqfoo\*(Aq, \-value=>[\*(Aqsome\*(Aq, \*(Aqnew\*(Aq, \*(Aqvalues\*(Aq] );
\&
\&    Delete(\*(Aqfoo\*(Aq);   # delete param \*(Aqfoo\*(Aq and all its values
\&    Delete_all();    # delete everything
\&
\&    <INPUT TYPE="file" NAME="upload_file" SIZE="42">
\&
\&    $files    = upload()                   # number of files uploaded
\&    @files    = upload();                  # names of all uploaded files
\&    $filename = param(\*(Aqupload_file\*(Aq)       # filename of \*(Aqupload_file\*(Aq field
\&    $mime     = upload_info($filename,\*(Aqmime\*(Aq); # MIME type of uploaded file
\&    $size     = upload_info($filename,\*(Aqsize\*(Aq); # size of uploaded file
\&
\&    my $fh = $q\->upload($filename);     # open filehandle to read from
\&    while ( read( $fh, $buffer, 1024 ) ) { ... }
\&
\&    # short and sweet upload
\&    $ok = upload( param(\*(Aqupload_file\*(Aq), \*(Aq/path/to/write/file.name\*(Aq );
\&    print "Uploaded ".param(\*(Aqupload_file\*(Aq)." and wrote it OK!" if $ok;
\&
\&    $decoded    = url_decode($encoded);
\&    $encoded    = url_encode($unencoded);
\&    $escaped    = escapeHTML(\*(Aq<>"&\*(Aq);
\&    $unescaped  = unescapeHTML(\*(Aq&lt;&gt;&quot;&amp;\*(Aq);
\&
\&    $qs = query_string();   # get all data in $q as a query string OK for GET
\&
\&    no_cache(1);            # set Pragma: no\-cache + expires
\&    print header();         # print a simple header
\&    # get a complex header
\&    $header = header(   \-type       => \*(Aqimage/gif\*(Aq
\&                        \-nph        => 1,
\&                        \-status     => \*(Aq402 Payment required\*(Aq,
\&                        \-expires    =>\*(Aq+24h\*(Aq,
\&                        \-cookie     => $cookie,
\&                        \-charset    => \*(Aqutf\-7\*(Aq,
\&                        \-attachment => \*(Aqfoo.gif\*(Aq,
\&                        \-Cost       => \*(Aq$2.00\*(Aq);
\&
\&    @cookies = cookie();        # get names of all available cookies
\&    $value   = cookie(\*(Aqfoo\*(Aq)    # get first value of cookie \*(Aqfoo\*(Aq
\&    @value   = cookie(\*(Aqfoo\*(Aq)    # get all values of cookie \*(Aqfoo\*(Aq
\&    # get a cookie formatted for header() method
\&    $cookie  = cookie(  \-name    => \*(AqPassword\*(Aq,
\&                        \-values  => [\*(Aqsuperuser\*(Aq,\*(Aqgod\*(Aq,\*(Aqmy dog woofie\*(Aq],
\&                        \-expires => \*(Aq+3d\*(Aq,
\&                        \-domain  => \*(Aq.nowhere.com\*(Aq,
\&                        \-path    => \*(Aq/cgi\-bin/database\*(Aq,
\&                        \-secure  => 1 );
\&    print header( \-cookie=>$cookie );       # set cookie
\&
\&    print redirect(\*(Aqhttp://go.away.now\*(Aq);   # print a redirect header
\&
\&    dienice( cgi_error() ) if cgi_error();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module is a wrapper for the completely object oriented CGI::Simple
module and provides a simple functional style interface. It provides two
different methods to import function names into your namespace.
.SS Autoloading
.IX Subsection "Autoloading"
If you specify the '\-autoload' pragma like this:
.PP
.Vb 1
\&    use CGI::Simple::Standard qw( \-autoload );
.Ve
.PP
Then it will use AUTOLOAD and a symbol table trick to export only those subs
you actually call into your namespace. When you specify the '\-autoload' pragma
this module exports a single AUTOLOAD subroutine into you namespace. This will
clash with any AUTOLOAD sub that exists in the calling namespace so if you are
using AUTOLOAD for something else don't use this pragma.
.PP
Anyway, when you call a subroutine that is not defined in your script this
AUTOLOAD sub will be called. The first time this happens it
will initialize a CGI::Simple object and then apply the requested method
(if it exists) to it. A fatal exception will be thrown if you try to use an
undefined method (function).
.SS "Specified Export"
.IX Subsection "Specified Export"
Alternatively you can specify the functions you wish to import. You can do
this on a per function basis like this:
.PP
.Vb 1
\&    use CGI::Simple::Standard qw( param upload query_string Dump );
.Ve
.PP
or utilize the \f(CW%EXPORT_TAGS\fR that group functions into related groups.
Here are the groupings:
.PP
.Vb 10
\&  %EXPORT_TAGS = (
\&    \*(Aq:html\*(Aq     => [ qw(:misc) ],
\&    \*(Aq:standard\*(Aq => [ qw(:core :access) ],
\&    \*(Aq:cgi\*(Aq      => [ qw(:core :access) ],
\&    \*(Aq:all\*(Aq      => [ qw(:core :misc :cookie :header :push :debug :cgi\-lib
\&                        :access :internal) ],
\&    \*(Aq:core\*(Aq     => [ qw(param add_param param_fetch url_param keywords
\&                        append Delete delete_all Delete_all upload
\&                        query_string parse_query_string  parse_keywordlist
\&                        Vars save_parameters restore_parameters) ],
\&    \*(Aq:misc\*(Aq     => [ qw(url_decode url_encode escapeHTML unescapeHTML put) ],
\&    \*(Aq:cookie\*(Aq   => [ qw(cookie raw_cookie) ],
\&    \*(Aq:header\*(Aq   => [ qw(header cache no_cache redirect) ],
\&    \*(Aq:push\*(Aq     => [ qw(multipart_init multipart_start multipart_end
\&                        multipart_final) ],
\&    \*(Aq:debug\*(Aq    => [ qw(Dump as_string cgi_error _cgi_object) ],
\&    \*(Aq:cgi\-lib\*(Aq  => [ qw(ReadParse SplitParam MethGet MethPost MyBaseUrl MyURL
\&                        MyFullUrl PrintHeader HtmlTop HtmlBot PrintVariables
\&                        PrintEnv CgiDie CgiError Vars) ],
\&    \*(Aq:ssl\*(Aq      => [ qw(https) ],
\&    \*(Aq:access\*(Aq   => [ qw(version nph all_parameters charset crlf globals
\&                        auth_type content_length content_type document_root
\&                        gateway_interface path_translated referer remote_addr
\&                        remote_host remote_ident remote_user request_method
\&                        script_name server_name server_port server_protocol
\&                        server_software user_name user_agent virtual_host
\&                        path_info Accept http https protocol url self_url
\&                        state) ],
\&    \*(Aq:internal\*(Aq => [ qw(_initialize_globals _use_cgi_pm_global_settings
\&                        _store_globals _reset_globals) ]
\&    );
.Ve
.PP
The familiar CGI.pm tags are available but do not include the HTML
functionality. You specify the import of some function groups like this:
.PP
use CGI::Simple::Standard qw( :core :cookie :header );
.PP
Note that the function groups all start with a : char.
.SS "Mix and Match"
.IX Subsection "Mix and Match"
You can use the '\-autoload' pragma, specifically named function imports and
tag group imports together if you desire.
.ie n .SH "$POST_MAX and $DISABLE_UPLOADS"
.el .SH "\f(CW$POST_MAX\fP and \f(CW$DISABLE_UPLOADS\fP"
.IX Header "$POST_MAX and $DISABLE_UPLOADS"
If you wish to set \f(CW$POST_MAX\fR or \f(CW$DISABLE_UPLOADS\fR you must do this *after* the
use statement and *before* the first function call as shown in the synopsis.
.PP
Unlike CGI.pm uploads are disabled by default and the maximum acceptable
data via post is capped at 102_400kB rather than infinity. This is specifically
to avoid denial of service attacks by default. To enable uploads and to
allow them to be of infinite size you simply:
.PP
.Vb 2
\&    $CGI::Simple::Standard::POST_MAX = \-1;         # infinite size upload
\&    $CGI::Simple::Standard::$DISABLE_UPLOADS = 0;  # enable uploads
.Ve
.PP
Alternatively you can specify the CGI.pm default values as shown above by
specifying the '\-default' pragma in your use statement.
.PP
.Vb 1
\&    use CGI::Simple::Standard qw( \-default ..... );
.Ve
.SH EXPORT
.IX Header "EXPORT"
Nothing by default.
.PP
Under the '\-autoload' pragma the AUTOLOAD subroutine is
exported into the calling namespace. Additional subroutines are only imported
into this namespace if you physically call them. They are installed in the
symbol table the first time you use them to save repeated calls to AUTOLOAD.
.PP
If you specifically request a function or group of functions via an EXPORT_TAG
then stubs of these functions are exported into the calling namespace. These
stub functions will be replaced with the real functions only if you actually
call them saving wasted compilation effort.
.SH "FUNCTION DETAILS"
.IX Header "FUNCTION DETAILS"
This is a wrapper module for CGI::Simple. Virtually all the methods available
in the OO interface are available via the functional interface. Several
method names are aliased to prevent namespace conflicts:
.PP
.Vb 4
\&    $q\->delete(\*(Aqfoo\*(Aq)   =>  Delete(\*(Aqfoo\*(Aq)
\&    $q\->delete_all      =>  Delete_all() or delete_all()
\&    $q\->save(\e*FH)      =>  save_parameters(\e*FH)
\&    $q\->accept()        =>  Accept()
.Ve
.PP
Although you could use the \fBnew()\fR function to genrate new OO CGI::Simple
objects the \fBrestore_parameters()\fR function is a better choice as it operates
like new but on the correct underlying CGI::Simple object for the functional
interface.
.PP
\&\fBrestore_parameters()\fR can be used exactly as you might use \fBnew()\fR in that
you can supply arguments to it such as query strings, hashes and file handles
to re-initialize your underlying object.
.PP
.Vb 4
\&    $q\->new CGI::Simple()                => restore_parameters()
\&    $q\->new CGI::Simple({foo=>\*(Aqbar\*(Aq})    => restore_parameters({foo=>\*(Aqbar\*(Aq})
\&    $q\->new CGI::Simple($query_string)   => restore_parameters($query_string)
\&    $q\->new CGI::Simple(\e*FH)            => restore_parameters(\e*FH)
.Ve
.PP
For full details of the available functions see the CGI::Simple docs. Just
remove the \f(CW$q\fR\-> part and use the method name directly.
.SH BUGS
.IX Header "BUGS"
As this is 0.01 there are almost bound to be some.
.SH AUTHOR
.IX Header "AUTHOR"
Dr James Freeman <jfreeman@tassie.net.au>
This release by Andy Armstrong <andy@hexten.net>
.PP
This package is free software and is provided "as is" without express or
implied warranty. It may be used, redistributed and/or modified under the terms
of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)
.PP
Address bug reports and comments to: andy@hexten.net
.SH CREDITS
.IX Header "CREDITS"
The interface and key sections of the CGI::Simple code come from
CGI.pm by Lincoln Stein.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CGI::Simple which is the back end for this module,
\&\fBCGI.pm by Lincoln Stein\fR