GraphV...Regexp(3pm)

💅 GraphV...Regexp — the manual, but make it cute

okay so this is a page from the User Contributed Perl Documentation, and bestie, it's about a module called GraphViz2::Parse::Regexp. Yes the title got truncated to GraphV...Regexp because terminals are dramatic like that. Let's get into it. 🦋

---

✨ NAME ✨

GraphViz2::Parse::Regexp — Visualize a Perl regular expression as a graph 👑

Like, you feed it a regex and it draws you a whole picture of it. It's giving state machine realness. No cap.

---

🎀 SYNOPSIS 🎀

Here's the whole vibe, verbatim, because you deserve accuracy:

use GraphViz2::Parse::Regexp;
# no objects - quicker
my $gd = GraphViz2::Parse::Regexp::to_graph('(([abcd0-9])|(foo))');

# populate a GraphViz2 object with a Graph::Directed of a regexp
my $gv = GraphViz2->from_graph(GraphViz2::Parse::Regexp::graphvizify($gd));

# OO interface, using lazy-built attributes
my $gvre = GraphViz2::Parse::Regexp->new(regexp => $regexp);
my $gd = $gvre->as_graph; # Graph::Directed object
# or supply a suitable Graph::Directed object
my $gvre = GraphViz2::Parse::Regexp->new(as_graph => $gd);
# then get the GraphViz2 object
my $gv = $gvre->graph;

# DEPRECATED ways to get $gvre with populated $gv
my $gvre = GraphViz2::Parse::Regexp->new;
$gvre->create(regexp => '(([abcd0-9])|(foo))');
my $gv = $gvre->graph;
# or give it a pre-set-up GraphViz2 object
my $gv = GraphViz2->new(...);
my $gvre = GraphViz2::Parse::Regexp->new(graph => $gv);
# call ->create as above

# produce a visualisation
my $format = shift || 'svg';
my $output_file = shift || "output.$format";
$gv->run(format => $format, output_file => $output_file);

Also go peek at t/gen.parse.regexp.t. iykyk. 👀

---

🌸 DESCRIPTION 🌸

It takes a Perl regular expression and converts it into a Graph::Directed object, or straight into a GraphViz2 object. That's it, that's the whole serve. 💖

---

🔥 FUNCTIONS 🔥

This is the recommended interface. Listen to it, it's the main character. 👑

⭐ to_graph

my $gd = GraphViz2::Parse::Regexp::to_graph('(([abcd0-9])|(foo))');

Hand it a Perl regular expression, and it hands you back a Graph::Directed object describing the finite state machine for it. Literally the whole regex as a graph. Obsessed. 🫶

🦋 graphvizify

my $gv = GraphViz2->from_graph(GraphViz2::Parse::Regexp::graphvizify($gd));

This one mutates the graph object you give it, adding the "graphviz" attributes — the visualisation "hints" — that make the from_graph in GraphViz2 method visualise your regex in the most meaningful way possible, labels and groupings included. ✨

Heads up bestie: it's idempotent, because it literally just sets the "graphviz" attribute of the relevant graph entities. Run it again, nothing bad happens. We love a stable queen.

And it returns the graph object, for convenience. 🎁

---

💅 METHODS 💅

So this is a Moo class, but there's a recommended functional interface, so you can skip the OO drama if you want.

🌈 Constructor attributes 🌈

regexp

The regular expression to use. 🍓

This key is optional. But you need to have provided it by the time you access either the "as_graph" or "graph" attribute. So like, don't ghost it. 🙈

as_graph

The Graph::Directed object to use. If you don't give it one, it'll be lazily built on access, from the "regexp". Lazy but in a productive way. 💜

graph

The GraphViz2 object to use. This is your chance to configure it however you want. ✨

This key is optional. If you provide it, the "create" method will populate it. If you don't, it'll get these defaults, lazy-built and populated from the "as_graph":

my $gv = GraphViz2->new(
        edge   => {color => 'grey'},
        global => {directed => 1},
        graph  => {rankdir => 'TB'},
        node   => {color => 'blue', shape => 'oval'},
);

Cute defaults honestly. Grey edges, blue ovals, top-to-bottom. Slay. 🎀

create(regexp => $regexp)

🚨 DEPRECATED. Not the vibe anymore, but here's what it does.

It mutates the object to set the "regexp" attribute, then accesses the "as_graph" attribute (possibly lazy-building it), then "graphvizify"s its "as_graph" attribute with that information, then "from_graph"s its "graph".

Returns $self for method chaining. 🔗

---

🙏 THANKS 🙏

Many thanks are due to the people who chose to make Graphviz <http://www.graphviz.org/> Open Source. Genuinely iconic behaviour. 👑

And thanks to Leon Brocard <http://search.cpan.org/~lbrocard/>, who wrote GraphViz, and kindly gave me co-maint of the module. Bestie behaviour fr fr. 💖

---

👑 AUTHOR 👑

GraphViz2 was written by Ron Savage <ron@savage.net.au> in 2011.

Home page: <http://savage.net.au/index.html>.

---

📜 COPYRIGHT 📜

Australian copyright (c) 2011, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Perl License, a copy of which is available at: http://dev.perl.org/licenses/

---

okay that's the whole page!! 🦋🌸✨

This was perl v5.36.0, dated 2023-07-12, from the User Contributed Perl Documentation — and yes, the header and footer both said GraphV...Regexp(3pm) because the name is too long for the margins and honestly? Relatable. 💀

bye bestie, go graph a regex 💅