Pod::Abstract(3pm)

💖 Pod::Abstract — the abstract doc tree for yer Perl POD 💖

okay bestie, welcome to Pod::Abstract(3pm), part of the User Contributed Perl Documentation ✨ this is the lil module that lets you load a POD document without touching its syntax directly, then mess with the abstract syntax tree like the main character you are 👑

---

✨ NAME ✨

Pod::Abstract — Abstract document tree for Perl POD documents 🦋

---

🌸 SYNOPSIS 🌸

use Pod::Abstract;
use Pod::Abstract::BuildNode qw(node);

# Get all the first level headings, and put them in a verbatim block
# at the start of the document
my $pa = Pod::Abstract->load_filehandle(\*STDIN);
my @headings = $pa->select('/head1@heading');
my @headings_text = map { $_->pod } @headings;
my $headings_node = node->verbatim(join "\n",@headings_text);

$pa->unshift( node->cut );
$pa->unshift( $headings_node );
$pa->unshift( node->pod );

print $pa->pod;

---

💅 DESCRIPTION 💅

Pod::Abstract gives you a way to load a POD document without ever making a direct reference to its syntax, and then do whole manipulations on the abstract syntax tree. It's giving "I don't do string surgery, I do structural surgery" 🪄

Use it to support extra features for POD, to format output, to compile stuff into alternative formats, etc. Sky's the limit fr fr 🌈

So here's the thing — POD documents are not a natural tree, but they do have a logical nesting structure. Pod::Abstract makes that explicit: =head* commands create nested sections, =over and =back create nested lists, and so on 👑

The paf summary command gives you easy visualisation of the tree it made. Iconic 💖

🫶 USAGE 🫶

Pod::Abstract lets you easily manipulate and traverse POD or Perl files containing POD, without ever having to do manual string manipulation. No cap.

It lets you easily write formatters, filters, test scripts, etc for POD. Obsessed, honestly 💅

Pod::Abstract is based on the standard Pod::Parser module.

🧚 PROCESSING MODEL 🧚

Pod::Abstract lets documents be loaded, decorated, and manupulated in multiple steps. It can also make generating a POD formatter very simple. You can easily add features to an existing POD formatter, since any POD abstract object can be written out as a POD document. So slay ✨

Rather than write or fork a whole translator, you can just add a single inline "decorator".

The paf utility is a good starting point — it also lets you hook in to an existing filter/transform library. Add a Pod::Abstract::Filter class to the namespace and it should start working as a paf command 🔥

🍓 EXAMPLE 🍓

Say you're frustrated by the verbose list syntax regular POD uses. Mood. You might reasonably want to define a simplified list format for your own use... except POD formatters won't support it 😭

With Pod::Abstract you can write an inline filter to convert:

* item 1
* item 2
* item 3

into:

=over

=item *

item 1

=item *

item 2

=item *

item 3

=back

This transformation can be performed on the document tree. If your formatter doesn't use Pod::Abstract, you can pipe out POD and use a regular formatter. If your formatter does support Pod::Abstract, you can feed in the syntax tree directly without having to re-serialise and parse the document 💅

And the source document is still valid Pod — you aren't breaking compatibility with regular perldoc just by making Pod::Abstract transformations 🫶

👑 POD SUPPORT 👑

Pod::Abstract supports all POD rules defined in perlpodspec. Periodt.

---

🌈 COMPONENTS 🌈

Pod::Abstract is comprised of:

• The parser, which loads a document tree.

e.g:

my $pa = Pod::Abstract->load_filehandle(\*STDIN);

• The document tree, returned from the parser. The root node ($pa above) represents the whole document. Calling ->pod on the root node will give you back your original document.

Heads up bestie — the document includes #cut nodes, which are generally the Perl code, i.e. the parts that aren't POD. These will be included in the output of ->pod unless you remove them, so you can modify a Perl module as a POD document in POD abstract, and it will work the same afterwards 👀

e.g

my $pod_text = $pa->pod; # $pod_text is reserialized from the tree.

See Pod::Abstract::Node

• Pod::Abstract::Path, a node selection language. Called via $node->select(PATH_EXP). Pod paths are a powerful feature allowing declarative traversal of a document 🔥

For example —

"Find all head2s under METHODS"

/head1[@heading=~{^METHODS$}]/head2

"Find all bold text anywhere"

//B

• The node builder, Pod::Abstract::BuildNode. This exports methods to allow adding content to POD documents.

You can also combine documents —

use Pod::Abstract::BuildNode qw(node nodes);
# ...
my @nodes = nodes->from_pod($pod);

Where $pod is a text with POD formatting.

🌸 Using paths 🌸

The easiest way to traverse a $pa tree is to use the select method on the nodes, and paths.

select will accept and expression and return an array of Pod::Abstract::Node. These nodes also support the select method — for example:

my @headings = $pa->select('/head1'); # Get all heading 1
my @X = $headings[0]->select('//:X'); # Get all X (index) sequences inside that heading
my @indices = map { $_->text } @X; # Map out the contents of those as plain text.

You can combine path expressions with other methods, for example — children will give all the child nodes of a POD node, next, previous, parent and root allow traversal from a given node 💫

From any node you can then call select to make a declarative traversal from there. The above methods also have comparable expressions in Pod::Abstract::Path. iykyk 🎀

🦋 Traversing for document generation 🦋

To traverse the tree for document generation, you can follow children from the first node, then examine each node type to determine what you should generate.

The nodes will generate in a tree, so headings have nested children with subheadings and texts. In most cases the body method will give the text (or POD nodes) next to the command, while the children method will give the contained POD.

Special types are :paragraph, :text, <#cut>. Interior sequences are also started with a : for their type, like :L, :B, :I for Link, Bold, Italic. 👑

Use the $node->ptree method to see a visualised tree of a parsed document. So satisfying fr fr 🌳

---

💜 METHODS 💜

⭐ load_file ⭐

my $pa = Pod::Abstract->load_file( FILENAME );

Read the POD document in the named file. Returns the root node of the document.

🌷 load_filehandle 🌷

my $pa = Pod::Abstract->load_filehandle( FH );

Load a POD document from the provided filehandle reference. Returns the root node of the document.

🎀 load_string 🎀

my $pa = Pod::Abstract->load_string( STRING );

Loads a POD document from a scalar string value. Returns the root node of the document.

---

💖 AUTHOR 💖

Ben Lilburne <bnej80@gmail.com>

---

🌈 COPYRIGHT AND LICENSE 🌈

Copyright (C) 2009-2025 Ben Lilburne

This program 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 was perl v5.40.1, dated 2025-11-16, and it was giving Pod::Abstract(3pm) the entire time 💅✨