Pod::A...t::Node(3pm)

🌸 NAME 🌸

Pod::Abstract::Node — Pod Document Node. Yeah bestie, it's a node in a Pod document. That's the whole name. 💅

---

✨ SYNOPSIS ✨

$node->nest( @list );          # Nests list as children of $node. If they
                               # exist in a tree they will be detached.
$node->clear;                  # Remove (detach) all children of $node
$node->hoist;                  # Append all children of $node after $node.
$node->detach;                 # Detaches intact subtree from parent
$node->select( $path_exp );    # Selects the path expression under $node
$node->select_into( $target, $path_exp );
                               # Selects into the children of the
                               # target node.  (copies)

$node->insert_before($target); # Inserts $node in $target's tree
                               # before $target
$node->insert_after($target);

$node->push($target);          # Appends $target at the end of this node
$node->unshift($target);       # Prepends $target at the start of this node

$node->path();                 # List of nodes leading to this one
$node->children();             # All direct child nodes of this one
$node->next();                 # Following sibling if present
$node->previous();             # Preceding sibling if present

$node->duplicate();            # Duplicate node and children in a new tree.

$node->pod;                    # Convert node back into literal POD
$node->ptree;                  # Show visual (abbreviated) parse tree

---

🎀 METHODS 🎀

🌷 new

my $node = Pod::Abstract::Node->new(
   type => ':text', body => 'Some text',
);

Makes you a shiny new, fully unattached Node object. But bestie, listen — this is NOT the recommended way to make nodes you're gonna add to a document. Use Pod::Abstract::BuildNode for that, fr fr. There are specific rules about how the data has to be set up for these nodes, and new just… lets you ignore them. 🙈

Besides type and body, every other hash argument gets converted into params, which can be internal data or node attributes.

type can be:

• A plain word, which is taken to be a command name.
• :paragraph, :text, :verbatim or :X (where X is an inline format letter). These will be treated as you would expect.
• #cut, meaning this is literal, non-pod text.

Heads up though — none of this guarantees the resulting document structure will match your types. The types are derived from the document, not the other way around, iykyk. If your types don't match your document they will mutate when it's reloaded. 😭

Go peek at Pod::Abstract::BuildNode if you want to make nodes easily for creating/modifying a document tree. 💖

🦋 ptree

print $n->ptree;

Produces a formatted, readable, parse tree. Shows node types, nesting structure, abbreviated text. It does NOT show all the information — but it shows enough to help you debug parsing/traversal problems. Tiny legend behavior, honestly. ✨

🌸 text

print $n->text;

Returns the text subnodes only of the given node, concatenated together — i,e, the text only with no formatting at all. Just the raw vibes.

💜 pod

print $n->pod;

Returns the node (and all subnodes) formatted as POD. A newly loaded node should produce the original POD text when pod is requested. Slay, round-trip.

🔥 select

my @nodes = $n->select('/:paragraph[//:text =~ {TODO}]');

Select a pPath expression against this node. That example up there? It selects all paragraphs in the document containing 'TODO' in any of their text nodes. Iconic.

The returned values are the real nodes from the document tree — so manipulating them will transform the document. No copies, no safety net, main character energy. 👑

🌈 select_into

$node->select_into($target_node, $path)

Same deal as select, it matches a pPath expression against $node — but the resulting nodes get copied and added as children to $target_node. The nodes that were added get returned as a list. Copy-paste but make it fancy. 🫶

🍓 type

$node->type( [ $new_type ] );

Get or set the type of the node. Two jobs, one method, we love a multitasker.

🧚 body

$node->body( [ $new_body ] );

Get or set the node body text. This is NOT the child tree of the node — it's the literal text as used by text/verbatim nodes. Don't get it twisted. 💀

For a begin or for block, it is the text following the begin or for label. The children of the node are the contained text/nodes.

⭐ param

$node->param( $p_name [, $p_value ] );

Get or set the named parameter. Any value can be used, but for document attributes a Pod::Abstract::Node should be set.

