Pod::Tree::Node - nodes in a Pod::Tree
$node = root Pod::Tree::Node \@paragraphs; $node = code Pod::Tree::Node $paragraph; $node = verbatim Pod::Tree::Node $paragraph; $node = command Pod::Tree::Node $paragraph; $node = ordinary Pod::Tree::Node $paragraph; $node = letter Pod::Tree::Node $token; $node = sequence Pod::Tree::Node $letter, \@children; $node = text Pod::Tree::Node $text; $node = target Pod::Tree::Node $target; $node = link Pod::Tree::Node $node, $page, $section; is_code $node and ... is_command $node and ... is_for $node and ... is_item $node and ... is_letter $node and ... is_list $node and ... is_ordinary $node and ... is_pod $node and ... is_root $node and ... is_sequence $node and ... is_text $node and ... is_verbatim $node and ... is_link $node and ... is_c_head1 $node and ... is_c_head2 $node and ... is_c_cut $node and ... is_c_pod $node and ... is_c_over $node and ... is_c_back $node and ... is_c_item $node and ... is_c_for $node and ... is_c_begin $node and ... is_c_end $node and ... $arg = get_arg $node; $brackets = get_brackets $node; $children = get_children $node; $command = get_command $node; $domain = get_domain $node; $item_type = get_item_type $node; $letter = get_letter $node; $list_type = get_list_type $node; $page = get_page $node; $raw = get_raw $node; $raw_kids = get_raw_kids $node; $section = get_section $node; $siblings = get_siblings $node; $target = get_target $node; $text = get_text $node; $type = get_type $node; $deep_text = get_deep_text $node; $node->force_text($text); $node->force_for; $node->parse_begin (\@nodes); $node->set_children(\@children); $node->make_sequences; $node->parse_links; $node->unescape; $node->consolidate; $node->make_lists;
$node->clone; $node->dump; Pod::Tree::Node->set_filename($filename); $filename = $node->get_filename;
Pod::Escapes
Pod::Tree::Node objects are nodes in a tree that represents a POD.
Applications walk the tree to recover the structure and content of the POD.
Methods are provided for
The tree descends from a single root node;
is_root returns true on this node and no other.
$children = $root->get_children
returns a reference to an array of nodes. These nodes represent the POD.
For each node,
call get_type to discover the type of the node
for $child (@$children)
{
$type = $child->get_type;
}
$type will be one of these strings:
Here are instructions for walking these node types.
Call
$children = $node->get_children
to get a list of nodes representing the POD.
A code node contains the text of a paragraph that is not part of the
POD, for example, a paragraph that follows an =cut command. Call
$text = $node->get_text
to recover the text of the paragraph.
A verbatim node contains the text of a verbatim paragraph. Call
$text = $node->get_text
to recover the text of the paragraph.
An ordinary node represents the text of an ordinary paragraph. The text is parsed into a list of text and sequence nodes; these nodes are the children of the ordinary node. Call
$children = $node->get_children
to get a list of the children. Iterate over this list to recover the text of the paragraph.
A command node represents an =command paragraph. Call
$command = $node->get_command;
to recover the name of the command. The name is returned without the equals sign.
=over paragraphs are represented by list nodes, not command nodes; see list nodes, below.
The text of a command paragraph is parsed into a list of text and sequence nodes; these nodes are the children of the command node. Call
$children = $node->get_children;
to get a list of the children. Iterate over this list to recover the text of the paragraph.
A sequence node represents a single interior sequence (a <> markup). Call
$node->get_letter
to recover the original markup letter. The contents of the markup are parsed into a list of text and sequence nodes; these nodes are the children of the sequence node. Call
$node->get_children
to recover them.
Z<> and E<> markups do not generate sequence nodes;
these markups are expanded by Pod::Tree when the tree is built.
If a sequence node represents a link (an L<> markup),
then
is_link $node
returns true and
$target = $node->get_target
returns a node representing the target of the link.
Pod::Tree::Node can represent targets in two domains: POD and HTTP.
The POD domain represents the
L<page/section>
markups that are described in perlpod.
The HTTP domain represents L<> markups that contain a URL, e.g.
L<http://foo.bar.com/page.html#fragment>
Call
$domain = $target->get_domain
to discover the domain of the target. For targets in the POD domain, call
$page = $target->get_page; $section = $target->get_section;
to recover the man page and section that the link refers to. For targets in the HTTP domain, call
$url = $target->get_page;
to recover the URL for the link.
$target is used only for constructing hyper-links; the text to be displayed for the link is recovered by walking the children of $node, as for any other interior sequence.
A text node represents text that contains no interior sequences. Call
$text = $node->get_text
to recover the text.
A list node represents an =over list. Call
$list_type = $node->get_list_type;
to discover the type of the list. This will be one of the strings
The type of a list is the type of the first item in the list.
The children of a list node are item nodes; each item node represents one item in the list.
You can call
$node->get_arg;
to recover the indent value following the =over.
An item node represents one item in an =over list. Call
$item_type = $node->get_item_type;
to discover the type of the item.
This will be one of the strings shown above for list nodes.
Typically, all the items in a list have the same type,
but Pod::Tree::Node doesn't assume this.
The children of an item node represent the text of the =item paragraph; this is usually of interest only for 'text' items. Call
$children = $node->get_children
to get a list of the children; these will be sequence and text nodes, as for any other =command paragraph.
Each item node also has a list of nodes representing all the paragraphs following it, up to the next =item command, or the end of the list. These nodes are called siblings of the item node. Call
$siblings = $node->get_siblings
to get a list of sibling nodes.
for nodes represent text that is to be passed to an external formatter. Call
$formatter = $node->get_arg;
to discover the name of the formatter. Call
$text = $node->get_text;
to obtain the text to be passed to the formatter. This will either be the text of an =for command, or all of the text between =begin and =end commands.
PODs have a recursive structure; therefore, any application that walks a Pod::Tree must also be recursive. See skeleton for an example of the necessary code.
These methods construct Pod::Tree::Node objects.
They are used to build trees.
They aren't necessary to walk trees.
$node = root Pod::Tree::Node \@paragraphs; $node = code Pod::Tree::Node $paragraph; $node = verbatim Pod::Tree::Node $paragraph; $node = command Pod::Tree::Node $paragraph; $node = ordinary Pod::Tree::Node $paragraph; $node = letter Pod::Tree::Node $token; $node = sequence Pod::Tree::Node $letter, \@children; $node = text Pod::Tree::Node $text; $node = target Pod::Tree::Node $target; $node = link Pod::Tree::Node $node, $page, $section;
Pod::Tree::Node->link($node, $page, $section)
Creates a new sequence node representing an L<> markup.
$node becomes the sole child of the new node.
The target of the node is constructed from $page and $section.
This method isn't used to parse PODs.
It is provided for applications that want to create new links in an
existing Pod::Tree structure.
These methods return true iff $node has the type indicated by the method name.
is_code $node and ... is_command $node and ... is_for $node and ... is_item $node and ... is_letter $node and ... is_link $node and ... is_list $node and ... is_ordinary $node and ... is_pod $node and ... is_root $node and ... is_sequence $node and ... is_text $node and ... is_verbatim $node and ...
is_pod returns true for all nodes except code, =pod,
and =cut nodes.
These methods return true iff $node is a command node, and the command is the one indicated by the method name.
is_c_head1 $node and ... is_c_head2 $node and ... is_c_cut $node and ... is_c_pod $node and ... is_c_over $node and ... is_c_back $node and ... is_c_item $node and ... is_c_for $node and ... is_c_begin $node and ... is_c_end $node and ...
These methods return information about nodes. Most accessors are only relevant for certain types of nodes.
get_arg $node
get_brackets $node
Only relevant for for nodes.
If the node represents an =for command, @$brackets is a single-element list. The list element is the text of the =for command and its argument, i.e. the name of the external formatter.
If the node represents a =begin/=end construct, @$brackets is a two-element list containing the text of the =begin and =end paragraphs.
get_children $node
get_command $node
get_domain $node
Only relevant for target nodes. Returns the domain of the target. This will be one of the strings
get_item_type $node
Returns the type of an item node. The type will be one of
get_letter $node
get_list_type $node
get_page $node
POD domain,
returns the man page that is the target of the link.
For targets in the HTTP domain,
returns the URL that is the target of the link.
get_raw $node
get_raw_kids $node
Only provided for L<> sequence nodes. Returns a reference to a list of nodes representing the entire text of the L<> sequence, including any part following a vertical bar (|).
The original text of the L<> markup can be reconstructed from this list.
get_section $node
POD domain.
Returns the section that is the target of a link.
get_siblings $node
get_target $node
L<> markups).
is_link returns true on these nodes.
get_text $node
get_type $node
get_deep_text $node
Recursively walks the children of a node, catenates together the text from each node, and returns all that text as a single string. All interior sequence markups are discarded.
get_deep_text is provided as a convenience for applications that
want to ignore markups in a POD paragraph.
These methods manipulate the tree while it is being built. They aren't necessary to walk the tree.
$node->force_text($text) $node->force_for; $node->parse_begin (\@nodes); $node->set_children(\@children); $node->make_sequences; $node->parse_links; $node->unescape; $node->consolidate; $node->make_lists;
clone
text and sequence nodes.
dump
dump on the root node of a tree will show the entire POD.
Pod::Tree::Node->set_filename($filename)
getfile_name
set_file_name.
The t/ directory in the Pod::Tree distribution contains
examples of PODs,
together with dumps of the trees that Pod::Tree constructs for them.
The tree for t/file.pod is in t/file.p_exp.
Pod::Tree::Node::dump is a simple example of code that walks a POD tree.
skeleton is a skeleton application that walks a POD tree.
L<> markups to contain
URLs, but due to popular demand, this is now supported in
Pod::Tree::Node.
perl(1), Pod::Tree
Steven McDougall, swmcd@world.std.com
Copyright 1999-2003 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.