AZ::CGI - HTML forms and cookies parser

NAME

AZ::CGI - HTML forms and cookies parser

SYNOPSIS

  use AZ::CGI;
  $cgi = AZ::CGI->new();
  $cgi->set_GET(
      -incEmpty => $bool,         # No
      -cutNull  => $bool,         # Yes
      -maxLoops => $quantity      # 128
  );
  $cgi->set_COOKIE(
      -incEmpty => $bool,         # No
      -cutNull  => $bool,         # Yes
      -maxLoops => $quantity      # 128
  );
  $cgi->set_POST(
      -incEmpty   => $bool,       # No
      -cutNull    => $bool,       # Yes
      -maxLoops   => $quantity,   # 256
      -maxSize    => $size,       # 2Mb
      -maxKeySize => $size,       # 128b
      -maxValSize => $size        # 256Kb
  );
  $cgi->set_MULTI(
      -incEmpty   => $bool,       # No
      -cutNull    => $bool,       # Yes
      -maxLoops   => $quantity,   # 256
      -maxSize    => $size,       # 16Mb
      -maxKeySize => $size,       # 128b
      -maxValSize => $size,       # 256Kb
      -maxFiles   => $quantity    # 16
  );
  $cgi->GET($key,$number);
  $cgi->GET_is($key,$number);
  $cgi->GET_size($key);
  $cgi->GET_keys();
  $cgi->COOKIE($key);
  $cgi->COOKIE_is($key);
  $cgi->COOKIE_keys();
  $cgi->POST($key,$number);
  $cgi->POST_is($key,$number);
  $cgi->POST_size($key);
  $cgi->POST_keys();
  $cgi->FILE($key,$number)->name();
  $cgi->FILE($key,$number)->base();
  $cgi->FILE($key,$number)->temp();
  $cgi->FILE($key,$number)->mime();
  $cgi->FILE($key,$number)->size();
  $cgi->FILE_is($key,$number);
  $cgi->FILE_size($key);
  $cgi->FILE_keys();
  $cgi->env($key);
  $cgi->uri_encode($string);
  $cgi->uri_decode($string);

DESCRIPTION

This is Perl module for fastest and full securely parsing CGI query. POST query loading into memory only in parts, and, for this reason, module using little memory for parsing.

METHODS

new()
The constructor method instantiates a new AZ::CGI object.

DESTROY()
The destructor method cleaning up memory and deleting existings temporary files.

set_GET(-PARAM => VALUE, ...)
set_COOKIE(...)
set_POST(...)
set_MULTI(...)
Methods for changing settings of GET, COOKIE, POST and POST/multipart query's parsing.

Note: For a cancellation of action of -maxLoops, -maxSize, -maxKeySize, -maxValSize and -maxFiles parameters you can using value -1.

-incEmpty
Boolean value (1/0), include or not pairs with empty values. Allowed for all 4 methods. Default value is 0.

-cutNull
Boolean value (1/0), erase or not simbols with zero code from any places, where it needed. Allowed for all 4 methods. Default value is 1 and strongly not recommended to change this parameter!

-maxLoops
This is very important parameter. Defines limit for quantity of cycle iterations during parsing query. Usualy quantity of cycle iterations is equal to quantity of elements in HTML form, or some more. Allowed for all 4 methods. Default value for set_GET() and set_COOKIE() methods is 128, and for set_POST() and set_MULTI() methods is 256.

-maxSize
This method is used for definition maximal valid size in bytes for query. If query will have size more then this parameter, then this query will be ignored. Allowed for methods set_POST() and set_MULTI(). Default value for set_POST() method is 2Mb and for set_MULTI() method is 16Mb.

-maxKeySize
This method is used for definition maximal valid size in bytes for every key of pairs in query. If size of some keys will be more that size, then that pairs will be ignored. Allowed for methods set_POST() and set_MULTI(). Default value is 128.

-maxValSize
This method is used for definition maximal valid size in bytes for every value of pairs in query. If size of some values will be more that this size, then that values will be cuted off. Allowed for methods set_POST() and set_MULTI(). Default value is 256Kb.

-maxFiles
This method is used for definition maximal quantity of uploading files. Allowed for set_MULTI() method. Defalut value is 16.

Note: For size of files no limits.

Access to GET query pairs:
GET(KEY[,NUMBER])
Method returns value of specific by KEY and NUMBER pair. If NUMBER not exists, then default NUMBER zero will be used. If pair not exists, then returns empty string.

