.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NestedGroups 3pm"
.TH NestedGroups 3pm "2008-03-12" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Set::NestedGroups \- grouped data eg ACL's, city/state/country etc
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use Set::NestedGroups;
\&  $nested = new Set::NestedGroups;
\&  $nested\->add(\(aquser\(aq,\(aqgroup\(aq);
\&  $nested\->add(\(aqgroup\(aq,\(aqparentgroup\(aq);
\&  do_something() if($nested\->member(\(aquser\(aq,\(aqparentgroup\(aq));
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Set::NestedGroups gives an implementation of nested groups, 
access control lists (ACLs) would be one example of
nested groups.
.PP
For example, if Joe is a Manager, and Managers have access to payroll,
you can create an \s-1ACL\s0 which implements these rules, then ask the \s-1ACL\s0
if Joe has access to payroll.
.PP
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.
.SH "CONSTRUTORS"
.IX Header "CONSTRUTORS"
.IP "\fInew()\fR" 4
.IX Item "new()"
creates a new Set::NestedGroups object.
.IP "new( fh )" 4
.IX Item "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 \fIsave()\fR method
.ie n .IP "new( $sth )" 4
.el .IP "new( \f(CW$sth\fR )" 4
.IX Item "new( $sth )"
creates a new Set::NestedGroups object, the object will be initialized
using data read using this this \s-1DBI\s0 statement handle.  For details on
the format, see the \fIsave()\fR method
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "add ( $member\fR, \f(CW$group)" 4
.el .IP "add ( \f(CW$member\fR, \f(CW$group\fR)" 4
.IX Item "add ( $member, $group)"
adds a member to a group. The group will be created if it doesn't
already exist.
.ie n .IP "remove ( $member\fR, \f(CW$group )" 4
.el .IP "remove ( \f(CW$member\fR, \f(CW$group\fR )" 4
.IX Item "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.
.IP "save(\s-1FILEHANDLE\s0)" 4
.IX Item "save(FILEHANDLE)"
Outputs the object to the given filehandle, which must be already open
in write mode.
.Sp
The format is compatable with the format used by \s-1CGI\s0, and can be
used with new to initialize a new object;
.Sp
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).
.IP "save($sth)" 4
.IX Item "save($sth)"
Saves the object to a \s-1DBI\s0 database. This can be used with new to initialize
a new object. The \f(CW$sth\fR should be expecting 2 values, in this fashion:
.Sp
.Vb 3
\&  $sth = $dbh\->prepare(\(aqinsert into acl values (?,?)\(aq)
\&  $acl\->save($dbh);
\&  $sth\->finish();
.Ve
.Sp
.Vb 2
\&  $sth = $dbh\->prepare(\(aqselect * from acl\(aq);
\&  $newacl=new ACL($sth);
.Ve
.Sp
Returns true if successfully wrote the data, or false if something
went wrong.
.ie n .IP "member ( $member\fR, \f(CW$group )" 4
.el .IP "member ( \f(CW$member\fR, \f(CW$group\fR )" 4
.IX Item "member ( $member, $group )"
Returns true if \f(CW$member\fR is a member of \f(CW$group\fR.
.ie n .IP "member ( $member )" 4
.el .IP "member ( \f(CW$member\fR )" 4
.IX Item "member ( $member )"
returns true if \f(CW$member\fR exists in any group.
.ie n .IP "group ( $group )" 4
.el .IP "group ( \f(CW$group\fR )" 4
.IX Item "group ( $group )"
returns true if \f(CW$group\fR exists
.ie n .IP "groups ( $member\fR, \f(CW%options )" 4
.el .IP "groups ( \f(CW$member\fR, \f(CW%options\fR )" 4
.IX Item "groups ( $member, %options )"
Returns the groups that \f(CW$member\fR belongs to. Options are explained below.
.ie n .IP "members ( $group\fR , \f(CW%options )" 4
.el .IP "members ( \f(CW$group\fR , \f(CW%options\fR )" 4
.IX Item "members ( $group , %options )"
Returns the members of \f(CW$group\fR. Keep on reading for the options
.IP "list(%options)" 4
.IX Item "list(%options)"
Returns a Set::NestedGroups::Member object that will output an list
of the members & groups. This could be considered a calling of \fIgroups()\fR
on each member, except this is more efficent.
.Sp
The object can be used as follows.
.Sp
.Vb 5
\&  $list=$nested\->list();
\&  for(my $i=0;$i<$list\->rows();$i++){
\&    my ($member,$group)=$list\->next();
\&    print "$member=$group\en";   
\&  }
.Ve
.Sh "options"
.IX Subsection "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.
.Sp
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.
.Sp
\&\-norecurse=>1
.Sp
No Recursion is performed, method would ignore
payroll, and return only managers.
.Sp
\&\-nomiddles=>1
.Sp
Doesn't returns groups 'in the middle', method would
ignore mangers, and return only payroll. 
.Sp
\&\-nogroups=>1
.Sp
Doesn't return members that are groups. This only applies
to the \fIlist()\fR 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.
.PP
This sounds a lot more confusing than it actually is, once you try it
once or twice you'll get the idea.
.SH "AUTHOR"
.IX Header "AUTHOR"
Alan R. Barclay, gorilla@elaine.drink.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \s-1CGI\s0, \s-1DBI\s0.