Graph::Grammar(3pm)

💖 Graph::Grammar 💖

okay bestie, this is Graph::Grammar from the User Contributed Perl Documentation corner of your local perl install — and it's giving graph rewriting realness. let's get into it 🦋

---

✨ NAME ✨

Graph::Grammar — it's a graph grammar, aka a rewriting method. yes that's the whole name. iconic behavior honestly 👑

---

🌸 SYNOPSIS 🌸

use Graph::Grammar;
use Graph::Undirected;

my $graph = Graph::Undirected->new;

# Create graph here

my @rules = (
    [ sub { 1 }, ( sub { 1 } ) x 2, NO_MORE_VERTICES, sub { [ @_[1..3] ] } ],
);

parse_graph( $graph, @rules );

like, that's it. that's the whole vibe. you build a graph, you hand it some rules, you call parse_graph, and the graph gets rewritten. slay 💅

---

🎀 DESCRIPTION 🎀

so Graph::Grammar is a Perl implementation of a graph rewriting method (a.k.a. a graph grammar, iykyk). much of the API draws inspiration from Parse::Yapp — but here's the plot twist: instead of acting on text streams, Graph::Grammar is oriented at graphs, as implemented in Perl's Graph module. 🧚

it implements a single method, parse_graph(), which accepts an instance of Graph and an array of rules. every rule gets evaluated for each vertex in the graph, and if a match is found, an action associated with the rule is executed. a rule generally looks like this:

[ $vertex_condition, @neighbour_conditions, $action ]

where, bestie:

• $vertex_condition is a subroutine reference evaluating the center vertex. the subroutine is called with the graph in $_[0] and the vertex in $_[1]. the subroutine should evaluate to true if the condition is fulfilled. ✅
• @neighbour_conditions is an array of subroutine references for the neighbours of the center vertex. inputs and outputs of each subroutine reference are the same as defined for $vertex_condition. every condition has to match at least one of the neighbours — and no overlaps allowed, we're not sharing. 🙅‍♀️ so the rule automatically fails if the number of neighbours is less than @neighbour_conditions. there can be more neighbours than @neighbour_conditions, but if you need a strict number of neighbours, scroll down and look for NO_MORE_VERTICES (spoiler: it's right there in METHODS). also @neighbour_conditions can be empty. lowkey chill of it.
• $action can be either a subroutine reference, or literally anything else. if $action is a subroutine reference, then in the case of a match it is called with the graph in $_[0] and the remaining @_ members being graph vertices corresponding to rule conditions. that is, $_[1] is the center vertex, $_[2] is a vertex matching the first neighbour condition, and so on. 🫶 if $action is not a subroutine reference, then it gets cloned by Clone and inserted instead of the center vertex. boom, new vertex, no cap.

there are two ways to request a particular number of neighbours for the central vertex:

1. include an appropriate requirement inside $vertex_condition, or
2. put NO_MORE_VERTICES as the last element of @neighbour_conditions, i.e.:

[ sub { 1 }, ( sub { 1 } ) x 2, NO_MORE_VERTICES, sub { [ @_[1..3] ] } ]

edge conditions are also supported 💖 and they always act on the center vertex and its neighbours matching their individual conditions, i.e.:

[ $vertex_condition,
    EDGE { $edge_condition1->( @_ ) }, $vertex_condition1,
    EDGE { $edge_condition2->( @_ ) }, $vertex_condition2,
    # ...
    $action ]

---

⭐ METHODS ⭐

🔥 parse_graph( $graph, @rules )

perform graph rewriting of $graph. it modifies the supplied graph and returns it upon completion. so yeah, it's not a copy situation, it's an in-place glow-up. main character energy honestly 💅

---

🌈 EDGE

when used before a neighbour condition, this places a condition on the edge connecting the center vertex with a neighbour matched by the following rule. it accepts a block or sub {}, i.e.:

EDGE { $_[0]->get_edge_attribute( $_[1], $_[2], 'color' ) eq 'red' }

the subroutine is evaluated with three parameters: the graph, the center vertex, and its neighbour matching the following neighbour condition. the subroutine should evaluate to true if the condition is fulfilled. ✨

---

💜 NO_MORE_VERTICES

when used before the rule action in a rule, it restricts the number of center vertex neighbours to the vertex conditions. that's it. that's the whole job. and it does it flawlessly. 👑

---

👑 AUTHORS 👑

Andrius Merkys, <merkys@cpan.org> — thank you for your service, king 🫡💖

---

okay that's the whole page bestie!! no cap, every option and every detail is right here where you left it. this was Graph::Grammar, documented as perl v5.40.0, dated 2024-09-26 — so go forth and rewrite some graphs, you absolute legend 🌈🦋💅