fixed "attach_nodes" tests, documented it

3 files changed, 21 insertions, 6 deletions

diff --git a/lib/Tree/Template/Declare.pm b/lib/Tree/Template/Declare.pm
index 38f933c..151801a 100644
--- a/lib/Tree/Template/Declare.pm
+++ b/lib/Tree/Template/Declare.pm
@@ -64,7 +64,8 @@ sub _build_group {
                 local $current_node[0]=$node;
                 $_[0]->(caller_args(1));
             }
-            if ($current_node[0] && !defined wantarray) {
+            my $scalar_context=defined wantarray && !wantarray;
+            if ($current_node[0] && !$scalar_context) {
                 $builder->add_child_node($current_node[0],$node);
             }
             return $node;
@@ -86,6 +87,7 @@ sub _build_group {
             $builder->set_node_attributes($current_node[0],\%attrs);
             return;
         },
+        detached => sub($) { return scalar $_[0] },
     };
     if ($builder->can('_munge_exports')) {
         return $builder->_munge_exports($normal_exports,\@current_node);
@@ -137,11 +139,26 @@ Uses the builder's C<new_tree> and C<finalize_tree>.
 =head2 C<node>
 
 This function takes a code ref or a block, inside which calls to
-C<name>, C<attribs>, and C<node> should be made, and adds the node to
-the "calling" node or tree. It also returns the node.
+C<name>, C<attribs>, and C<node> should be made, and returns the node.
+
+If I<not> called in scalar context, it also adds the node to the
+"calling" node or tree.
 
 Uses the builder's C<new_node> and C<add_child_node>.
 
+=head2 C<detached>
+
+Alias for C<scalar>, so that you can say C<return detached node ...>
+without having to worry about the calling context.
+
+=head2 C<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 C<node> in scalar context.
+
+Uses the builder's C<add_child_node>.
+
 =head2 C<name>
 
 This function takes a scalar, and sets the name of the current node to
diff --git a/t/02-xslt.t b/t/02-xslt.t
index ac6bf42..d36c132 100644
--- a/t/02-xslt.t
+++ b/t/02-xslt.t
@@ -16,14 +16,12 @@ use warnings;
 
 tree_rule match => '/', action => sub {
     tree {
-        main::diag 'root';
         $_[0]->apply_rules;
     };
 };
 
 tree_rule match => '*', priority => 0, action => sub {
     node {
-        main::diag 'node '.$_[0]->it->name;
         name $_[0]->it->name;
         attribs %{$_[0]->it->attributes};
         $_[0]->apply_rules;
diff --git a/t/06-code.t b/t/06-code.t
index 959fce2..a37d0d3 100644
--- a/t/06-code.t
+++ b/t/06-code.t
@@ -8,7 +8,7 @@ use Data::Dumper;
 sub make_item {
     my ($name,$id)=@_;
 
-    return node {
+    return detached node {
         name 'item';
         attribs id => $id;
         node {