GET_is(KEY[,NUMBER])
Checking for pair existing. All as in previous method, only returns boolean (1/0) values. Value ``1'' if pair exists or ``0'' if not.

GET_size(KEY)
Returns size of array with pairs by using the KEY.

GET_keys()
Returns array with all keys.

Access to COOKIE's:
COOKIE(KEY)
All the same as GET() method. Only one difference, - no NUMBER argument.

COOKIE_is(KEY)
The same, but without NUMBER argument too.

COOKIE_keys()
Returns array with all keys.

Access to POST query pairs:
POST(KEY[,NUMBER])
POST_is(KEY[,NUMBER])
POST_size(KEY)
POST_keys()
All 4 method works the same as methods at GET structure.

Access to uploaded with POST(multipart) query files:
FILE_is(KEY[,NUMBER])
FILE_size(KEY)
FILE_keys()
This 3 methods works the same as methods at GET or POST structures.

FILE(KEY[,NUMBER])->name()
Returns file name if specific file exists. Otherwise returns empty string.

Note: Exists file or not, you can check by FILE_is() method.

FILE(KEY[,NUMBER])->base()
Returns base name of file if specific file exists. Otherwise returns empty string. Can't contains simbols ``/'', ``\'' and ``:''.

FILE(KEY[,NUMBER])->temp()
Returns real path to uploaded file, or empty string if file not exists.

FILE(KEY[,NUMBER])->mime()
Returns mime type of file. Can contains anything or nothing ;-)

FILE(KEY[,NUMBER])->size()
Size of file or 0 if file not exists or empty.

Utilites:
env(KEY)
Simple wrapper for array %ENV. Only one difference - never returns undef value. Can be handle for checking some values. Example: 
  if ($cgi->env("REQUEST_METHOD") eq "POST") {
      # ...
  }

uri_decode(STRING)
URL-formed strings decoder.

uri_encode(STRING)
URL-formed strings encoder.

UTF-8 SUPPORT

Returns only raw data. URL-encoded data in UTF-8 mode (%uXXXX) will be decoded correctly.

EBCDIC SUPPORT

No support. Only ACSII platforms supported.

REQUIREMENT

This module is required installed module AZ::Splitter version 0.60 or higher.

EXAMPLES

Simple HTML form:

  use AZ::CGI;
  my $cgi = AZ::CGI->new();
  print qq{Content-type: text/html\n\n};
  print qq{<HTML>\n};
  print qq{<BODY>\n};
  print qq{<FORM action="">\n};
  print qq{<P>Your name: <INPUT type=text name="name"></P>\n};
  print qq{<P><INPUT type=submit></P>\n};
  print qq{</FORM>\n};
  print qq{<P><HR></P>\n};
  if ($cgi->GET_is("name"))
  {
      my $name = $cgi->GET("name");
      print qq{<P>Your name: $name</P>\n};
  }
  print qq{</BODY>\n};
  print qq{</HTML>\n};

File upload:

  use AZ::CGI;
  my $cgi = AZ::CGI->new();
  print qq{Content-type: text/html\n\n};
  print qq{<HTML>\n};
  print qq{<BODY>\n};
  print qq{<FORM action="" method=POST enctype=multipart/form-data>\n};
  print qq{<P>Select file: <INPUT type=file name="file"></P>\n};
  print qq{<P><INPUT type=submit></P>\n};
  print qq{</FORM>\n};
  print qq{<P><HR></P>\n};
  if ($cgi->FILE_is("file"))
  {
      my $base = $cgi->FILE("file")->base();
      my $temp = $cgi->FILE("file")->temp();
      if (rename($temp,"/path/to/upload/$base"))
      {
          print qq{<P>File "$base" has uploaded successfuly!</P>};
      }
  }
  print qq{</BODY>\n};
  print qq{</HTML>\n};

Printing all pairs from some query (POST for example):

  use AZ::CGI;
  my $cgi = AZ::CGI->new();
  for my $key (sort $cgi->POST_keys()) {
    for my $number (0..$cgi->POST_size($key))
    {
        my $value = $cgi->POST($key,$number);
        print qq{<P>$key = "$value"</P>\n};
    }
  }

Special thanks too:

Green Kakadu <gnezdo@gmail.com>

AUTHOR

Andrian Zubko aka Ondr, <ondr@mail.ru>

 AZ::CGI - HTML forms and cookies parser