🎀 link_info

my $link_info = $node->link_info;

For :L nodes (Links), break up the link according to the Perl Pod rules and return a hashref containing text, document and section. Deconstructed. ✂️

💫 duplicate

my $new_node = $node->duplicate;

Make a deep-copy of the node. The duplicate node returned has an identical document tree, but different node identifiers. Same fit, new serial number. 💅

🌺 insert_before

$node->insert_before($target);

Inserts $node before $target, as a sibling of $target. If $node is already in a document tree, it will be removed from it's existing position. (Yes, it sneaks out of its old home first.)

🌻 insert_after

$node->insert_after($target);

Inserts $node after $target, as a sibling of $target. If $node is already in a document tree, it will be removed from it's existing position. Same energy, other side.

🦄 hoist

$node->hoist;

Inserts all children of $node, in order, immediately after $node. After this operation, $node will have no children. In pictures:

- a
 - b
 - c
  - d
-f

$a->hoist; # ->

- a
- b
- c
 - d
- f

The glow-up is real. 🔥

🩷 clear

$node->clear;

Detach all children of $node. The detached nodes will be returned, and can be safely reused, but they will no longer be in the document tree. Fired, but reusable. 😌

🎈 push

$node->push($target);

Pushes $target at the end of $node's children. Queue, but make it a tree.

🌼 nest

$node->nest(@new_children);

Adds @new_children to $node's children. The new nodes will be added at the end of any existing children. This can be considered the inverse of hoist. Math girlies stay winning. ✨

💖 unshift

$node->unshift($target);

The reverse of push — add a node to the start of $node's children. Front of the line, periodt.

🎵 serial

$node->serial;

The unique serial number of $node. This should never be modified. Hands off, bestie. 🙅‍♀️

🌟 attached

$node->attached;

Returns true if $node is attached to a document tree. Vibe check: are you in the tree or not?

🍄 detach

$node->detach;

Removes a node from it's document tree. Returns true if the node was removed from a tree, false otherwise. After this operation, the node will be detached.

Detached nodes can be reused safely. It's giving conscious uncoupling. 🦋

🌙 parent

my $parent = $node->parent;

Returns the parent of $node if available. Returns undef if no parent. Orphan behavior, no notes.

☁️ parents

my @parents = $node->parents;

Returns a list of the parents of $node, including $node. Yes, it includes itself. Self-love, lowkey.

🪷 path_to

my $path_to = $node->path_to;

Returns a ppath expression that will lead to the heading/item containing $node, as best as is possible by named nodes. GPS for your pod. 🗺️

⚡ root

$node->root

Find the root node for the tree holding this node — this may be the original node if it has no parent. Ancestor hunt, and sometimes the answer is you. 💅

🎀 children

my @children = $node->children;

Returns the children of the node in document order. In order, bestie, the order MATTERS.

🐚 next

my $next = $node->next;

Returns the following sibling of $node, if one exists. If there is no following node undef will be returned.

🫧 previous

my $previous = $node->previous;

Returns the preceding sibling of $node, if one exists. If there is no preceding node, undef will be returned.

🧁 coalesce_body

$node->coalesce_body(':verbatim');

This performs node coalescing as required by perlpodspec. Successive verbatim nodes can be merged into a single node. This is also done with text nodes, primarily for =begin/=end blocks.

The named node type will be merged together in the child document wherever there are two or more successive nodes of that type. Don't use for anything except :text and :verbatim nodes unless you're really sure you know what you want. ⚠️

---

👑 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.

---

💀 POD ERRORS 💀

Hey! The above document had some coding errors, which are explained below:

Around line 735:

=cut found outside a pod block.  Skipping to next block.

Not the doc dragging itself in public, but okay. 😭

---

And that's a wrap, bestie! This was Pod::A...t::Node(3pm) from the User Contributed Perl Documentation, running on perl v5.40.1, dated 2025-11-16. Go forth and parse some Pod. 💖✨🦋