local-lib5/man/man3/CGI::Simple::Standard.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "CGI::Simple::Standard 3"
 132 .TH CGI::Simple::Standard 3 "2009-05-31" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 CGI::Simple::Standard \- a wrapper module for CGI::Simple that provides a
 135 function style interface
 136 .SH "SYNOPSIS"
 137 .IX Header "SYNOPSIS"
 138 .Vb 3
 139 \&    use CGI::Simple::Standard qw( \-autoload );
 140 \&    use CGI::Simple::Standard qw( :core :cookie :header :misc );
 141 \&    use CGI::Simple::Standard qw( param upload );
 142 .Ve
 143 .PP
 144 .Vb 2
 145 \&    $CGI::Simple::Standard::POST_MAX = 1024;       # max upload via post 1kB
 146 \&    $CGI::Simple::Standard::DISABLE_UPLOADS = 0;   # enable uploads
 147 .Ve
 148 .PP
 149 .Vb 3
 150 \&    @params = param();        # return all param names as a list
 151 \&    $value =  param('foo');   # return the first value supplied for 'foo'
 152 \&    @values = param('foo');   # return all values supplied for foo
 153 .Ve
 154 .PP
 155 .Vb 3
 156 \&    %fields   = Vars();       # returns untied key value pair hash
 157 \&    $hash_ref = Vars();       # or as a hash ref
 158 \&    %fields   = Vars("|");    # packs multiple values with "|" rather than "\e0";
 159 .Ve
 160 .PP
 161 .Vb 1
 162 \&    @keywords = keywords();   # return all keywords as a list
 163 .Ve
 164 .PP
 165 .Vb 3
 166 \&    param( 'foo', 'some', 'new', 'values' );        # set new 'foo' values
 167 \&    param( \-name=>'foo', \-value=>'bar' );
 168 \&    param( \-name=>'foo', \-value=>['bar','baz'] );
 169 .Ve
 170 .PP
 171 .Vb 2
 172 \&    append( \-name=>'foo', \-value=>'bar' );          # append values to 'foo'
 173 \&    append( \-name=>'foo', \-value=>['some', 'new', 'values'] );
 174 .Ve
 175 .PP
 176 .Vb 2
 177 \&    Delete('foo');   # delete param 'foo' and all its values
 178 \&    Delete_all();    # delete everything
 179 .Ve
 180 .PP
 181 .Vb 1
 182 \&    <INPUT TYPE="file" NAME="upload_file" SIZE="42">
 183 .Ve
 184 .PP
 185 .Vb 5
 186 \&    $files    = upload()                   # number of files uploaded
 187 \&    @files    = upload();                  # names of all uploaded files
 188 \&    $filename = param('upload_file')       # filename of 'upload_file' field
 189 \&    $mime     = upload_info($filename,'mime'); # MIME type of uploaded file
 190 \&    $size     = upload_info($filename,'size'); # size of uploaded file
 191 .Ve
 192 .PP
 193 .Vb 2
 194 \&    my $fh = $q\->upload($filename);     # open filehandle to read from
 195 \&    while ( read( $fh, $buffer, 1024 ) ) { ... }
 196 .Ve
 197 .PP
 198 .Vb 3
 199 \&    # short and sweet upload
 200 \&    $ok = upload( param('upload_file'), '/path/to/write/file.name' );
 201 \&    print "Uploaded ".param('upload_file')." and wrote it OK!" if $ok;
 202 .Ve
 203 .PP
 204 .Vb 4
 205 \&    $decoded    = url_decode($encoded);
 206 \&    $encoded    = url_encode($unencoded);
 207 \&    $escaped    = escapeHTML('<>"&');
 208 \&    $unescaped  = unescapeHTML('&lt;&gt;&quot;&amp;');
 209 .Ve
 210 .PP
 211 .Vb 1
 212 \&    $qs = query_string();   # get all data in $q as a query string OK for GET
 213 .Ve
 214 .PP
 215 .Vb 11
 216 \&    no_cache(1);            # set Pragma: no\-cache + expires
 217 \&    print header();         # print a simple header
 218 \&    # get a complex header
 219 \&    $header = header(   \-type       => 'image/gif'
 220 \&                        \-nph        => 1,
 221 \&                        \-status     => '402 Payment required',
 222 \&                        \-expires    =>'+24h',
 223 \&                        \-cookie     => $cookie,
 224 \&                        \-charset    => 'utf\-7',
 225 \&                        \-attachment => 'foo.gif',
 226 \&                        \-Cost       => '$2.00');
 227 .Ve
 228 .PP
 229 .Vb 11
 230 \&    @cookies = cookie();        # get names of all available cookies
 231 \&    $value   = cookie('foo')    # get first value of cookie 'foo'
 232 \&    @value   = cookie('foo')    # get all values of cookie 'foo'
 233 \&    # get a cookie formatted for header() method
 234 \&    $cookie  = cookie(  \-name    => 'Password',
 235 \&                        \-values  => ['superuser','god','my dog woofie'],
 236 \&                        \-expires => '+3d',
 237 \&                        \-domain  => '.nowhere.com',
 238 \&                        \-path    => '/cgi\-bin/database',
 239 \&                        \-secure  => 1 );
 240 \&    print header( \-cookie=>$cookie );       # set cookie
 241 .Ve
 242 .PP
 243 .Vb 1
 244 \&    print redirect('http://go.away.now');   # print a redirect header
 245 .Ve
 246 .PP
 247 .Vb 1
 248 \&    dienice( cgi_error() ) if cgi_error();
 249 .Ve
 250 .SH "DESCRIPTION"
 251 .IX Header "DESCRIPTION"
 252 This module is a wrapper for the completely object oriented CGI::Simple
 253 module and provides a simple functional style interface. It provides two
 254 different methods to import function names into your namespace.
 255 .Sh "Autoloading"
 256 .IX Subsection "Autoloading"
 257 If you specify the '\-autoload' pragma like this:
 258 .PP
 259 .Vb 1
 260 \&    use CGI::Simple::Standard qw( \-autoload );
 261 .Ve
 262 .PP
 263 Then it will use \s-1AUTOLOAD\s0 and a symbol table trick to export only those subs
 264 you actually call into your namespace. When you specify the '\-autoload' pragma
 265 this module exports a single \s-1AUTOLOAD\s0 subroutine into you namespace. This will
 266 clash with any \s-1AUTOLOAD\s0 sub that exists in the calling namespace so if you are
 267 using \s-1AUTOLOAD\s0 for something else don't use this pragma.
 268 .PP
 269 Anyway, when you call a subroutine that is not defined in your script this
 270 \&\s-1AUTOLOAD\s0 sub will be called. The first time this happens it
 271 will initialize a CGI::Simple object and then apply the requested method
 272 (if it exists) to it. A fatal exception will be thrown if you try to use an
 273 undefined method (function).
 274 .Sh "Specified Export"
 275 .IX Subsection "Specified Export"
 276 Alternatively you can specify the functions you wish to import. You can do
 277 this on a per function basis like this:
 278 .PP
 279 .Vb 1
 280 \&    use CGI::Simple::Standard qw( param upload query_string Dump );
 281 .Ve
 282 .PP
 283 or utilize the \f(CW%EXPORT_TAGS\fR that group functions into related groups.
 284 Here are the groupings:
 285 .PP
 286 .Vb 31
 287 \&  %EXPORT_TAGS = (
 288 \&    ':html'     => [ qw(:misc) ],
 289 \&    ':standard' => [ qw(:core :access) ],
 290 \&    ':cgi'      => [ qw(:core :access) ],
 291 \&    ':all'      => [ qw(:core :misc :cookie :header :push :debug :cgi\-lib
 292 \&                        :access :internal) ],
 293 \&    ':core'     => [ qw(param add_param param_fetch url_param keywords
 294 \&                        append Delete delete_all Delete_all upload
 295 \&                        query_string parse_query_string  parse_keywordlist
 296 \&                        Vars save_parameters restore_parameters) ],
 297 \&    ':misc'     => [ qw(url_decode url_encode escapeHTML unescapeHTML put) ],
 298 \&    ':cookie'   => [ qw(cookie raw_cookie) ],
 299 \&    ':header'   => [ qw(header cache no_cache redirect) ],
 300 \&    ':push'     => [ qw(multipart_init multipart_start multipart_end
 301 \&                        multipart_final) ],
 302 \&    ':debug'    => [ qw(Dump as_string cgi_error _cgi_object) ],
 303 \&    ':cgi\-lib'  => [ qw(ReadParse SplitParam MethGet MethPost MyBaseUrl MyURL
 304 \&                        MyFullUrl PrintHeader HtmlTop HtmlBot PrintVariables
 305 \&                        PrintEnv CgiDie CgiError Vars) ],
 306 \&    ':ssl'      => [ qw(https) ],
 307 \&    ':access'   => [ qw(version nph all_parameters charset crlf globals
 308 \&                        auth_type content_length content_type document_root
 309 \&                        gateway_interface path_translated referer remote_addr
 310 \&                        remote_host remote_ident remote_user request_method
 311 \&                        script_name server_name server_port server_protocol
 312 \&                        server_software user_name user_agent virtual_host
 313 \&                        path_info Accept http https protocol url self_url
 314 \&                        state) ],
 315 \&    ':internal' => [ qw(_initialize_globals _use_cgi_pm_global_settings
 316 \&                        _store_globals _reset_globals) ]
 317 \&    );
 318 .Ve
 319 .PP
 320 The familiar \s-1CGI\s0.pm tags are available but do not include the \s-1HTML\s0
 321 functionality. You specify the import of some function groups like this:
 322 .PP
 323 use CGI::Simple::Standard qw( :core :cookie :header );
 324 .PP
 325 Note that the function groups all start with a : char.
 326 .Sh "Mix and Match"
 327 .IX Subsection "Mix and Match"
 328 You can use the '\-autoload' pragma, specifically named function imports and
 329 tag group imports together if you desire.
 330 .ie n .SH "$POST_MAX and $DISABLE_UPLOADS"
 331 .el .SH "$POST_MAX and \f(CW$DISABLE_UPLOADS\fP"
 332 .IX Header "$POST_MAX and $DISABLE_UPLOADS"
 333 If you wish to set \f(CW$POST_MAX\fR or \f(CW$DISABLE_UPLOADS\fR you must do this *after* the
 334 use statement and *before* the first function call as shown in the synopsis.
 335 .PP
 336 Unlike \s-1CGI\s0.pm uploads are disabled by default and the maximum acceptable
 337 data via post is capped at 102_400kB rather than infinity. This is specifically
 338 to avoid denial of service attacks by default. To enable uploads and to
 339 allow them to be of infinite size you simply:
 340 .PP
 341 .Vb 2
 342 \&    $CGI::Simple::Standard::POST_MAX = \-1;         # infinite size upload
 343 \&    $CGI::Simple::Standard::$DISABLE_UPLOADS = 0;  # enable uploads
 344 .Ve
 345 .PP
 346 Alternatively you can specify the \s-1CGI\s0.pm default values as shown above by
 347 specifying the '\-default' pragma in your use statement.
 348 .PP
 349 .Vb 1
 350 \&    use CGI::Simple::Standard qw( \-default ..... );
 351 .Ve
 352 .SH "EXPORT"
 353 .IX Header "EXPORT"
 354 Nothing by default.
 355 .PP
 356 Under the '\-autoload' pragma the \s-1AUTOLOAD\s0 subroutine is
 357 exported into the calling namespace. Additional subroutines are only imported
 358 into this namespace if you physically call them. They are installed in the
 359 symbol table the first time you use them to save repeated calls to \s-1AUTOLOAD\s0.
 360 .PP
 361 If you specifically request a function or group of functions via an \s-1EXPORT_TAG\s0
 362 then stubs of these functions are exported into the calling namespace. These
 363 stub functions will be replaced with the real functions only if you actually
 364 call them saving wasted compilation effort.
 365 .SH "FUNCTION DETAILS"
 366 .IX Header "FUNCTION DETAILS"
 367 This is a wrapper module for CGI::Simple. Virtually all the methods available
 368 in the \s-1OO\s0 interface are available via the functional interface. Several
 369 method names are aliased to prevent namespace conflicts:
 370 .PP
 371 .Vb 4
 372 \&    $q\->delete('foo')   =>  Delete('foo')
 373 \&    $q\->delete_all      =>  Delete_all() or delete_all()
 374 \&    $q\->save(\e*FH)      =>  save_parameters(\e*FH)
 375 \&    $q\->accept()        =>  Accept()
 376 .Ve
 377 .PP
 378 Although you could use the \fInew()\fR function to genrate new \s-1OO\s0 CGI::Simple
 379 objects the \fIrestore_parameters()\fR function is a better choice as it operates
 380 like new but on the correct underlying CGI::Simple object for the functional
 381 interface.
 382 .PP
 383 \&\fIrestore_parameters()\fR can be used exactly as you might use \fInew()\fR in that
 384 you can supply arguments to it such as query strings, hashes and file handles
 385 to re-initialize your underlying object.
 386 .PP
 387 .Vb 4
 388 \&    $q\->new CGI::Simple()                => restore_parameters()
 389 \&    $q\->new CGI::Simple({foo=>'bar'})    => restore_parameters({foo=>'bar'})
 390 \&    $q\->new CGI::Simple($query_string)   => restore_parameters($query_string)
 391 \&    $q\->new CGI::Simple(\e*FH)            => restore_parameters(\e*FH)
 392 .Ve
 393 .PP
 394 For full details of the available functions see the CGI::Simple docs. Just
 395 remove the \f(CW$q\fR\-> part and use the method name directly.
 396 .SH "BUGS"
 397 .IX Header "BUGS"
 398 As this is 0.01 there are almost bound to be some.
 399 .SH "AUTHOR"
 400 .IX Header "AUTHOR"
 401 Dr James Freeman <jfreeman@tassie.net.au>
 402 This release by Andy Armstrong <andy@hexten.net>
 403 .PP
 404 This package is free software and is provided \*(L"as is\*(R" without express or
 405 implied warranty. It may be used, redistributed and/or modified under the terms
 406 of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)
 407 .PP
 408 Address bug reports and comments to: andy@hexten.net
 409 .SH "CREDITS"
 410 .IX Header "CREDITS"
 411 The interface and key sections of the CGI::Simple code come from
 412 \&\s-1CGI\s0.pm by Lincoln Stein.
 413 .SH "SEE ALSO"
 414 .IX Header "SEE ALSO"
 415 \&\*(L"CGI::Simple which is the back end for this module\*(R",
 416 \&\fB\s-1CGI\s0.pm by Lincoln Stein\fR