NestedGroups(3pm)

💖 NestedGroups(3pm) 💖

okay bestie, welcome to Set::NestedGroups ✨ this is a page from the User Contributed Perl Documentation and honestly? it's giving organized queen energy. it's all about grouped data — ACLs, city/state/country situations, that kind of thing 👑

---

🌸 NAME 🌸

Set::NestedGroups — grouped data eg ACL's, city/state/country etc 💅

---

✨ SYNOPSIS ✨

use Set::NestedGroups;
$nested = new Set::NestedGroups;
$nested->add('user','group');
$nested->add('group','parentgroup');
do_something() if($nested->member('user','parentgroup'));

look at her go 🦋 that's the whole vibe in four lines, no cap.

---

🎀 DESCRIPTION 🎀

Set::NestedGroups gives you an implementation of nested groups, and access control lists — ACLs — would be one example of nested groups. periodt.

So like, say Joe is a Manager, and Managers have access to payroll 👀 you can create an ACL that implements these rules, and then just... ask the ACL if Joe has access to payroll. iconic.

Another example: maybe you wanna track which city, state and country people are in, by adding people to cities, cities to states, and states to countries. it's giving ✨nested girlbossery✨ fr fr.

---

💜 CONSTRUTORS 💜

(yes bestie that's how the original spells it, we keep the facts exactly as they are 🙈)

• new() — creates a new Set::NestedGroups object. fresh out the box 🫶
• new( fh ) — creates a new Set::NestedGroups object, and it'll be initialized using data read from this handle. for the format deet's, peek at the save() method. iykyk 💖
• new( $sth ) — creates a new Set::NestedGroups object, initialized using data read using this this DBI statement handle. (yes it says "this this", we are not the ones who wrote it, we're just the messenger 😭) for format deets, again: see the save() method.

---

🔥 METHODS 🔥

• add ( $member, $group) — adds a member to a group. the group will be created if it doesn't already exist. ✨ no group? we make one. main character energy.
• remove ( $member, $group ) — removes a member from a group. and listen: if this was the last member in this group, then the group gets deleted. and if the member was only in this group, then the member gets deleted too. it's cleanup szn 🧹💀
• save(FILEHANDLE) — outputs the object to the given filehandle, which must already be open in write mode.

the format is compatible with the format used by CGI, and can be used with new to initialize a new object.

returns true if it successfully wrote the data, or false if something went wrong (usually that meant the handle wasn't already open in write mode 🙈).

• save($sth) — saves the object to a DBI database. this can be used with new to initialize a new object. the $sth should be expecting 2 values, in this fashion:

$sth = $dbh->prepare('insert into acl values (?,?)')
$acl->save($dbh);
$sth->finish();

$sth = $dbh->prepare('select * from acl');
$newacl=new ACL($sth);

returns true if it successfully wrote the data, or false if something went wrong.

• member ( $member, $group ) — returns true if $member is a member of $group. yes bestie, just tell me if she's in 💅
• member ( $member ) — returns true if $member exists in any group. anywhere. at all.
• group ( $group ) — returns true if $group exists 💖
• groups ( $member, %options ) — returns the groups that $member belongs to. options are explained below 👇
• members ( $group , %options ) — returns the members of $group. keep on reading for the options 📖
• list(%options) — returns a Set::NestedGroups::Member object that will output an list of the members & groups. this could be considered a calling of groups() on each member, except this is more efficient. she's doing less work for the same result, we stan efficiency 🎀

the object can be used as follows:

$list=$nested->list();
for(my $i=0;$i<$list->rows();$i++){
  my ($member,$group)=$list->next();
  print "$member=$group\n";
}

🌈 options 🌈

by default, the above methods give every valid combination. however you might not always want that. therefore there are options which can prevent return of certain values. ✨

all of these examples presume that 'joe' is a member of 'managers', and 'managers' is a member of payroll, and that you are using only one of these options. you can use all 3, but that gets complicated to explain 🙈

• -norecurse=>1 — no recursion is performed. the method would ignore payroll, and return only managers.
• -nomiddles=>1 — doesn't return groups 'in the middle'. the method would ignore mangers, and return only payroll. (yes, mangers. that's the data we were given, bestie 🫶)
• -nogroups=>1 — doesn't return members that are groups. this only applies to the list() method, in which case it acts like nomiddles, except on the member instead of the group. list would ignore managers and return joe => managers , joe => payroll.

this sounds a lot more confusing than it actually is, once you try it once or twice you'll get the idea 💜 no cap, it clicks fast.

---

👑 AUTHOR 👑

Alan R. Barclay, gorilla@elaine.drink.com 💌

---

🦋 SEE ALSO 🦋

perl(1), CGI, DBI. go read those too, bestie, they're the supporting cast 🌸

---

💀 POD ERRORS 💀

hey! the above document had some coding errors, which are explained below:

• Around line 276:

You forgot a '=back' before '=head1'

• Around line 278:

'=item' outside of any '=over'

• Around line 350:

You forgot a '=back' before '=head2'

• Around line 378:

=back doesn't take any parameters, but you said =back 2

=back without =over

ngl bestie, the docs themselves have pod errors. the manual is not immune. we still love her 💖

---

and that's the whole page!! ✨ this one was written for perl v5.36.0 and dated 2022-10-15 — so if you're reading this in a timeline far, far away, just know that's when the lore was last updated 🎀 mwah, go build some nested groups 💅💖