NAME

XML::SAX::Builder - build XML documents using SAX

SYNOPSIS

  my $x = XML::SAX::Builder->new;
  $x->xml( $x->foo( 'bar' ) );

  # Produces:
  # <foo>bar</foo>

  $x->xml( $x->foo( { id => 1 }, 'bar' ) );

  # Produces:
  # <foo id='1'>bar</foo>

  $x->xml( $x->foo( $x->bar(1), 'middle', $x->baz ) );

  # Produces:
  # <foo><bar>1</bar>middle<baz /></foo>

  $x->xml( $x->xmlns( '' => 'urn:foo', $x->foo( 'bar' ) ) );

  # Produces:
  # <foo xmlns='urn:foo'>bar</foo>

  my $pfx = $x->xmlprefix( 'pfx' );
  $x->xml( $x->xmlns( foo => 'urn:foo', $pfx->foo( 'bar' ) ) );

  # Produces:
  # <pfx:foo xmlns:pfx='urn:foo'>bar</pfx:foo>

DESCRIPTION

This module is a set of classes to allow easy construction of XML documents, in particular in association with an XML::SAX pipeline. The default is to output the XML to stdout, although this is easily changed.

METHODS

new ( [ HANDLER ] )

Return a new builder object. Optionall, a SAX HANDLER may be passed in. If none is passed in, the default is to use an XmL::SAX::Writer instead. The default configuration for XML::SAX::Writer sends XML to STDOUT. If you wish to get XML sent elsewhere, supply your own XML::SAX::Writer object.

element ( [ [ ATTRS ], OBJ, ... ] )

Any element may be produced by calling it as a method on the Builder object. Each argument may be a previously created element, or a piece of text.

Optionally, the first argument may be a hash reference. If so, it will be used as a list of attributes for the element.

xml ( OBJECT )

Calling this method actually creates the XML document. That is to say, it fires all the handlers for the objects that have been built up and passed in. No XML will be output until this method has been called.

xmlns ( PREFIX, URI, CHILD )

This method inserts a new namespace into the resulting XML. PREFIX and URI are the namespace prefix and uri. CHILD is either an element object, or another namespace object.

xmlcdata ( TEXT, [ TEXT ] )

Inserts all arguments concatenated together inside a <![CDATA block.

xmldtd ( ELEMENT, SYSTEM [, PUBLIC ] )

Insert a DOCTYPE declaration into the resulting XML. You have to specify ELEMENT as the top level element name.

xmlcomment ( TEXT )

Inserts TEXT as an XML comment.

xmlpi ( TARGET, DATA )

Inserts TARGET and DATA as a processing instruction.

xmlprefix ( PREFIX )

Returns a new instance of XML::SAX::Builder, which will automatically prefix all element names with PREFIX. This can then be used in place of the original builder object where needed. The Handler will be copied from original builder object.

NB: It's still up to you to ensure that the prefix you're using is valid according to the current namespace scope! What that means: If you're thinking of using this function without calling xmlns() nearby, you'll lose.

TODO

CDATA doesn't work at present, because XML::Filter::BufferText, which is used by XML::SAX::Writer, gets it wrong (inheritance & AUTOLOAD - always a bad mix :).

Having to specify the top level element name to the doctype is nasty, but I can't see an obvious way to automatically pick it up right now.

You can't have a tag called DESTROY.

SEE ALSO

XML::SAX, XML::SAX::Writer.

Alternative XML document constructors: XML::SAX::Generator, XML::Writer.

AUTHOR

Dominic Mitchell, <cpan@semantico.com>

COPYRIGHT AND LICENSE

Copyright 2003 semantico

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.