NAME

CGI::Deurl.pm - a CGI parameter decoding package

version 1.08

SYNOPSIS

 use CGI::Deurl as => 'q';
 ...
 print "$q{ParamName}\n";

DESCRIPTION

This is a little module made for CGI scripting. It decodes the parameters passed to the CGI. It does nothing more, so it's much smaller and loads more quickly than CGI.pm.

Since version 0.04 it also exports the deurl, deurlstr and deurlarr functions so that you are able to decode not only the parameters your CGI got, but also an arbitrary string.

Reading CGI query

The module can take the arguments from several sources. CGI::Deurl tests the environmental variable 'REQUEST_METHOD' to find the arguments.

REQUEST_METHOD=POST

CGI::Deurl slurps in it's STDIN and parses it, then it tests $ENV{QUERY_STRING} and if defined parses the data as well.

REQUEST_METHOD=GET

 CGI::Deurl reads $ENV{QUERY_STRING} and parses the contents.

REQUEST_METHOD not defined

CGI::Deurl tests ARGV and parses all it's arguments. If it didn't find any args it reads it's STDIN line by line until EOF and parses all the lines. This is handy if you want to test a CGI script from command prompt. You may specify the parameters either on the command line or enter them after the script starts to run.

If you use CGI::Deurl NOTCGI; the module doesn't look for the parameters and just exports the functions. This is handy if you use CGI::Deurl.pm in a script that is not a CGI.

Using query variables

The data are stored in a hash %CGI::Deurl::query, but CGI::Deurl provides two ways to specify otherwise. They may be stored either in a hash you specify or be exported into a package.

``use'' statement options

lc

If you use the option 'lc' all names of the parameters are converted to lowercase. This way you may get case insensitive parameters.

uc

This option is similar to 'lc'. It converts the names to uppercase.

as variable

If you use CGI::Deurl qw(as variablename); CGI::Deurl uses variable %variablename from package main to store the data (%CGI::Deurl::query works as well, this is just a nickname).

use CGI::Deurl export;

All the query variables are exported into package CGI::Deurl. That means that if the query was ``?x=5&y=24'', you can use $CGI::Deurl::x + $CGI::Deurl::y. Again %CGI::Deurl::query works as usual.

use CGI::Deurl export Package;

All the query values are exported into Package. That means that if the query was ``?x=5&y=24'', you can use $Package::x + $Package::y. Again %CGI::Deurl::query works as usual.

use CGI::Deurl NOTCGI;

Do not read any query. This option should be first or directly after the &=....

use CGI::Deurl '&=.'

You may change the character used to separate the parameters. Use any character or string you want. This must be the first option if present!

The parameter separator is stored in variable $CGI::Deurl::ParamSeparator. You may change it any time you want.

use CGI::Deurl 'JOIN' => ';';

use CGI::Deurl 'JOIN' , 'file' => ';', '-all' => ',';

This option will cause a call to joinquery(), all folowing arguments will be passed to this function, so this switch has to be the last one!

Parsing query

If the argument in the query in in the form ``name=value''. $CGI::Deurl::query{name} is set to value. If it is just ``value'' (say myscript.pl?one&two), $CGI::Deurl::query{0}='one' and $CGI::Deurl::query{1}='two'. These kinds of parameters can be intermixed.

If there is more than one occurence of a variable, $CGI::Deurl::query{name} contains a refference to an array containing all the values.

 Ex.
   ?x=one&y=two&x=three
  =>
   $CGI::Deurl::query{x}=['one','three'];
   $CGI::Deurl::query{y}='two';

!!! If you 'export' such a variable it's not exported as a refference but as a real array!!!

 That is if you use CGI::Deurl qw(export CGI::Deurl) you will get :
    @CGI::Deurl::x = ('one','three');
    $CGI::Deurl::y = 'two';

! All changes made to $CGI::Deurl::variable are visible in $CGI::Deurl::query{variable} and vice versa.

Functions

deurl

deurl $string, \%hash

Decodes the string as if it was an ordinary CGI query. The %hash then contains all CGI parameters specified there.

 Ex.
   deurl('a=5&b=13',\%query);
  leads to :
   $query{a} = 5;
   $query{b} = 13;

deurlstr

$decodedstring = deurlstr $string

Decodes the string as if it was a CGI parameter value. That is ist translates all '+' to ' ' and all %xx to the corresponding character. It doesn't care about '&' nor '='.

 Ex.
   $result = deurlstr 'How+are+you%3F';
  leads to:
   $result = 'How are you?'
  !!! but notice that !!!
   $result = deurlstr('a=5&b=13%25');
  gives:
   $result = 'a=5&b=13%'
  !!!!!!

deurlarr

@result = deurlarr $string;

Decodes the string as a sequence of unnamed CGI parameters, that is it supposes that the $string looks somehow like this : 'param1&param2&par%61m3'. It doesn't care about '='

 Ex.
   @result = deurlarr 'How&are+you%3f';
  leads to
   @result = ( 'How', 'are you?');

   @result = deurlstr('a=5&b=13%25');
  gives:
   @result = ( 'a=5', 'b=13%');
  which may but may not be what you want.

CGI::Deurl::load

Instructs CGI::Deurl to load the CGI data from QUERY_STRING, @ARGV or <STDIN>. The parameters are the same as for the use CGI::Deurl ...; Usefull only if you use CGI::Deurl NOTCGI;, but later on you find out you want the CGI parameters.

joinquery %query, $delimiter

joinquery %query, $key => $delimiter [, ...]

If the query contains several values for a singe variable, these values are stored as an array in the hash. This function joins them using the delimiter you specify. You may either join all the keys using the same delimiter, or use different delimiters for each key. You may even leave some values intact.

 Ex.:
  joinquery %query, $delimiter
    it will join all multivalues it finds using the $delimiter.

  joinquery %query, 'key' => $delimiter
    it will join only the multivalue for 'key'. All other values will remain
    the same.

  joinquery %query, 'key' => ';', '-all' => ' '
    it will join the multivalue for 'key' by semicolons. All other values will
    be joined using spaces.

You may call this function from the ``use'' statement.

$CGI::Deurl::offline

If the script was called from the command line instead of as a CGI, this variable contains 1. Otherwise it's undefined.

AUTHOR

Jenda@Krynicky.cz