fixed "attach_nodes" tests, documented it

1 files changed, 20 insertions, 3 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