Tree::Template::Declare - easily build tree structures
version 0.7
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'; }; }; };
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.
node
Uses the builder's new_tree and finalize_tree.
new_tree
finalize_tree
This function takes a code ref or a block, inside which calls to name, attribs, and node should be made, and returns the node.
name
attribs
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.
new_node
add_child_node
detached
Alias for scalar, so that you can say return detached node ... without having to worry about the calling context.
scalar
return detached node ...
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.
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.
set_node_name
This function takes a hash (not a hash ref), and sets the attributes of the current node.
Uses the builder's set_node_attributes.
set_node_attributes
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.
builder
use
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.
new
The builder must implement these methods:
$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
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
$current_node=$builder->new_node();
returns a new, unattached node
$builder->set_node_name($current_node, $name);
sets the name of the node (e.g. for SGML-like trees, this is the "tag name")
$builder->set_node_attributes($current_node, \%attribs);
sets attributes of the node; it should not remove previously-set attributes
$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
a hash ref consisting of the functions that Tree::Template::Declare wants to export,
Tree::Template::Declare
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.
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';
_munge_exports is ugly
the context-sensitivity of node might not be the best way to DWIM for the creation of detached nodes
Gianni Ceccarelli <dakkar@thenautilus.net>
This software is copyright (c) 2015 by Gianni Ceccarelli <dakkar@thenautilus.net>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Tree::Template::Declare, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tree::Template::Declare
CPAN shell
perl -MCPAN -e shell install Tree::Template::Declare
For more information on module installation, please visit the detailed CPAN module installation guide.