Pod::Tree::Node(3pm)

🎀 NAME 🎀

okay so bestie, this is the Pod::Tree::Node(3pm) man page, and it's all about Pod::Tree::Node — literally nodes in a Pod::Tree 💅 no cap, that's the whole gig.

---

✨ SYNOPSIS ✨

here's the entire menu of constructors and methods, laid out like a little snack platter 🍓:

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

---

🦋 REQUIRES 🦋

• Pod::Escapes — that's it, that's the whole list, she's low-maintenance 💖

---

🌈 DESCRIPTION 🌈

Pod::Tree::Node objects are nodes in a tree that represents a POD. Applications walk that 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, fr fr.

$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 👑
• 'code' — the node represents a paragraph that is not part of the POD
• '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 the instructions for walking each of these node types, bestie 💅

🌱 root node

Call

$children = $node->get_children

to get a list of nodes representing the POD.

💻 code nodes

A code node contains the text of a paragraph that is not part of the POD — like, for example, a paragraph that follows an =cut command. Call

$text = $node->get_text

to recover the text of the paragraph.

📜 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. That text is parsed into a list of text and sequence nodes; those 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 comes back without the equals sign, iykyk.

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

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.

🔤 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 — she checks, she doesn't guess 💅

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.

🔧 Parsing 🔧

okay these ones mess with the tree while it's still being built. Walking a tree? You literally never need these. They're the backstage crew. 🎭

$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->"clone"

Returns a deep copy of a node. Only implemented for text and sequence nodes — anything else and it's a no. 🙈

💅 $node->"dump"

Returns a string containing a pretty-printed representation of the node. Call dump on the root node of a tree and it shows you the entire POD. It's giving full receipts. ✨

💅 "Pod::Tree::Node"->"set_filename"($filename)

Sets the file name that gets reported in error messages. So when something goes wrong, it can point at the right file instead of being vague about it. 🫶

💅 $filename = $node->"getfile_name"

Returns the file name set by set_file_name. (Yes, bestie, the names don't match — that's just how it is, we don't fix the source material here. 💀)

---

🌈 EXAMPLES 🌈

The t/ directory in the Pod::Tree distribution has examples of PODs, plus dumps of the trees that Pod::Tree builds for them. The tree for t/file.pod lives in t/file.p_exp — that file bit is a placeholder for the actual file name, iykyk. 🎀

Pod::Tree::Node::dump is a simple little example of code that walks a POD tree. Cute, minimal, does the thing.

skeleton is a skeleton application that walks a POD tree. Perfect starting point if you wanna build your own thing. 👑

---

📝 NOTES 📝

• There is no provision in perlpod for L<> markups to contain URLs, but due to popular demand, this is now supported in Pod::Tree::Node. The people spoke and they were heard, periodt. 💅

---

👀 SEE ALSO 👀

perl(1), Pod::Tree

---

👑 AUTHOR 👑

Steven McDougall, swmcd@world.std.com

---

©️ COPYRIGHT ©️

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.

---

and that's the whole page, bestie 💖 This one shipped as part of perl v5.36.0 on 2022-11-19, under the title Pod::Tree::Node(3pm). Go build a tree, you absolute main character. 🌸🦋⭐