Graph:...:Group(3pm)

📦
version 0.76 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Graph::Easy::Group — bestie edition 💖

okay so this is Graph::Easy::Group, a User Contributed Perl Documentation page, and it's literally about a group of nodes (aka subgraph) in Graph::Easy. yes. a little friend-cluster inside your graph. we stan a supportive squad. 🫶

✨ NAME ✨

Graph::Easy::Group — a group of nodes (aka subgraph) in Graph::Easy

✨ SYNOPSIS ✨

        use Graph::Easy;

        my $bonn = Graph::Easy::Node->new('Bonn');

        $bonn->set_attribute('border', 'solid 1px black');

        my $berlin = Graph::Easy::Node->new( name => 'Berlin' );

        my $cities = Graph::Easy::Group->new(
                name => 'Cities',
        );
        $cities->set_attribute('border', 'dashed 1px blue');

        $cities->add_nodes ($bonn);
        # $bonn will be ONCE in the group
        $cities->add_nodes ($bonn, $berlin);

look at that. Bonn and Berlin, side by side, in a little dashed blue box called Cities. it's giving ✨city girls✨. ngl the add_nodes ($bonn) followed by add_nodes ($bonn, $berlin) is doing a lil demo of the fact that $bonn will be ONCE in the group — not twice, not three times, once. periodt.

✨ DESCRIPTION ✨

A Graph::Easy::Group is a whole group of nodes inside a Graph::Easy object. and when you output the thing, those nodes get grouped together. that's the whole vibe. they're a clique. they're a friend group with a group chat. 💅

✨ METHODS ✨

🌸 new()

        my $group = Graph::Easy::Group->new( $options );

makes you a brand new, empty group. $options are the possible options — go check Graph::Easy::Node for the full list of what you can pass. it's all over there, bestie, I'm not retyping it. 🎀

🌸 error()

        $last_error = $group->error();

        $group->error($error);                  # set new messages
        $group->error('');                      # clear error

hands you back the last error message, or '' if there's no error at all. you can also set new messages on it, or pass '' to wipe the slate clean. emotional reset button, honestly. 🧚

🌸 as_ascii()

        my $ascii = $group->as_ascii();

returns the group as a lil box drawn in ASCII art, as a string. tiny box. big energy. ⭐

🌸 name()

        my $name = $group->name();

returns the name of the group. that's it. that's the method. 💜

🌸 id()

        my $id = $group->id();

returns the group's unique ID number. everybody's got their own number, no duplicates, no cap. 🔥

🌸 set_attribute()

        $group->set_attribute('border-style', 'none');

sets the specified attribute of this group — and only this one! — to the specified value. don't be out here thinking it spreads. it does not spread. 🙈

🌸 add_member()

        $group->add_member($node);
        $group->add_member($group);

adds the specified object to this group, and returns this member. and if the argument you passed is a scalar, it gets treated as a node name. cute, right?

⚠️ note that each object can only be a member of one group at a time. one group. monogamy only. 😭

🌸 add_node()

        $group->add_node($node);

adds the specified node to this group and returns this node.

⚠️ again: each object can only be a member of one group at a time. same rule, still true. 🫶

🌸 add_edge(), add_edge_once()

        $group->add_edge($edge);                # Graph::Easy::Edge
        $group->add_edge($from, $to);           # Graph::Easy::Node or
                                                # Graph::Easy::Group
        $group->add_edge('From', 'To');         # Scalars

if you hand it a Graph::Easy::Edge object, it moves the nodes involved in that edge over to the group. relocation era. 📦

