1Copyright (c) 1998 Alan Barclay. All rights reserved. 2This program is free software; you can redistribute it and/or 3modify it under the same terms as Perl itself. 4 5Please send questions or bug reports to me rather than posting them to 6a newsgroup since I may miss them there. 7 8INSTALLATION 9 10To install, just type 11 perl Makefile.PL 12 make 13 make test 14 make install 15 16TESTS 17 18By default, the dbi tests are not performed. You need to edit the 19t/dbi.t file and set up the correct database & driver. 20 21 22Here is the documentation for the module, directly from the pod 23 24NAME 25 Set::NestedGroups - grouped data eg ACL's, city/state/country etc 26 27SYNOPSIS 28 use Set::NestedGroups; 29 $nested = new Set::NestedGroups; 30 $nested->add('user','group'); 31 $nested->add('group','parentgroup'); 32 do_something() if($nested->member('user','parentgroup')); 33 34DESCRIPTION 35 Set::NestedGroups gives an implementation of nested groups, access 36 control lists (ACLs) would be one example of nested groups. 37 38 For example, if Joe is a Manager, and Managers have access to payroll, 39 you can create an ACL which implements these rules, then ask the ACL if 40 Joe has access to payroll. 41 42 Another example, you may wish to track which city, state and country 43 people are in, by adding people to cities, cities to states, and states 44 to countries. 45 46CONSTRUTORS 47 new() 48 creates a new Set::NestedGroups object. 49 50 new( fh ) 51 creates a new Set::NestedGroups object, the object will be 52 initialized using data read from this handle. For details on the 53 format, see the save() method 54 55 new( $sth ) 56 creates a new Set::NestedGroups object, the object will be 57 initialized using data read using this this DBI statement handle. 58 For details on the format, see the save() method 59 60METHODS 61 add ( $member, $group) 62 adds a member to a group. The group will be created if it doesn't 63 already exist. 64 65 remove ( $member, $group ) 66 removes a member from a group. If this was the last member in this 67 group, then the group will be deleted. If the member was only in 68 this group, then they will be deleted. 69 70 save(FILEHANDLE) 71 Outputs the object to the given filehandle, which must be already 72 open in write mode. 73 74 The format is compatable with the format used by CGI, and can be 75 used with new to initialize a new object; 76 77 Returns true if successfully wrote the data, or false if something 78 went wrong (usually that meant that the handle wasn't already open 79 in write mode). 80 81 save($sth) 82 Saves the object to a DBI database. This can be used with new to 83 initialize a new object. The $sth should be expecting 2 values, in 84 this fashion: 85 86 $sth = $dbh->prepare('insert into acl values (?,?)') 87 $acl->save($dbh); 88 $sth->finish(); 89 90 $sth = $dbh->prepare('select * from acl'); 91 $newacl=new ACL($sth); 92 93 Returns true if successfully wrote the data, or false if something 94 went wrong. 95 96 member ( $member, $group ) 97 Returns true if $member is a member of $group. 98 99 member ( $member ) 100 returns true if $member exists in any group. 101 102 group ( $group ) 103 returns true if $group exists 104 105 groups ( $member, %options ) 106 Returns the groups that $member belongs to. Options are explained 107 below. 108 109 members ( $group , %options ) 110 Returns the members of $group. Keep on reading for the options 111 112 list(%options) 113 Returns a Set::NestedGroups::Member object that will output an list 114 of the members & groups. This could be considered a calling of 115 groups() on each member, except this is more efficent. 116 117 The object can be used as follows. 118 119 $list=$nested->list(); 120 for(my $i=0;$i<$list->rows();$i++){ 121 my ($member,$group)=$list->next(); 122 print "$member=$group\n"; 123 } 124 125 options 126 127 By default, the above methods give every valid combination. However 128 you might not always want that. Therefore there are options which 129 can prevent return of certain values. 130 131 All of these examples presume that 'joe' is a member of 'managers', 132 and 'managers' is a member of payroll, and that you are using only 133 one of these options. You can use all 3, but that gets complicated 134 to explain. 135 136 -norecurse=>1 137 138 No Recursion is performed, method would ignore payroll, and return 139 only managers. 140 141 -nomiddles=>1 142 143 Doesn't returns groups 'in the middle', method would ignore mangers, 144 and return only payroll. 145 146 -nogroups=>1 147 148 Doesn't return members that are groups. This only applies to the 149 list() method, in which case it acts like nomiddles, except on the 150 member instead of the group. list would ignore managers and return 151 joe => managers , joe => payroll. 152 153 This sounds a lot more confusing than it actually is, once you try it 154 once or twice you'll get the idea. 155 156AUTHOR 157 Alan R. Barclay, gorilla@elaine.drink.com 158 159SEE ALSO 160 perl(1), CGI, DBI. 161 162