NAME

XML::Generator::CGI - Generate SAX2 Events from CGI objects

SYNOPSIS

use XML::Generator::CGI;
use XML::Handler::YAWriter; # Or any other upstream XML filter
use CGI;

my $ya = XML::Handler::YAWriter->new( AsString => 1 );
my $cx = XML::Generator::CGI->new( Hanlder => $ya, <other options> );

my $q = new CGI;
my $xml = $cx->parsecgi( $q );

# OR

my $xml = $cx->parsecgi();

DESCRIPTION

XML::Generator::CGI is a SAX event generator for CGI objects. Both name/parameter sets and cookies are enumated in the resulting XML. By default, and after appropriate parsing by additional handlers, the resulting XML will look similar to:

<cgi generator="XML::Generator::CGI" version="0.01">
  <parameter name="dino">
    <value>Barney</value>
    <value>TRex</value>
  </parameter>
  <parameter name="color">
    <value>purple</value>
  </parameter>
  <cookie name="ticket">123ABC</cookie>
</cgi>

though aspects of this structure can be changed by the user. Parameters and multivalues will be returned in the order that CGI normally returns these.

API

XML::Generator::CGI->new( <options> )

Creates a new generator object. Options are passed in as key-value sets, and as this class inherits from XML::SXL::Base, any addition options that work there can be accepted here.

Handler (required, no default)

The hanlder that the SAX events will be passed to.

RootElement (optional, default: 'cgi')

The name of the root element tag that will be created in the SAX events.

ParameterElement (optional, default: 'parameter')

The name of the parameter element tags. The name attribute of these tags will contain the paramter name itself.

ValueElement (optional, default: 'value')

The name of the value element tags. One of these tags is generated as a child of the parameter element for each value that is returns from the CGI object. The value is stored as the character data between this tag.

CookieElement (optional, default: 'cookie')

The name of the cookie element tags. The name attribute of these tags will contain the name of the cookie. The data inside these tags will be the value of the cookie.

Cookies (optional, default: 1 (enabled))

If set true, then the cookies from the CGI will be included in the output of SAX events, otherwise they will be ignored.

Include (optional, no default, list)

A list of parameter names that only should be included in the resulting SAX events. Parameter names that are not on this list will not be included.

Exclude (optional, no default, list)

A list of parameters names that should never be included in the resulting SAX events. Parameter names that are not on this list will be included. Note that Include and Exclude should be considered mutually exclusive, with the Excluded list removed first, following by the limitation of the include list.

parsecgi( <CGI object> | <query_string> | undef )

Generates SAX events depending on the passed object. If the passed object is a CGI object, then processing is done on that. If this is not the case, but an argument is still passed, then the object will be treated as a query string, converted into a CGI object, and parsed appropriately. Finally if no object is passed, then a new CGI object is created in the current environment, which may be useful in a web application.

EXPORT

None by default.

AUTHOR

Michael K. Neylon, <mneylon-pm@masemware.com>

SEE ALSO

perl, CGI, XML::SAX::Base.