NAME

YAX::Builder - Declarative programmatic DOM construction

SYNOPSIS

 use YAX::Builder;
 my $elmt = YAX::Builder->node([ $name, @kids ]);
 my $elmt = YAX::Builder->node([ $name, \%atts, @kids ]);

 my @nodes = YAX::Builder->build([ $name1, ... ], [ $namen, ... ]);

 my $text = YAX::Builder->text( $data );
 my $elmt = YAX::Builder->element( $name, %atts );
 my $frag = YAX::Builder->fragment( @kids );

DESCRIPTION

This module implements a builder for creating DOM trees in a declarative way (meaning you specify what the shape of the tree fragment is without specifying how it is constructed) using a terse, array reference based syntax. For example to following:

 my $node = YAX::Builder->node(
     [ div => { class => 'fancy' },
         [ a => { href => 'http://www.example.com' }, 'Click Me!' ]
     ]
 );

gives you the structure:

 <div class="fancy"><a href="http://www.example.com">Click Me!</a></div>

There are a few simple rules to the structure of an element descriptor (a Text::Node descriptor is simply a string):

The first element must be a string and is taken as the tag name. The second element is an optional hash reference which is the attributes. If the attributes hash reference is not present, then the child nodes start at the second element. Anything else is a child. Plain text is turned into YAX::Text nodes. Examples:

 $n = YAX::Builder->node([ 'div' ])
 $n = YAX::Builder->node([ 'div', { class => 'fancy' }, "Text content" ])
 $n = YAX::Builder->node([ 'div', "Text content 1" ])
 $n = YAX::Builder->node([ 'div', [ 'em', "emphasized" ], $a_node ])

METHODS

node( $spec )

Takes an array reference as described above or a single string and returns either a YAX::Element node, or a YAX::Text node respectively.

text( $text )

Takes a text string and returns a YAX::Text node.

build( @specs )

Takes a list of descriptors and returns a list of nodes. In a scalar context returns only the first node.

fragment( @specs )

Takes a list of descriptors and returns a YAX::Fragment.

ACKNOWLEDGEMENTS

This module was inspired by HTML::Builder.

AUTHOR

 Richard Hundt

SEE ALSO

YAX::Element, YAX::Text, YAX::Fragment

LICENSE

This program is free software and may be modified and distributed under the same terms as Perl itself.