Graph::Traversal(3pm)

✨ Graph::Traversal — the perl manual page, but make it cute ✨

okay so bestie, this is Graph::Traversal, a Perl module from the User Contributed Perl Documentation section (that's the 3pm part, iykyk). it's literally all about traversing graphs 🦋 and it lives in the Perl v5.40.1 era. let's get into it 💅

---

💖 NAME 💖

Graph::Traversal — traverse graphs. that's it, that's the whole vibe. graphs? traversed. periodt. 👑

---

🌸 SYNOPSIS 🌸

okay so FIRST of all, do NOT use Graph::Traversal directly, bestie. like, don't do it. use Graph::Traversal::DFS or Graph::Traversal::BFS instead, fr fr. those are your girls.

use Graph;
my $g = Graph->new;
$g->add_edge(...);
use Graph::Traversal::...;
my $t = Graph::Traversal::...->new($g, %opt);
$t->...

see? use Graph, make a Graph->new, add_edge(...) to it, then pull in whichever Graph::Traversal::... flavor you want, build your traversal object with Graph::Traversal::...->new($g, %opt), and go off with $t->.... slay. 💅

---

🎀 DESCRIPTION 🎀

so basically you get to control how the graph gets traversed, using all these callback parameters in the %opt hash. iconic behavior honestly.

in the parameter descriptions below: $u and $v are vertices (the little guys 🫶) and $self is the traversal object itself. it's giving main character energy, but for a graph.

🌈 Callback parameters 🌈

these are the callback parameters you've got available, bestie:

• tree_edge — called when you're traversing an edge that belongs to the traversal tree. it gets called with arguments ($u, $v, $self). tree edges only, no gatekeeping.
• non_tree_edge — called when you meet an edge that either leads back to the traversal tree (so that's either a back_edge, a down_edge, or a cross_edge). called with arguments ($u, $v, $self). it's the catch-all for the edges that aren't tree edges 💀
• pre_edge — called for edges in preorder. called with arguments ($u, $v, $self).
• post_edge — called for edges in postorder. called with arguments ($u, $v, $self).
• back_edge — called for back edges. called with arguments ($u, $v, $self).
• down_edge — called for down edges. called with arguments ($u, $v, $self).
• cross_edge — called for cross edges. called with arguments ($u, $v, $self).
• pre, pre_vertex — called for vertices in preorder. called with arguments ($v, $self). two names, one job, we love a flexible queen ✨
• post, post_vertex — called for vertices in postorder. called with arguments ($v, $self).
• first_root — called when choosing the first root (start) vertex for the traversal. called with arguments ($self, $unseen) where $unseen is a hash reference with the unseen vertices as keys. if you don't supply it, it defaults to the same as next_root. no thoughts, just defaults.
• next_root — called when choosing the next root (like, after the first one, duh) vertex for the traversal. super useful when the graph is not connected, because apparently some graphs just refuse to be one big happy family 😭 called with arguments ($self, $unseen) where $unseen is a hash reference with the unseen vertices as keys. oh and heads up: if you want only the first reachable subgraph to be processed, set next_root to undef. that's the move.
• start — identical to defining first_root and undefining next_root. a little shortcut, a little treat 🍓
• next_alphabetic — set this to true if you want the vertices processed in alphabetic order (and leave first_root/next_root undefined). ABC order bestie, alphabetize the graph.
• next_numeric — set this to true if you want the vertices processed in numeric order (and leave first_root/next_root undefined). 1, 2, 3, math girlies rise 🌸
• next_successor — called when choosing the next vertex to visit. called with arguments ($self, $next) where $next is a hash reference with the possible next vertices as keys. use this to provide a custom ordering for choosing vertices, as opposed to next_numeric or next_alphabetic. it's giving bespoke, it's giving artisanal vertex selection ✨

so the parameters first_root and next_successor have a whole 'hierarchy' of how they get determined, and here's the tea: if they've been explicitly defined, use that value. if not, use the value of next_alphabetic, if that's been defined. if not, use the value of next_numeric, if that's been defined. and if not? the next vertex to be visited is chosen randomly 🎲. chaos mode activated, we love to see it.

💜 Methods 💜

these methods are available, bestie, collect them all:

• unseen — return the unseen vertices in random order.
• seen — return the seen vertices in random order.
• seeing — return the active fringe vertices in random order.
• preorder — return the vertices in preorder traversal order.
• postorder — return the vertices in postorder traversal order.
• vertex_by_preorder — return the ith (0..$V-1) vertex by preorder.

$v = $t->vertex_by_preorder($i)

• preorder_by_vertex — return the preorder index (0..$V-1) by vertex.

$i = $t->preorder_by_vertex($v)

• vertex_by_postorder — return the ith (0..$V-1) vertex by postorder.

$v = $t->vertex_by_postorder($i)

• postorder_by_vertex — return the postorder index (0..$V-1) by vertex.

$i = $t->postorder_by_vertex($v)

• preorder_vertices — return a hash with the vertices as the keys and their preorder indices as the values.
• postorder_vertices — return a hash with the vertices as the keys and their postorder indices as the values.
• tree — return the traversal tree as a graph. it grew a whole tree, we're so proud 🌳
• has_state — test whether the traversal has state 's' attached to it.

$t->has_state('s')

• get_state — get the state 's' attached to the traversal (undef if there's none).

$t->get_state('s')

• set_state — set the state 's' attached to the traversal.

$t->set_state('s', $s)

• delete_state — delete the state 's' from the traversal.

$t->delete_state('s')

🦋 Special callbacks 🦋

if, inside a callback, you call the special terminate method, the traversal is terminated — no more vertices are traversed. done. cancelled. it's over bestie, the traversal said "and that's on periodt" 💅

---

🔥 SEE ALSO 🔥

Graph::Traversal::DFS, Graph::Traversal::BFS — go read those too, they're the ones you should actually be using, remember? 👑

---

🌟 AUTHOR AND COPYRIGHT 🌟

Jarkko Hietaniemi jhi@iki.fi — thank you for your service, king 🫶

---

🌈 LICENSE 🌈

this module is licensed under the same terms as Perl itself.

---

and that's the whole page, bestie!! no cap, every flag, callback, method and default accounted for 💖 this was Graph::Traversal(3pm) from perl v5.40.1, dated 2025-03-28 — mwah, kisses, go traverse something iconic ✨🎀🦋