Pod::Tree::Node(3pm) | User Contributed Perl Documentation | Pod::Tree::Node(3pm) |
Pod::Tree::Node - nodes in a Pod::Tree
$node = Pod::Tree::Node->root ( \@paragraphs ); $node = Pod::Tree::Node->code ( $paragraph ); $node = Pod::Tree::Node->verbatim ( $paragraph ); $node = Pod::Tree::Node->command ( $paragraph ); $node = Pod::Tree::Node->ordinary ( $paragraph ); $node = Pod::Tree::Node->letter ( $token ); $node = Pod::Tree::Node->sequence ( $letter, \@children ); $node = Pod::Tree::Node->text ( $text ); $node = Pod::Tree::Node->target ( $target ); $node = Pod::Tree::Node->link ( $node, $page, $section ); $node->is_code and ... $node->is_command and ... $node->is_for and ... $node->is_item and ... $node->is_letter and ... $node->is_list and ... $node->is_ordinary and ... $node->is_pod and ... $node->is_root and ... $node->is_sequence and ... $node->is_text and ... $node->is_verbatim and ... $node->is_link and ... $node->is_c_head1 and ... $node->is_c_head2 and ... $node->is_c_head3 and ... $node->is_c_head4 and ... $node->is_c_cut and ... $node->is_c_pod and ... $node->is_c_over and ... $node->is_c_back and ... $node->is_c_item and ... $node->is_c_for and ... $node->is_c_begin and ... $node->is_c_end and ... $arg = $node->get_arg ; $brackets = $node->get_brackets ; $children = $node->get_children ; $command = $node->get_command ; $domain = $node->get_domain ; $item_type = $node->get_item_type ; $letter = $node->get_letter ; $list_type = $node->get_list_type ; $page = $node->get_page ; $raw = $node->get_raw ; $raw_kids = $node->get_raw_kids ; $section = $node->get_section ; $siblings = $node->get_siblings ; $target = $node->get_target ; $text = $node->get_text ; $type = $node->get_type ; $deep_text = $node->get_deep_text ; $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;
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_head3 $node and ... is_c_head4 $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.
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.
The original text of the L<> markup can be reconstructed from this list.
"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;
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.
perl(1), "Pod::Tree"
Steven McDougall, swmcd@world.std.com
Copyright (c) 1999-2004 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
2022-11-19 | perl v5.36.0 |