1CGI::Simple::Standard(3U)ser Contributed Perl DocumentatiCoGnI::Simple::Standard(3)
2
3
4

NAME

6       CGI::Simple::Standard - a wrapper module for CGI::Simple that provides
7       a function style interface
8

SYNOPSIS

10           use CGI::Simple::Standard qw( -autoload );
11           use CGI::Simple::Standard qw( :core :cookie :header :misc );
12           use CGI::Simple::Standard qw( param upload );
13
14           $CGI::Simple::Standard::POST_MAX = 1024;       # max upload via post 1kB
15           $CGI::Simple::Standard::DISABLE_UPLOADS = 0;   # enable uploads
16
17           @params = param();        # return all param names as a list
18           $value =  param('foo');   # return the first value supplied for 'foo'
19           @values = param('foo');   # return all values supplied for foo
20
21           %fields   = Vars();       # returns untied key value pair hash
22           $hash_ref = Vars();       # or as a hash ref
23           %fields   = Vars("|");    # packs multiple values with "|" rather than "\0";
24
25           @keywords = keywords();   # return all keywords as a list
26
27           param( 'foo', 'some', 'new', 'values' );        # set new 'foo' values
28           param( -name=>'foo', -value=>'bar' );
29           param( -name=>'foo', -value=>['bar','baz'] );
30
31           append( -name=>'foo', -value=>'bar' );          # append values to 'foo'
32           append( -name=>'foo', -value=>['some', 'new', 'values'] );
33
34           Delete('foo');   # delete param 'foo' and all its values
35           Delete_all();    # delete everything
36
37           <INPUT TYPE="file" NAME="upload_file" SIZE="42">
38
39           $files    = upload()                   # number of files uploaded
40           @files    = upload();                  # names of all uploaded files
41           $filename = param('upload_file')       # filename of 'upload_file' field
42           $mime     = upload_info($filename,'mime'); # MIME type of uploaded file
43           $size     = upload_info($filename,'size'); # size of uploaded file
44
45           my $fh = $q->upload($filename);     # open filehandle to read from
46           while ( read( $fh, $buffer, 1024 ) ) { ... }
47
48           # short and sweet upload
49           $ok = upload( param('upload_file'), '/path/to/write/file.name' );
50           print "Uploaded ".param('upload_file')." and wrote it OK!" if $ok;
51
52           $decoded    = url_decode($encoded);
53           $encoded    = url_encode($unencoded);
54           $escaped    = escapeHTML('<>"&');
55           $unescaped  = unescapeHTML('&lt;&gt;&quot;&amp;');
56
57           $qs = query_string();   # get all data in $q as a query string OK for GET
58
59           no_cache(1);            # set Pragma: no-cache + expires
60           print header();         # print a simple header
61           # get a complex header
62           $header = header(   -type       => 'image/gif'
63                               -nph        => 1,
64                               -status     => '402 Payment required',
65                               -expires    =>'+24h',
66                               -cookie     => $cookie,
67                               -charset    => 'utf-7',
68                               -attachment => 'foo.gif',
69                               -Cost       => '$2.00');
70
71           @cookies = cookie();        # get names of all available cookies
72           $value   = cookie('foo')    # get first value of cookie 'foo'
73           @value   = cookie('foo')    # get all values of cookie 'foo'
74           # get a cookie formatted for header() method
75           $cookie  = cookie(  -name    => 'Password',
76                               -values  => ['superuser','god','my dog woofie'],
77                               -expires => '+3d',
78                               -domain  => '.nowhere.com',
79                               -path    => '/cgi-bin/database',
80                               -secure  => 1 );
81           print header( -cookie=>$cookie );       # set cookie
82
83           print redirect('http://go.away.now');   # print a redirect header
84
85           dienice( cgi_error() ) if cgi_error();
86

DESCRIPTION

