Gianni Ceccarelli > Tree-Template-Declare-0.4 > Tree::Template::Declare

Download:
Tree-Template-Declare-0.4.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.4   Source   Latest Release: Tree-Template-Declare-0.5

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:

_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 ^

AUTHOR ^

Gianni Ceccarelli <dakkar@thenautilus.net>

syntax highlighting: