Pod document node.
$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
my $node = Pod::Abstract::Node->new( type => ':text', body => 'Some text', );
Creates a new, unattached Node object. This is \s-1NOT\s0 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 \*(C`new\*(C' lets you ignore them.
Apart from type and body, all other hash arguments will be converted into \*(L"params\*(R", which may be internal data or node attributes.
Type may be:
A plain word, which is taken to be a command name.
\*(C`:paragraph\*(C', \*(C`:text\*(C', \*(C`:verbatim\*(C' or <:X> (where X is an inline format letter). These will be treated as you would expect.
\*(C`#cut\*(C', 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.
print $n->ptree;
Produces a formatted, readable, parse tree. Shows node types, nesting structure, abbreviated text. Does \s-1NOT\s0 show all information, but shows enough to help debug parsing/traversal problems.
print $n->text;
Returns the text subnodes only of the given node, concatenated together - i,e, the text only with no formatting at all.
print $n->pod;
Returns the node (and all subnodes) formatted as \s-1POD\s0. A newly loaded node should produce the original \s-1POD\s0 text when pod is requested.
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 '\s-1TODO\s0' in any of their text nodes.
The returned values are the real nodes from the document tree, and manipulating them will transform the document.
$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.
$node->type( [ $new_type ] );
Get or set the type of the node.
$node->body( [ $new_body ] );
Get or set the node body text. This is \s-1NOT\s0 the child tree of the node, it is the literal text as used by text/verbatim nodes.
$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.
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.
$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.
$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.
$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
$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.
$node->push($target);
Pushes $target at the end of $node's children.
$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.
$node->unshift($target);
The reverse of push, add a node to the start of $node's children.
$node->serial;
The unique serial number of $node. This should never be modified.
$node->attached;
Returns true if $node is attached to a document tree.
$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.
$node->parent;
Returns the parent of $node if available. Returns undef if no parent.
$node->root
Find the root node for the tree holding this node - this may be the original node if it has no parent.
my @children = $node->children;
Returns the children of the node in document order.
my $next = $node->next;
Returns the following sibling of $node, if one exists. If there is no following node undef will be returned.
my $previous = $node->previous;
Returns the preceding sibling of $node, if one exists. If there is no preceding node, undef will be returned.
$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 \*(C`:text\*(C' and \*(C`:verbatim\*(C' nodes unless you're really sure you know what you want.
Ben Lilburne <[email protected]>
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.