/ 
Tree-Template-Declare-0.5
River stage zero No dependents
/ Tree::Template::Declare

NAME

Tree::Template::Declare - easily build tree structures

SYNOPSIS

use Tree::Template::Declare builder => '+DAG_Node';

my $tree=tree {
    node {
        name 'root';
        attribs name => 'none';
        node {
            name 'first';
            attribs name => 'number_1';
            attribs other => 'some';
        };
        node {
            name 'second';
        };
    };
};

FUNCTIONS

For details on the implementation of these functions, see the "BUILDER" section, and the documentation of your chosen builder.

tree

This function takes a code ref or a block, inside which calls to node should be made, and returns a properly constructed tree containing those nodes.

Uses the builder's new_tree and finalize_tree.

node

This function takes a code ref or a block, inside which calls to name, attribs, and node should be made, and returns the node.

If not called in scalar context, it also adds the node to the "calling" node or tree.

Uses the builder's new_node and add_child_node.

detached

Alias for scalar, so that you can say return detached node ... without having to worry about the calling context.

attach_nodes

This function takes a list of nodes, and adds them (in order) to the "calling" node or tree. You should only use this with nodes you obtained by calling node in scalar context.

Uses the builder's add_child_node.

name

This function takes a scalar, and sets the name of the current node to the value of that scalar.

Uses the builder's set_node_name.

attribs

This function takes a hash (not a hash ref), and sets the attributes of the current node.

Uses the builder's set_node_attributes.

BUILDER

To actually create nodes and trees, this module uses helper classes called "builders". You must always specify a builder package, class or object with the builder option in the use line.

If the builder is an object, the methods discussed below will be called on it; if it's a class (i.e. a package that has a new function), they will be called on an instance created by calling new without parameters; otherwise they will be called as class methods.

The builder must implement these methods:

new_tree
$tree = $current_node = $builder->new_tree();

returns a tree object; that object will be set as the current node within the code passed to the tree function

finalize_tree
return $builder->finalize_tree($tree);

this function will be passed the object returned by new_tree, after the code passed to tree has been executed; the result of finalize_tree will be the result of tree

new_node
$current_node=$builder->new_node();

returns a new, unattached node

set_node_name
$builder->set_node_name($current_node, $name);

sets the name of the node (e.g. for SGML-like trees, this is the "tag name")

set_node_attributes
$builder->set_node_attributes($current_node, \%attribs);

sets attributes of the node; it should not remove previously-set attributes

add_child_node
$builder->add_child_node($parent_node, $child_node);

adds the second node at the end of the children list of the first node

The builder can also implement an _munge_exports method. If it does, _munge_exports will be called with:

  • a hash ref consisting of the functions that Tree::Template::Declare wants to export,

  • an array ref, whose first element will be the current node whenever the user calls an exported function

_munge_exports should return a hash ref with the functions that will actually be exported.

See Sub::Exporter, in particular the section on group builders, for details. See Tree::Template::Declare::HTML_Element and Tree::Template::Declare::LibXML for examples.

IMPORTING

This module uses Sub::Exporter, although it munges the use list before passing it to Sub::Exporter. A line like:

use Tree::Template::Declare @something;

becomes a call to Sub::Exporter's export sub like:

$export->('Tree::Template::Declare',-default => {@something});

See Sub::Exporter's documentation for things like renaming the imports.

You can use this module more than once, with different builders and different names for the imports:

use Tree::Template::Declare -prefix=> 'x', builder => '+LibXML';
use Tree::Template::Declare -prefix=> 'd', builder => '+DAG_Node';

KNOWN ISSUES & BUGS

  • _munge_exports is ugly

  • the context-sensitivity of node might not be the best way to DWIM for the creation of detached nodes

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>