Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Pod::Abstract::Node(3)User Contributed Perl DocumentatioPod::Abstract::Node(3)

       Pod::Abstract::Node - 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->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 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:

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

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

       o   "#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.

	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.

	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	POD. A newly loaded
       node should produce the original	POD 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	'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.

	$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 NOT 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.


       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


       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


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

	- a
	 - b
	 - c
	  - d

	$a->hoist; # ->

	- a
	- b
	- c
	 - d
	- f


       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.


       Pushes $target at the end of $node's 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


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


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


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


       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.


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


       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.


       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.

       Ben Lilburne <>

       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.

perl v5.32.1			  2010-01-03		Pod::Abstract::Node(3)


Want to link to this manual page? Use this URL:

home | help