88       This module is a wrapper for the completely object oriented CGI::Simple
89       module and provides a simple functional style interface. It provides
90       two different methods to import function names into your namespace.
91
92   Autoloading
93       If you specify the '-autoload' pragma like this:
94
95           use CGI::Simple::Standard qw( -autoload );
96
97       Then it will use AUTOLOAD and a symbol table trick to export only those
98       subs you actually call into your namespace. When you specify the
99       '-autoload' pragma this module exports a single AUTOLOAD subroutine
100       into you namespace. This will clash with any AUTOLOAD sub that exists
101       in the calling namespace so if you are using AUTOLOAD for something
102       else don't use this pragma.
103
104       Anyway, when you call a subroutine that is not defined in your script
105       this AUTOLOAD sub will be called. The first time this happens it will
106       initialize a CGI::Simple object and then apply the requested method (if
107       it exists) to it. A fatal exception will be thrown if you try to use an
108       undefined method (function).
109
110   Specified Export
111       Alternatively you can specify the functions you wish to import. You can
112       do this on a per function basis like this:
113
114           use CGI::Simple::Standard qw( param upload query_string Dump );
115
116       or utilize the %EXPORT_TAGS that group functions into related groups.
117       Here are the groupings:
118
119         %EXPORT_TAGS = (
120           ':html'     => [ qw(:misc) ],
121           ':standard' => [ qw(:core :access) ],
122           ':cgi'      => [ qw(:core :access) ],
123           ':all'      => [ qw(:core :misc :cookie :header :push :debug :cgi-lib
124                               :access :internal) ],
125           ':core'     => [ qw(param add_param param_fetch url_param keywords
126                               append Delete delete_all Delete_all upload
127                               query_string parse_query_string  parse_keywordlist
128                               Vars save_parameters restore_parameters) ],
129           ':misc'     => [ qw(url_decode url_encode escapeHTML unescapeHTML put) ],
130           ':cookie'   => [ qw(cookie raw_cookie) ],
131           ':header'   => [ qw(header cache no_cache redirect) ],
132           ':push'     => [ qw(multipart_init multipart_start multipart_end
133                               multipart_final) ],
134           ':debug'    => [ qw(Dump as_string cgi_error _cgi_object) ],
135           ':cgi-lib'  => [ qw(ReadParse SplitParam MethGet MethPost MyBaseUrl MyURL
136                               MyFullUrl PrintHeader HtmlTop HtmlBot PrintVariables
137                               PrintEnv CgiDie CgiError Vars) ],
138           ':ssl'      => [ qw(https) ],
139           ':access'   => [ qw(version nph all_parameters charset crlf globals
140                               auth_type content_length content_type document_root
141                               gateway_interface path_translated referer remote_addr
142                               remote_host remote_ident remote_user request_method
143                               script_name server_name server_port server_protocol
144                               server_software user_name user_agent virtual_host
145                               path_info Accept http https protocol url self_url
146                               state) ],
147           ':internal' => [ qw(_initialize_globals _use_cgi_pm_global_settings
148                               _store_globals _reset_globals) ]
149           );
150
151       The familiar CGI.pm tags are available but do not include the HTML
152       functionality. You specify the import of some function groups like
153       this:
154
155       use CGI::Simple::Standard qw( :core :cookie :header );
156
157       Note that the function groups all start with a : char.
158
159   Mix and Match
160       You can use the '-autoload' pragma, specifically named function imports
161       and tag group imports together if you desire.
162

$POST_MAX and $DISABLE_UPLOADS

164       If you wish to set $POST_MAX or $DISABLE_UPLOADS you must do this
165       *after* the use statement and *before* the first function call as shown
166       in the synopsis.
167
168       Unlike CGI.pm uploads are disabled by default and the maximum
169       acceptable data via post is capped at 102_400kB rather than infinity.
170       This is specifically to avoid denial of service attacks by default. To
171       enable uploads and to allow them to be of infinite size you simply:
172
173           $CGI::Simple::Standard::POST_MAX = -1;         # infinite size upload
174           $CGI::Simple::Standard::$DISABLE_UPLOADS = 0;  # enable uploads
175
176       Alternatively you can specify the CGI.pm default values as shown above
177       by specifying the '-default' pragma in your use statement.
178
179           use CGI::Simple::Standard qw( -default ..... );
180

EXPORT

182       Nothing by default.
183
184       Under the '-autoload' pragma the AUTOLOAD subroutine is exported into
185       the calling namespace. Additional subroutines are only imported into
186       this namespace if you physically call them. They are installed in the
187       symbol table the first time you use them to save repeated calls to
188       AUTOLOAD.
189
190       If you specifically request a function or group of functions via an
191       EXPORT_TAG then stubs of these functions are exported into the calling
192       namespace. These stub functions will be replaced with the real
193       functions only if you actually call them saving wasted compilation
194       effort.
195

FUNCTION DETAILS

197       This is a wrapper module for CGI::Simple. Virtually all the methods
198       available in the OO interface are available via the functional
199       interface. Several method names are aliased to prevent namespace
200       conflicts:
201
202           $q->delete('foo')   =>  Delete('foo')
203           $q->delete_all      =>  Delete_all() or delete_all()
204           $q->save(\*FH)      =>  save_parameters(\*FH)
205           $q->accept()        =>  Accept()
206
207       Although you could use the new() function to genrate new OO CGI::Simple
208       objects the restore_parameters() function is a better choice as it
209       operates like new but on the correct underlying CGI::Simple object for
210       the functional interface.
211
212       restore_parameters() can be used exactly as you might use new() in that
213       you can supply arguments to it such as query strings, hashes and file
214       handles to re-initialize your underlying object.
215
216           $q->new CGI::Simple()                => restore_parameters()
217           $q->new CGI::Simple({foo=>'bar'})    => restore_parameters({foo=>'bar'})
218           $q->new CGI::Simple($query_string)   => restore_parameters($query_string)
219           $q->new CGI::Simple(\*FH)            => restore_parameters(\*FH)
220
221       For full details of the available functions see the CGI::Simple docs.
222       Just remove the $q-> part and use the method name directly.
223

BUGS

225       As this is 0.01 there are almost bound to be some.
226

AUTHOR

228       Dr James Freeman <jfreeman@tassie.net.au> This release by Andy
229       Armstrong <andy@hexten.net>
230
231       This package is free software and is provided "as is" without express
232       or implied warranty. It may be used, redistributed and/or modified
233       under the terms of the Perl Artistic License (see
234       http://www.perl.com/perl/misc/Artistic.html)
235
236       Address bug reports and comments to: andy@hexten.net
237

CREDITS

239       The interface and key sections of the CGI::Simple code come from CGI.pm
240       by Lincoln Stein.
241

SEE ALSO

243       CGI::Simple which is the back end for this module, CGI.pm by Lincoln
244       Stein
245
246
247
248perl v5.30.1                      2020-01-29          CGI::Simple::Standard(3)
Impressum