XML::Generator::Essex 0.01

XML::Generator::Essex is a Perl module that can generate XML with Essex.

SYNOPSIS

package My::Generator;

use XML::Generator::Essex;
@ISA = qw( XML::Generator::Essex );

use strict;

sub main { # Called by XML::Generator::Essex->generate().
my $self = shift;
}

## And, to use:

my $g = MY::Generator->new( Handler => $h );
$g->generate( ... );

Provides Essex output primitives like put() and constructors for essex events.

Methods

put

Example Whats emitted
======= ==============
put; ## (whatevers in $_: event, characters, etc)
put "text<"; ## text<
put [ a => "foo" ] ## < a >foo< /a >
put comment "foo"; ## < !--foo-- >
put $event; ## an event (see constructors below)
put $data; ## Emit a data structure
put @list; ## Emit multiple events and / or data structures

Emits one or more data structures as XML. Returns the result of emitting the last event (ie the result from the next SAX processor).

Most of the things you can pass to put (strings, constructed events) are relatively self evident.

For instance, you can pass any events you construct, so an Essex script to make sure all character data is emitted in CDATA sections might look like:

get( "text()" ), put cdata $_ while 1;

A less obvious feature is that you can pass a (possibly nested) Perl ARRAY that defines an XML tree to emit:

put [
root => { id => 1 }, ## HASHes contain attributes
"root content",
[ a => "a content" ],
"more root content",
[ b => { id => 2 }, "b content" ],
];

will emit the SAX events corresponding to the XML (whitespace added for legibility):

< root id="1" >
root content
< a >a content< /a >
more root content
< b id="2" >b content< /b >
< /root >

NOTE: this does not allow you to control attribute order.

By using the DOM constructors, you could also write the above as:

put elt(
root => { id => 1 }, ## HASHes contain attributes
"root content",
elt( a => "a content" ),
"more root content",
elt( b => { id => 2 }, "b content" ),
];

to emit the XML < root id="1" >< !--comment-- >content< /root >.

You can actually pass any blessed object to put() that provides a generate_SAX() method. This will be called with the results of $self->get_handler() (which may be undefined) and should return a TRUE if the handler is undefined or if no events are sent. If any events are sent, it should return the result of the last event.

See XML::Essex::Model for some more examples.

put() is a bit DWIMy: it will fill in the name of end_elements for you if you leave them out:
put start "foo";
...
put end;

It will also die() if you emit the wrong end_elt for the currently open element (it keeps a stack), or if you emit and end_document without emitting end_elements. You can catch this error and put() the proper end_element events if you like.

If the filter exits after half-emitting a document and does not set a result, an error is emitted. This is to notify you that a document was half-emitted. die() to get around this.

Note that downstream filters are free to cache things you send, so dont modify events once theyre sent. If you need to do that, send a copy and modify the original.

output_monitor

Returns a handle to the output monitor. See XML::Essex::Filter::OutputMonitor for details.