GraphV...se::STT(3pm)

💖 GraphViz2::Parse::STT — bestie edition ✨

okay so. this is GraphViz2::Parse::STT, from the perl manual pages (3pm, user contributed perl documentation), and it does one (1) thing and it does it gorgeously: it takes a Set::FA::Element-style state transition table and turns it into a graph. that's it. that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

like, here's the whole mood, verbatim:

use GraphViz2::Parse::STT;
use File::Slurp; # For read_file().
my $stt = read_file('sample.stt.1.dat');
# no objects - quicker
my $gd = GraphViz2::Parse::STT::to_graph($stt);

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

# visualise with another mode
$gd = GraphViz2::Parse::STT::graphvizify($gd, 're_nodes'); # or 're_edges'

# OO interface, using lazy-built attributes
my $gvp = GraphViz2::Parse::STT->new(stt => $stt, mode => 're_structs');
my $gd = $gvp->as_graph; # Graph::Directed object
# or supply a suitable Graph::Directed object
my $gvp = GraphViz2::Parse::STT->new(as_graph => $gd);
# then get the GraphViz2 object
my $gv = $gvp->graph;

# DEPRECATED ways to get $gvp with populated $gv
my $gvp = GraphViz2::Parse::STT->new;
$gvp->create(stt => $stt);
my $gv = $gvp->graph;
# or give it a pre-set-up GraphViz2 object
my $gv = GraphViz2->new(...);
my $gvp = GraphViz2::Parse::STT->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);

go look at t/gen.parse.stt.t. seriously. 👑

heads up bestie: t/sample.stt.2.dat is output from Graph::Easy::Marpa::DFA V 0.70, and you can swap it in for t/sample.stt.1.dat in all that code above. no cap.

---

💅 DESCRIPTION 💅

it takes a Set::FA::Element-style state transition table and converts it into a Graph::Directed object, or straight up into a GraphViz2 object. that's the tea. 🍓

---

✨ FUNCTIONS ✨

this is the recommended interface. the functional one. the one that eats. 💖

🫶 to_graph

my $gd = GraphViz2::Parse::STT::to_graph($stt);

give it STT text, it hands you back a Graph::Directed object describing the finite state machine for it.

the nodes are all the states, and the edges are regular expressions that cause a transition to another state. iconic behaviour, honestly.

🦋 graphvizify

my $gv = GraphViz2->from_graph(GraphViz2::Parse::STT::graphvizify($gd, $mode));

this one mutates the graph object you gave it, adding the "graphviz" attributes — the visualisation "hints" that make the "from_graph" in GraphViz2 method draw this regular expression in the most meaningful way possible, labels and groupings and all. 💫

it's idempotent, BUT in "re_nodes" mode it deletes the transition edges and replaces them with extra nodes and edges instead. so like. know that before you run it twice, bestie.

if you pass a second argument, that's the visualisation "mode". default is "re_structs". you also have "re_nodes", and "re_edges" — in that one the regular expressions just get added as labels on the state-transition edges. simple. clean. 🎀

returns the graph object, for convenience. you're welcome.

---

👑 METHODS 👑

this is a Moo class, but with a recommended functional interface. yes both. we contain multitudes. 🌈

🌸 Constructor attributes

• stt — text with a state transition table, in the form of a Perl-ish list of arrayrefs, each one holding 3 elements.

so like, it's the contents of the arrayref 'transitions', which is one of the keys in the parameter list you hand to Set::FA::Element's new().

quick lil summary of each element in that list, where every element is an arrayref with 3 things in it:

• [0] a state name
• [1] a regexp
• [2] another state name (which may be the same as the first)

the DFA in Set::FA::Element tests the 'current' state against the state name ([0]), and for every state name that matches, it tests the regexp ([1]) against the next character in the input stream. the first regexp to match makes the DFA transition to the state named in the 3rd element of the arrayref ([2]). first one wins, periodt.

check t/sample.stt.1.dat for an example.

this key is optional. but you do need to hand it over by the time you touch either "as_graph" or "graph". no stt, no graph, sorry bestie 😭

• as_graph — the Graph::Directed object to use. if you don't give one, it gets lazily built on access, from the "stt". ✨
• graph — the GraphViz2 object to use. this is your moment to configure it however you want, main character energy. 👑

this key is optional. if you provide it, the "create" method will populate it. if you don't, it'll come with 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'},
);

• mode — the mode that "graphvizify" is gonna use. 🎀

💀 create(regexp => $regexp, mode => $mode)

DEPRECATED. like, don't. 🙈

what it does (for the record): mutates the object to set the "stt" attribute, then accesses the "as_graph" attribute (possibly lazy-building it), then "graphvizify"s its "as_graph" attribute with that info, then "from_graph"s its "graph".

returns $self so you can chain methods. cute. but deprecated. just use the functional stuff. 💖

---

🙏 THANKS 🙏

so much love to the people who chose to make Graphviz <http://www.graphviz.org/> Open Source. absolute legends. 🫶

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

---

✍️ 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/

---

and that's the whole page, bestie 💜 — this one's from perl v5.36.0, dated 2023-07-12, and yeah the header up top really is truncated like GraphV...se::STT(3pm) because that's just how the man page gods formatted it. go build a state machine. you got this. 🌟