CommonM...terator(3)

💖 CommonM...terator(3) — the manual page, bestie edition 💖

okay so this is the User Contributed Perl Documentation for CommonMark::Iterator, and I'm gonna walk you through it like we're texting at 2am. it's giving "walking a parse tree but make it cute". let's go 🦋

---

✨ NAME ✨

CommonMark::Iterator — iterate CommonMark nodes, no cap

---

🌸 SYNOPSIS 🌸

okay bestie, here's the vibe:

use CommonMark qw(:node :event);

my $iter = $doc->iterator;

while (my ($ev_type, $node) = $iter->next) {
    my $node_type = $node->get_type;

    if ($node_type == NODE_PARAGRAPH) {
        if ($ev_type == EVENT_ENTER) {
            print("<p>");
        }
        else {
            print("</p>\n");
        }
    }
    elsif ($node_type == NODE_TEXT) {
        print($node->get_literal);
    }
}

literally the whole thing in one loop. periodt 💅

---

👑 DESCRIPTION 👑

CommonMark::Iterator gives you a convenient way to walk through all the nodes in a parse tree. it's the "hold my hand while we traverse" of CommonMark. 🫶

🎀 Construction

my $iterator = $node->iterator;

creates an iterator from a node. $node is the root node of the iterator — like, the main character of this whole traversal. 👑

🧚 next

my $ev_type = $iterator->next;
my ($ev_type, $node) = $iterator->next;

so the contents of the iterator are initially undefined (yes, fr fr, it starts out with nothing). after the first call to next, and after every call after that, the iterator holds a new event type and a new current node.

• in scalar context, next returns the new event type
• in list context, it returns a 2-element list: the new event type and the new current node

the event types are:

CommonMark::EVENT_DONE
CommonMark::EVENT_ENTER
CommonMark::EVENT_EXIT

and you can import them from CommonMark with the tag event, like:

use CommonMark qw(:event);

the iterator starts by visiting the root node. every visited node V generates this sequence of events, in order:

1. Enter the node. the event type is CommonMark::EVENT_ENTER and the current node is set to the entered node V. 🚪✨
2. Visit all children of the node V, from first to last, applying this same sequence of events recursively. it's recursive bestie, it goes all the way down 🌀
3. Except for leaf nodes, exit the node. the event type is CommonMark::EVENT_EXIT and the current node is set to the original node V.

after the root node was exited, the event type is set to CommonMark::EVENT_DONE and the current node becomes undef. so in scalar context next returns CommonMark::EVENT_DONE, and in list context it returns the empty list. (yes, the empty list. it's done. bye. 💀)

for leaf nodes, no exit events are generated. leaf nodes are the node types that never have children:

CommonMark::NODE_HTML
CommonMark::NODE_HRULE
CommonMark::NODE_CODE_BLOCK
CommonMark::NODE_TEXT
CommonMark::NODE_SOFTBREAK
CommonMark::NODE_LINEBREAK
CommonMark::NODE_CODE
CommonMark::NODE_INLINE_HTML

for other node types, an exit event is generated even if the node has no children. so no sneaky "oh it has no kids, skip the exit" — nope, exit happens anyway. 🌈

⚠️ it is safe to modify nodes after an exit event, or an enter event for leaf nodes. otherwise, changes to the tree structure can result in undefined behavior. do not do this. I'm serious bestie, undefined behavior is NOT the vibe. 🙈

🍓 Accessors

my $node    = $iter->get_node;
my $ev_type = $iter->get_event_type;
my $node    = $iter->get_root;

these accessors return the current node, the current event type, and the root node. three little getters, all iconic. 💜

---

💅 COPYRIGHT 💅

this software is copyright (C) by Nick Wellnhofer.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, honestly. 🎀

---

and that's the whole page, bestie!! 🌟 this was CommonM...terator(3) from the User Contributed Perl Documentation, and it's perl v5.42.0, dated 2025-07-25. mwah 💋 go traverse something pretty 🦋