NAME

       Pod::Abstract::Node - Pod Document Node.

SYNOPSIS

        $node->nest( @list );          # Nests list as children of $node. If they
                                       # exist in a tree they will be detached.
        $node->clear;                  # Remove (detach) all children of $node
        $node->hoist;                  # Append all children of $node after $node.
        $node->detach;                 # Detaches intact subtree from parent
        $node->select( $path_exp );    # Selects the path expression under $node
        $node->select_into( $target, $path_exp );
                                       # Selects into the children of the
                                       # target node.  (copies)

        $node->insert_before($target); # Inserts $node in $target's tree
                                       # before $target
        $node->insert_after($target);

        $node->push($target);          # Appends $target at the end of this node
        $node->unshift($target);       # Prepends $target at the start of this node

        $node->path();                 # List of nodes leading to this one
        $node->children();             # All direct child nodes of this one
        $node->next();                 # Following sibling if present
        $node->previous();             # Preceding sibling if present

        $node->duplicate();            # Duplicate node and children in a new tree.

        $node->pod;                    # Convert node back into literal POD
        $node->ptree;                  # Show visual (abbreviated) parse tree

METHODS

   new
        my $node = Pod::Abstract::Node->new(
           type => ':text', body => 'Some text',
        );

       Creates a new, unattached Node object. This is NOT the recommended way to make nodes to
       add to a document, use Pod::Abstract::BuildNode for that. There are specific rules about
       how data must be set up for these nodes, and "new" lets you ignore them.

       Apart from type and body, all other hash arguments will be converted into "params", which
       may be internal data or node attributes.

       Type may be:

       •   A plain word, which is taken to be a command name.

       •   ":paragraph", ":text", ":verbatim" or <:X> (where X is an inline format letter). These
           will be treated as you would expect.

       •   "#cut", meaning this is literal, non-pod text.

       Note that these do not guarantee the resulting document structure will match your types -
       types are derived from the document, not the other way around. If your types do not match
       your document they will mutate when it is reloaded.

       See Pod::Abstract::BuildNode if you want to make nodes easily for creating/modifying a
       document tree.

   ptree
        print $n->ptree;

       Produces a formatted, readable, parse tree. Shows node types, nesting structure,
       abbreviated text. Does NOT show all information, but shows enough to help debug
       parsing/traversal problems.

   text
        print $n->text;

       Returns the text subnodes only of the given node, concatenated together - i,e, the text
       only with no formatting at all.

   pod
        print $n->pod;

       Returns the node (and all subnodes) formatted as POD. A newly loaded node should produce
       the original POD text when pod is requested.

   select
        my @nodes = $n->select('/:paragraph[//:text =~ {TODO}]');

       Select a pPath expression against this node. The above example will select all paragraphs
       in the document containing 'TODO' in any of their text nodes.

       The returned values are the real nodes from the document tree, and manipulating them will
       transform the document.

   select_into
        $node->select_into($target_node, $path)

       As with select, this will match a pPath expression against $node - but the resulting nodes
       will be copied and added as children to $target_node. The nodes that were added will be
       returned as a list.

   type
        $node->type( [ $new_type ] );

       Get or set the type of the node.

   body
        $node->body( [ $new_body ] );

       Get or set the node body text. This is NOT the child tree of the node, it is the literal
       text as used by text/verbatim nodes.

   param
        $node->param( $p_name [, $p_value ] );

       Get or set the named parameter. Any value can be used, but for document attributes a
       Pod::Abstract::Node should be set.

   duplicate
        my $new_node = $node->duplicate;

       Make a deep-copy of the node. The duplicate node returned has an identical document tree,
       but different node identifiers.

   insert_before
        $node->insert_before($target);

       Inserts $node before $target, as a sibling of $target. If $node is already in a document
       tree, it will be removed from it's existing position.

   insert_after
        $node->insert_after($target);

       Inserts $node after $target, as a sibling of $target. If $node is already in a document
       tree, it will be removed from it's existing position.

   hoist
        $node->hoist;

       Inserts all children of $node, in order, immediately after $node. After this operation,
       $node will have no children. In pictures:

        - a
         - b
         - c
          - d
        -f

        $a->hoist; # ->

        - a
        - b
        - c
         - d
        - f

   clear
        $node->clear;

       Detach all children of $node. The detached nodes will be returned, and can be safely
       reused, but they will no longer be in the document tree.

   push
        $node->push($target);

       Pushes $target at the end of $node's children.

   nest
        $node->nest(@new_children);

       Adds @new_children to $node's children. The new nodes will be added at the end of any
       existing children. This can be considered the inverse of hoist.

   unshift
        $node->unshift($target);

       The reverse of push, add a node to the start of $node's children.

   serial
        $node->serial;

       The unique serial number of $node. This should never be modified.

   attached
        $node->attached;

       Returns true if $node is attached to a document tree.

   detach
        $node->detach;

       Removes a node from it's document tree. Returns true if the node was removed from a tree,
       false otherwise. After this operation, the node will be detached.

       Detached nodes can be reused safely.

   parent
        $node->parent;

       Returns the parent of $node if available. Returns undef if no parent.

   root
        $node->root

       Find the root node for the tree holding this node - this may be the original node if it
       has no parent.

   children
        my @children = $node->children;

       Returns the children of the node in document order.

   next
        my $next = $node->next;

       Returns the following sibling of $node, if one exists. If there is no following node undef
       will be returned.

   previous
        my $previous = $node->previous;

       Returns the preceding sibling of $node, if one exists. If there is no preceding node,
       undef will be returned.

   coalesce_body
        $node->coalesce_body(':verbatim');

       This performs node coalescing as required by perlpodspec. Successive verbatim nodes can be
       merged into a single node. This is also done with text nodes, primarily for =begin/=end
       blocks.

       The named node type will be merged together in the child document wherever there are two
       or more successive nodes of that type. Don't use for anything except ":text" and
       ":verbatim" nodes unless you're really sure you know what you want.

AUTHOR

       Ben Lilburne <bnej@mac.com>

COPYRIGHT AND LICENSE

       Copyright (C) 2009 Ben Lilburne

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.