NAME

XML::Generator::Essex - 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( ... );

DESCRIPTION

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

Methods

put

   Example             What's emitted
   =======             ==============
   put;                ## (whatever's in $_: event, characters, etc)
   put "text<";        ## text&lt;
   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 don't modify events once they're 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.

Event Constructors

Each event can be constructed by calling the appropriate function or abbreviated function.

start_document

aka: start_doc

    start_doc \%values;  ## SAX does not define any %values.

end_document

aka: end_doc

    end_doc \%values;    ## SAX does not define any %values.

xml_decl

aka: no abbreviated form

    xml_decl
        Version    => 1,
        Encoding   => "UTF-8",
        Standalone => "yes";

    xml_decl {
        Version    => 1,
        Encoding   => "UTF-8",
        Standalone => "yes"
    };

start_element

aka: start_elt, start

    my $e = start "foo", { "attr" => "va1", ... };
    my $e = start $start_elt;   ## copy constructor
    my $e = start $elt;
    my $e = start $end_elt;

Stringifies like: <foo attr="val">

end_element

aka: end_elt, end

    my $e = end "foo";
    my $e = end $end_elt;   ## copy constructor
    my $e = end $start_elt; ## end for a given start_elt
    my $e = end $elt;       ## elt deconstructor

Stringifies like: </foo>

characters

aka: chars

    my $e = chars "foo", "bar";

Stringifies like the string it is: foobar

NOTE: the stringified form is not XML escaped.

LIMITATIONS

COPYRIGHT

    Copyright 2002, R. Barrie Slaymaker, Jr., All Rights Reserved

LICENSE

You may use this module under the terms of the BSD, Artistic, oir GPL licenses, any version.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>