NAME

XML::Handler::EasyTree::Generator - Perl extension for generating EasyTree structures

SYNOPSIS

  use XML::Handler::EasyTree::Generator;
  
  $e = XML::Handler::EasyTree::Generator->new('t' => '_t',
        'pi' => '_pi', 'c' => '_c');
  
  $hashref = $e->AUTOLOAD(\%args, @content);
  $hashref = $e->AUTOLOAD(@content);
  $hashref = $e->_t(@content);                           # make a text node
  $hashref = $e->_c(@content);                           # make a comment node
  $hashref = $e->_pi({'target' => $target}, @content);   # make a pi node
  $hashref = $e->_pi($target, @content);                 # make a pi node
  
  $hashref = &XML::Handler::EasyTree::Generator::AUTOLOAD(\%args, @content);

DESCRIPTION

This module provides a way to create EasyTree structures on the fly. For more about EasyTree structures see XML::Parser::EasyTree or XML::Handler::Trees. The interface resembles the autoloader in CGI.pm. I've chosen to get rid of the leading hyphen for arguments/attributes; if you'd like to see them added in, I suppose I can add a regex to remove them :-)

If any errors are encountered the functions will return false and the error will be stored in $XML::Handler::EasyTree::Generator::error.

CAVEAT

I've noticed that XML::Parser::EasyTree (or XML::Parser or libexpat1) does a few "interesting" things with parsing input. I haven't checked yet to see if XML::Handler::Trees or its dependencies do the same. This module does allow for generating some output that is non-cannonical by those standards, but largely this shouldn't be a problem. Where non-cannonical abilities are granted they'll be noted.

One example is unary vs empty tags. The parser reads them in as the same, but you can generate them differently for output. In the potentially forthcoming XML::Handler::EasyTree::Searchable::Extended (I haven't checked other modules yet) an element node with no content is considered unary whereas one with a null content ('') text node is considered binary but empty.

A more dangerous example is generating comment nodes. Comments are usually ignored by the parser. As such, functions that flatten EasyTree structures may croak on comment nodes.

EXPORT

None by default. None possible for now.

FUNCTIONS

XML::Handler::EasyTree::Generator->new(['t' => $name][, 'pi' => $name][, 'c' => $name])

This method creates a new object which lets you use the autoloader below in object-oriented fashion. By default the autoloader will create element nodes.

Since tag names are extensible, we need special names for other node types. Rather than enforcing a specific special name, you can specify what names you would like to be set aside for text, parser-instruction, and comment nodes. By default these are '_t', '_pi', and '_c' respectively. With the function oriented autoloader there's no way to change these defaults.

N.B. comment nodes are non-cannonical and may cause functions that turn EasyTree structures into XML text to croak.

$easytreetools_obj->AUTOLOAD([\%args,] @content)

&XML::Handler::EasyTree::Generator::AUTOLOAD([\%args,] @content)

This function set allows you to create an EasyTree node in a manner similar to that used in CGI.pm for creating HTML nodes. It can be used either as a function or as a method.

The initial hashref of attribute/value pairs is optional. If it is present for text or comment nodes it is discarded. If it is present for PI nodes, the 'target' value is taken if present, all other values are discarded. If the target cannot be taken from the %args hash, the first element of @content is assumed to be the target.

For element nodes the @content array can contain either scalars which are interperated as text nodes, or can contain hashrefs which are assumed to be EasyTree nodes. For non-element nodes the @content array is join('')ed, sans the target for PI nodes as appropriate.

If you want to use a namespace for an element, surround it with underscores as so: _namespace__tagname() and the function will deal with the rest. Single underscores are allowed in namespaces or tagnames; double underscores are not allowed in namespaces. It's convoluted, but it doesn't severely limit your choices of tag names and allows namespaces so we can deal with it.

BUGS AND ISSUES

Actual resolved namespaces aren't yet supported. Namespaces lead to a node with the name 'namespace:tagname' just as if you have namespace resolving turned off.

SEE ALSO

XML::Parser::EasyTree, XML::Handler::Trees, XML::Handler::EasyTree::Searchable::Extended

Not specific to this module, but post discussion to perl-xml@listserv.ActiveState.com

AUTHOR

wren ng thornton, <wren@cpan.org> http://llama.freegeek.org/~wren/

COPYRIGHT AND LICENSE

Copyright (C) 2004~2006 by wren ng thornton. ALL RIGHTS RESERVED.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.

Version History

v0.0

• Tried better to make v0.02 updates consistent in meta files. (v0.03)

• Updated author's name and contact info. (v0.02)

• Initial release. (v0.01)