NAME

Pod::Tree::Node - nodes in a Pod::Tree

SYNOPSIS

$node = root     Pod::Tree::Node \@paragraphs;
$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;

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_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_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;
$children  = get_children  $node;
$command   = get_command   $node;
$item_type = get_item_type $node;
$letter    = get_letter    $node;
$list_type = get_list_type $node;
$page      = get_page      $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->dump;

DESCRIPTION

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

• creating nodes in the tree

• parsing the POD into nodes

• returning information about nodes

• walking the tree

TREE STRUCTURE

Root node

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.

Node types

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:

'root'

The node is the root of the tree.

'verbatim'

The node represents a verbatim paragraph.

'ordinary'

The node represents an ordinary paragraph.

'command'

The node represents an =command paragraph (but not an =over paragraph).

'sequence'

The node represents an interior sequence.

'target'

The node represents the target of a link (An L<> markup).

'text'

The node represents text that contains no interior sequences.

'list'

The node represents an =over list.

'item'

The node represents an item in an =over list.

'for'

The node represents a =for paragraph, or it represents the paragraphs between =begin/=end commands.

Here are instructions for walking these node types.

root node

Call

$children = $node->get_children

to get a list of nodes representing the POD.

verbatim nodes

A verbatim node contains the text of a verbatim paragraph. Call

$text = $node->get_text

to recover the text of the paragraph.

ordinary nodes

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.

command nodes

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.

sequence nodes

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.

target nodes

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. Call

$page    = $target->get_page;
$section = $target->get_section;

to recover the man page and section that the link refers to.

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

text nodes

A text node represents text that contains no interior sequences. Call

$text = $node->get_text

to recover the text.

list nodes

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

'bullet'

'number'

'text'

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.

item nodes

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

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.

Walking the tree

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.

METHODS

Constructors

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 = 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;

Tests

These methods return true iff $node has the type indicated by the method name.

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_root     $node and ...
is_sequence $node and ...
is_text     $node and ...
is_verbatim $node and ...

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_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 ...

Accessors

These methods return information about nodes. Most accessors are only relevant for certain types of nodes.

$arg = get_arg $node

Returns the argument of $node. This is the number following an =over command, or the name of an external translator for =for, =begin, and =end commands. Only relevant for these four command nodes.

$children = get_children $node

Returns a reference to the list of nodes that are children of $node. May be called on any node. The list may be empty.

$command = get_command $node

Returns the name of a command, without the equals sign. Only relevant for command nodes.

$item_type = get_item_type $node

Returns the type of an item node. The type will be one of

'bullet'

'number'

'text'

$letter = get_letter $node

Returns the letter that introduces an interior sequence. Only relevant for sequence nodes.

$list_type = get_list_type $node

Returns the type of a list node. The type of a list node is the type of the first item node in the list.

$page = get_page $node

Returns the man page that is the target of a link. Only relevant for target nodes.

$section = get_section $node

Returns the section that is the target of a link. Only relevant for target nodes.

$siblings = get_siblings $node

Returns the siblings of a node. May be called on any node. Only item nodes have siblings.

$target = get_target $node

Returns the target of a node. Only relevant for sequence nodes that represent links (L<> markups). is_link returns true on these nodes.

$text = get_text $node

Returns the text of a node. $text will not contain any interior sequences. Only relevant for text nodes.

$type = get_type $node

Returns the type of $node. May be called on any node. See "TREE STRUCTURE" for descriptions of the node types.

$deep_text = 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.

Parsing

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;

Utility

$node->dump

Returns a string containing a pretty-printed representation of the node. Calling dump on the root node of a tree will show the entire POD.

EXAMPLES

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.

SEE ALSO

perl(1), Pod::Tree

AUTHOR

Steven McDougall, swmcd@world.std.com

COPYRIGHT

Copyright 1999-2000 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Pod::Tree

perl -MCPAN -e shell
install Pod::Tree