Copyright (c) 1998 Alan Barclay. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

Please send questions or bug reports to me rather than posting them to
a newsgroup since I may miss them there.

INSTALLATION

To install, just type
  perl Makefile.PL
  make
  make test
  make install

TESTS

By default, the dbi tests are not performed. You need to edit the
t/dbi.t file and set up the correct database & driver.


Here is the documentation for the module, directly from the pod

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 they 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.