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