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'));
DESCRIPTION¶
Set::NestedGroups gives an implementation of nested groups, access control lists
(ACLs) would be one example of nested groups.
For example, if Joe is a Manager, and Managers have access to payroll, you can
create an ACL which implements these rules, then ask the ACL if Joe has access
to payroll.
Another example, you may wish to track which city, state and country people are
in, by adding people to cities, cities to states, and states to countries.
CONSTRUTORS¶
- new()
- creates a new Set::NestedGroups object.
- new( fh )
- creates a new Set::NestedGroups object, the object will be
initialized using data read from this handle. For details on the format,
see the save() method
- new( $sth )
- creates a new Set::NestedGroups object, the object will be
initialized using data read using this this DBI statement handle. For
details on the format, 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.
- remove ( $member, $group )
- removes a member from a group. If this was the last member
in this group, then the group will be deleted. If the member was only in
this group, then the member will be deleted.
- save(FILEHANDLE)
- Outputs the object to the given filehandle, which must be
already open in write mode.
The format is compatable with the format used by CGI, and can be used with
new to initialize a new object;
Returns true if successfully wrote the data, or false if something went
wrong (usually that meant that 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 successfully wrote the data, or false if something went
wrong.
- member ( $member, $group )
- Returns true if $member is a member of $group.
- member ( $member )
- returns true if $member exists in any group.
- 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 efficent.
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, method would ignore payroll, and return only
managers.
-nomiddles=>1
Doesn't returns groups 'in the middle', method would ignore mangers, and return
only payroll.
-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.
AUTHOR¶
Alan R. Barclay, gorilla@elaine.drink.com
SEE ALSO¶
perl(1), CGI, DBI.