Pod::Tree(3pm)

✨ Pod::Tree ✨

okay so bestie, you know how POD is just vibes and text but sometimes you need to actually understand it structurally? yeah. that's this. Pod::Tree — the 3pm manual page, coming at you live 💅

---

🌸 SYNOPSIS 🌸

use Pod::Tree;

$tree = Pod::Tree->new;
$tree->load_file      ( $file, %options)
$tree->load_fh        ( $fh  , %options);
$tree->load_string    ( $pod , %options);
$tree->load_paragraphs(\@pod , %options);

$loaded = $tree->loaded;

$node   = $tree->get_root;
          $tree->set_root  ($node);
$node =   $tree->pop;
          $tree->push(@nodes);

          $tree->walk(\&sub);
          $tree->has_pod and ...
print     $tree->dump;

---

🎀 EXPORTS 🎀

Nothing. Literally nothing. Zero. Nada. She exports nothing and she's iconic for it 💖

---

🦋 DESCRIPTION 🦋

Pod::Tree parses a POD into a static syntax tree. Apps walk that tree to recover the structure and content of the POD. And if you wanna know what the tree actually looks like, go peek at Pod::Tree::Node — that's where the description lives. 🌈

---

👑 METHODS 👑

💫 $tree = "Pod::Tree"->"new"

Makes you a shiny new Pod::Tree object. The syntax tree starts out empty — a blank canvas, main character energy ✨

💫 $ok = $tree->"load_file"($file, %options)

Parses a POD and builds a syntax tree from it. $file is the name of a file that contains the POD. Returns null iff it can't open $file. (yes, "iff" — if and only if, bestie, we're precise here)

Wanna know what %options does? Scroll to OPTIONS 👇

💫 $tree->"load_fh"($fh, %options)

Parses a POD and builds a syntax tree from it. $fh is an IO::File object that's open on a file containing the POD.

%options deets → OPTIONS 👇

💫 $tree->"load_string"($pod, %options)

Parses a POD and builds a syntax tree from it. $pod is one single string holding the POD.

%options deets → OPTIONS 👇

💫 $tree->"load_paragraphs"(\@pod, %options)

Parses a POD and builds a syntax tree from it. \@pod is a reference to an array of strings, and each string is one paragraph of the POD.

%options deets → OPTIONS 👇

💫 $loaded = $tree->"loaded"

Returns true iff one of the load_* methods has been called on $tree. So basically: "did we load yet??" 🫶

💫 $node = $tree->"get_root"

Hands you the root node of the syntax tree. (Want the full lore on the syntax tree? Pod::Tree::Node, go look 👀)

💫 $tree->"set_root"($node)

Sets the root of the syntax tree to $node. Simple as. 💅

💫 $tree->"push"(@nodes)

Pushes @nodes onto the end of the top-level list of nodes in $tree.

💫 $node = $tree->"pop"

Pops $node off the end of the top-level list of nodes in $tree.

💫 $tree->"walk"(\&sub)

Walks the syntax tree, depth first. Calls sub once for every node in the tree, and the current node gets passed as the first argument to sub.

Here's the tea though: walk only descends to the children and siblings of $node iff sub() returns true. so like, return false and the walk just... stops going deeper there. boundaries, we love them 🧚

💫 $tree->"has_pod"

Returns true iff $tree contains POD paragraphs.

💫 $tree->"dump"

Pretty prints the syntax tree. This is the moment where you get to see how Pod::Tree interpreted your POD — honestly a vibe check for your markup 😭

---

🌈 OPTIONS 🌈

These options can be passed in the %options hash to the load_* methods. ✨

• "in_pod => 0"
• "in_pod => 1" — Sets the initial value of in_pod. When in_pod is false, the parser ignores all text until the next =command paragraph.

The initial value of in_pod defaults to false for load_file() and load_fh() calls, and true for load_string() and load_paragraphs() calls. That's usually exactly what you want — unless you're out here craving consistency. If this isn't what you want, just pass different initial values in the %options hash. no biggie 🫶

• "limit" => n — Only parse the first n paragraphs in the POD. Snip snip ✂️

---

💀 DIAGNOSTICS 💀

"load_file"($file)

Returns null iff it can't open $file. That's it, that's the diagnostic 🥲

---

🌸 NOTES 🌸

🎀 No round-tripping 🎀

Currently, Pod::Tree does not provide a complete, exact representation of its input. For example, it doesn't distingish between

C<$foo-E<gt>bar>

and

C<< $foo->bar >>

(and yeah, "distingish" is what the page says, we keep it 💅)

As a result, it is not guaranteed that a file can be exactly reconstructed from its Pod::Tree representation. So don't go expecting a perfect glow-up back to the original, bestie. it's giving lossy 😭

🎀 L<> markups 🎀

In the documentation of the

L<"sec">    section in this manual page

markup, perlpod has always claimed

(the quotes are optional)

However, there is no way to decide from the syntax alone whether

L<foo>

is a link to the foo man page or a link to the "foo" section of this man page. it literally cannot tell 😭

So here's what Pod::Tree does: it parses L<foo> as a link to a section if foo looks like a section name (e.g. contains whitespace), and as a link to a man page otherswise.

In practice, this tends to break links to sections. If you want your section links to work reliably, write them as L<"foo"> or L</foo>. periodt. write it the safe way 👑

---

⭐ SEE ALSO ⭐

perl(1), "Pod::Tree::Node", "Pod::Tree::HTML"

---

🫶 ACKNOWLEDGMENTS 🫶

the whole squad, the day-ones, the icons:

• <crazyinsomniac@yahoo.com>
• <joenio@cpan.org>
• Paul Bettinger <paul@n8geil.de>
• Sean M. Burke <sburke@spinn.net>
• Brad Choate <brad@bradchoate.com>
• Havard Eidnes <he@NetBSD.org>
• Rudi Farkas <rudif@bluemail.ch>
• Paul Gibeault <pagibeault@micron.com>
• Jay Hannah <jhannah@omnihotels.com>
• Paul Hawkins <phawkins@datajunction.com>
• Jost Krieger <Jost.Krieger@ruhr-uni-bochum.de>
• Marc A. Lehmann <pcg@goof.com>
• Jonas Liljegren <jonas@jonas.rit.se>
• Thomas Linden <tom@co.daemon.de>
• Johan Lindstrom <johanl@bahnhof.se>
• Terry Luedtke <terry_luedtke@nlm.nih.gov>
• Rob Napier <rnapier@employees.org>
• Kate L Pugh <kake@earth.li>
• Christopher Shalah <trance@drizzle.com>
• Johan Vromans <JVromans@Squirrel.nl>

---

💖 AUTHOR 💖

Steven McDougall <swmcd@world.std.com>

Currently maintained by Mohammad S Anwar <mohammad.anwar@yahoo.com> 🌟

---

📜 COPYRIGHT 📜

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

---

okay that's the whole thing bestie, you're fully caught up 💅✨ this was Pod::Tree from perl v5.36.0, dated 2022-11-19 — go build a syntax tree and slay 👑💖