docs, and changed the export-munging methods for builders

3 files changed, 105 insertions, 2 deletions

diff --git a/lib/Tree/Template/Declare/DAG_Node.pm b/lib/Tree/Template/Declare/DAG_Node.pm
index 806413d..2736a5f 100644
--- a/lib/Tree/Template/Declare/DAG_Node.pm
+++ b/lib/Tree/Template/Declare/DAG_Node.pm
@@ -54,3 +54,31 @@ sub set_node_attributes {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Tree::Template::Declare::DAG_Node
+
+=head1 SYNOPSIS
+
+See L<Tree::Template::Declare>.
+
+=head1 SPECIFICITIES
+
+This module will build trees using L<Tree::DAG_Node>. You can make it
+use another module (assuming it has the same interface, for example
+L<Tree::DAG_Node::XPath>) by passing the class name to the C<new>
+method.
+
+ use Tree::Template::Declare builder => '+DAG_Node'; # default
+
+ use Tree::Template::Declare builder =>
+     Tree::Template::Declare::DAG_Node->new('Tree::DAG_Node::XPath');
+     # custom class
+
+=head1 AUTHOR
+
+Gianni Ceccarelli <dakkar@thenautilus.net>
+
+=cut
diff --git a/lib/Tree/Template/Declare/HTML_Element.pm b/lib/Tree/Template/Declare/HTML_Element.pm
index 1480987..c2dd87c 100644
--- a/lib/Tree/Template/Declare/HTML_Element.pm
+++ b/lib/Tree/Template/Declare/HTML_Element.pm
@@ -10,6 +10,21 @@ sub new {
     return bless {},$class;
 }
 
+sub _munge_exports {
+    my ($self,$exports)=@_;
+
+    return {
+        %$exports,
+        text_node => sub($) {
+            $exports->{node}->(
+                sub {
+                    $exports->{name}->('~text');
+                    $exports->{attribs}->(text => $_[0]);
+                });
+        },
+    };
+}
+
 sub new_tree {
     my ($self)=@_;
 
@@ -57,3 +72,36 @@ sub set_node_attributes {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Tree::Template::Declare::HTML_Element
+
+=head1 SYNOPSIS
+
+See L<Tree::Template::Declare>.
+
+=head1 SPECIFICITIES
+
+This module will build trees using L<HTML::Element>.
+
+To create text nodes, you would be forced to say:
+
+  node {
+    name '~text';
+    attribs text => 'some text';
+  }
+
+which is too cumbersone. You can instead use:
+
+  text_node 'some text';
+
+HTML::Element's C<deobjectify_text> method will be called by
+C<finalize_tree> before returning the tree object.
+
+=head1 AUTHOR
+
+Gianni Ceccarelli <dakkar@thenautilus.net>
+
+=cut
diff --git a/lib/Tree/Template/Declare/LibXML.pm b/lib/Tree/Template/Declare/LibXML.pm
index f8c0e01..d5e208c 100644
--- a/lib/Tree/Template/Declare/LibXML.pm
+++ b/lib/Tree/Template/Declare/LibXML.pm
@@ -10,10 +10,11 @@ sub new {
     return bless {ns=>{':default'=>undef}},$class;
 }
 
-sub _additional_exports {
-    my ($self)=@_;
+sub _munge_exports {
+    my ($self,$exports)=@_;
 
     return {
+        %$exports,
         xmlns => sub($$) {
             $self->{ns}->{$_[0]}=$_[1];
             return;
@@ -95,3 +96,29 @@ sub set_node_attributes {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Tree::Template::Declare::LibXML
+
+=head1 SYNOPSIS
+
+See L<Tree::Template::Declare>.
+
+=head1 SPECIFICITIES
+
+A function C<xmlns> is exported, so that you can declare XML namespaces:
+
+  xmlns test => 'http://test/';
+
+  node { name 'test:elem'; attribs id => 1, 'test:attr' => 5 };
+
+You I<can> create nodes with qualified names with undeclared prefixes,
+but it's probably not a good idea.
+
+=head1 AUTHOR
+
+Gianni Ceccarelli <dakkar@thenautilus.net>
+
+=cut