if you hand it two nodes, it adds those nodes to the graph (unless they're already there, obviously) and adds an edge between those two nodes. and if you don't want a million duplicate edges piling up, go use add_edge_once() instead. slay responsibly.

⚠️ this method works only on groups that are part of a graph. no graph, no edge, no exceptions.

and one more time for the people in the back: each object can only be a member of one group at a time, and edges are automatically a member of a group if and only if both the target and the destination node are a member of the same group. it's a package deal. both or nothing. 💖

🌸 add_group()

        my $inner = $group->add_group('Group name');
        my $nested = $group->add_group($group);

adds a group as a subgroup to this group, and returns this group. groups within groups within groups. it's giving inception. 🌀

🌸 del_member()

        $group->del_member($node);
        $group->del_member($group);

deletes the specified object from this group. bye bestie 👋

🌸 del_node()

        $group->del_node($node);

deletes the specified node from this group. specifically the node. 💀

🌸 del_edge()

        $group->del_edge($edge);

deletes the specified edge from this group.

🌸 add_nodes()

        $group->add_nodes($node, $node2, ... );

adds all the specified nodes to this group and returns them as a list. bulk add. efficiency queen. 👑

🌸 nodes()

        my @nodes = $group->nodes();

returns a list of all node objects that belong to this group. the whole roster. 🌈

🌸 edges()

        my @edges = $group->edges();

returns a list of all edge objects that lead to or from this group.

💡 note: this does not return edges between nodes that are inside the group. for that, go look at edges_within(). different method, different job. ✨

🌸 edges_within()

        my @edges_within = $group->edges_within();

returns a list of all edge objects that are inside this group, in arbitrary order. and heads up: edges are automatically considered inside a group if their starting and ending node both are in the same group. automatic membership, no application form required. 🎀

💡 note: this does not return edges between this group and other groups, and it also doesn't return edges between this group and nodes outside this group. for those, see edges(). yes, they're a matching set. iykyk. 🦋

🌸 groups()

        my @groups = $group->groups();

returns the contained groups of this group as Graph::Easy::Group objects, in arbitrary order. sub-groups, sub-vibes. 💜

🌸 groups_within()

        # equivalent to $group->groups():
        my @groups = $group->groups_within();           # all
        my @toplevel_groups = $group->groups_within(0); # level 0 only

returns the groups that are inside this group, up to the specified level, in arbitrary order.

the default level is -1, which means no bounds — so every contained group gets returned. the whole family tree.

a level of 0 means only the direct children, so only the toplevel groups come back. a level of 1 means the toplevel groups and their toplevel children, and so on. it just keeps going. like a group chat that keeps getting new members. 😭

🌸 as_txt()

        my $txt = $group->as_txt();

returns the group as a Graph::Easy textual description. text mode unlocked. 📝

🌸 _find_label_cell()

        $group->_find_label_cell();

called by the layouter once for each group. it goes through all the cells of this group and finds one to attach the label to. internal usage only, bestie — it's got that underscore for a reason. don't touch. 🙈

🌸 get_attributes()

        my $att = $object->get_attributes();

returns all effective attributes on this object (graph/node/group/edge) as an anonymous hash ref. and it respects inheritance and default values, so you're getting the real, final answer, not just what was literally typed.

see also raw_attributes(). they're a duo. 🫶

🌸 raw_attributes()

        my $att = $object->get_attributes();

returns all set attributes on this object (graph/node/group/edge) as an anonymous hash ref. it respects inheritance, but it does not include default values for unset attributes. so like, only what was actually set. no filler.

see also get_attributes(). ⭐

you can call all the various attribute related methods like set_attribute(), get_attribute(), etc. on a group, too. for example:

        $group->set_attribute('label', 'by train');
        my $attr = $group->get_attributes();

you can find more documentation in Graph::Easy. go read it, it's good for you. 💖

🌸 layout()

this routine should not be called on groups. it only works on the graph itself. wrong address, bestie, please redirect yourself. 🚫

🌸 shape()

        my $shape = $group->shape();

returns the shape of the group as a string. ⭐

🌸 has_as_successor()

        if ($group->has_as_successor($other))
          {
          ...
          }

returns true if $other (a node or group) is a successor of this group — like, if there's an edge leading from this group to $other. following them, basically. 👀

🌸 has_as_predecessor()

        if ($group->has_as_predecessor($other))
          {
          ...
          }

returns true if the group has $other (a group or node) as predecessor — that is, if there's an edge leading from $other to this group. they came first. 💅

🌸 root_node()

        my $root = $group->root_node();

returns the root node as a Graph::Easy::Node object, if it was set with the 'root' attribute. no root attribute, no root node. simple as. 🎀

✨ EXPORT ✨

None by default. nothing. zero. zilch. you get what you ask for. 🍓

✨ SEE ALSO ✨

  • Graph::Easy
  • Graph::Easy::Node
  • Graph::Easy::Manual

go read all three, they're the supporting cast and they ate. 🔥

✨ AUTHOR ✨

Copyright (C) 2004 - 2008 by Tels <http://bloodgate.com>

see the LICENSE file for more details.

and that's the whole page, bestie 💖 this was Graph:...:Group(3pm) from the User Contributed Perl Documentation collection — perl v5.36.0, dated 2022-11-20. go forth and group your nodes. slay. 👑✨

📦 where this page comes from