Pod::A...ldNode(3pm)

💖 Pod::Abstract::BuildNode — bestie edition 💖

okay so this is Pod::Abstract::BuildNode from the User Contributed Perl Documentation section (3pm, the perl module manual, iykyk) and it's literally the glow-up station for building brand new nodes to use inside Pod::Abstract. 🫶

---

✨ NAME ✨

Pod::Abstract::BuildNode — Build new nodes for use in Pod::Abstract. 💅

---

🌸 SYNOPSIS 🌸

use Pod::Abstract::BuildNode qw(node nodes); # shorthand

my $root_doc = node->root;
for(my $i = 1; $i < 10; $i ++) {
   $root_doc->push(node->head1("Heading number $i"));
}
print $root_doc->pod;

like, look at her go. ten headings, zero effort, absolute main character energy. 👑

---

🦋 DESCRIPTION 🦋

So this module is for building a whole new Pod::Abstract document, OR for adding nodes onto one you already have sitting there. It gives you easy-peasy methods that generate correctly set nodes for most of the common Pod::Abstract elements. no cap, it just... does the fiddly part for you. ✨

---

🎀 NOTES 🎀

Pod::Abstract::BuildNode can export two functions: "node" and "nodes". These are constant functions that exist purely to be a shorthand, so instead of writing this whole thing:

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

you can instead write:

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

which is more readable and less typing. lowkey the best trade deal in the history of trade deals. "node" and "nodes" are both synonyms of Pod::Abstract::BuildNode.

This shorthand form is what's shown in all the method examples below. All methods operate on the class. periodt. 💅

---

🧚 METHODS 🧚

💜 from_pod

my @nodes = nodes->from_pod($pod_text);

Hand it some literal Pod text and it will generate a full subtree of nodes for you. The array you get back is all of the top level nodes, and the full document tree gets populated underneath those returned nodes. 🌈

💜 root

my $root = node->root;

Generates a root node. A root node generates no output — it's just the thing that holds a document tree. Use this one to make a brand new document. 🫶

💜 begin

my $begin_block = node->begin($command);

Generates a begin/end block. Any nodes you nest inside the begin node will appear between the begin and the end.

ngl there's no matching "end" method — the end command belongs to its corresponding begin. it's giving "we're a package deal". 🎀

💜 for

my $for = node->for('overlay from <class>');

Creates a =for node. The argument is the literal body of the for node — no parsing will be performed on it. 💅

💜 paragraph

my $para = node->paragraph('Pod text');

Generates a Pod paragraph, which may contain interior sequences. The argument gets parsed as Pod, and that generates text and sequence nodes inside the paragraph. slay. ✨

💜 verbatim

my $v = node->verbatim($text);

Adds the given text as a verbatim node to the document. Every single line in the given $text gets indented by one space so it's guaranteed to be treated as verbatim. (yes the original prose says "fiven" — we love a typo, we're keeping the meaning and moving on 💀)

💜 heading

my $head2 = node->heading(2, $heading);

Generates a heading node at the given level. Nodes that "belong" in that heading's section should be nested inside the heading node. The $heading text will be parsed for interior sequences. 👑

💜 head1

node->head1($heading);

💜 head2

node->head2($heading);

💜 head3

node->head3($heading);

💜 head4

node->head4($heading);

💜 over

my $list = node->over([$num]);

Generates an over/back block to hold your list items. The optional parameter $num says how many spaces to indent by. Heads up: the back node is part of the over — there is no separate back method. it's all one vibe. 🌸

💜 link

my $link = node->link('Pod::Abstract');

Generates an inline link. This will nest the link text you passed, and only that.

There's special inline parsing for Perl POD links, which is not handled by this method. so don't come for her about it. 🙈

💜 item

my $item = node->item('*');

Generates an item with the label you specify. To fill in the text of the item, nest paragraphs into the item. Items should be contained in over nodes. group chat rules: items live inside overs, that's just how it is. 🍓

💜 text

my $text = node->text('Literal text');

Generates a literal text node. You generally do not want this — you probably want a paragraph. Use this one when you genuinely need it, like appending a single word at the end of a paragraph. iykyk. ✨

💜 pod

my $n = node->pod;

Generates an "=pod" command. Can be useful to force pod mode at the end of cut nodes.

Do not confuse with "from_pod"! they are two completely different girls, don't mix them up 😭

💜 cut

my $cut = node->cut;

Generates an explicit "=cut" command. bye pod mode, it's been real. ✂️

---

🌟 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 💕 — brought to you by perl v5.40.1, dated 2025-11-16, from the Pod::A...ldNode(3pm) era of the manual. go build some nodes, you're gonna ate. 🦋✨👑🫶