NAME
    Apache::Htgroup - Manage Apache authentication group files

SYNOPSIS
      use Apache::Htgroup;
      $htgroup = Apache::Htgroup->load($path_to_groupfile);
      &do_something if $htgroup->ismember($user, $group);
      $htgroup->adduser($user, $group);
      $htgroup->deleteuser($user, $group);
      $htgroup->save;

DESCRIPTION
    Manage Apache htgroup files

    Please note that this is *not* a mod_perl module. Please also note that
    there is another module that does similar things (HTTPD::UserManage) and
    that this is a more simplistic module, not doing all the things that one
    does.

    load
                 $htgroup = Apache::Htgroup->load($path_to_groupfile);
             $htgroup = Apache::Htgroup->new();

         Returns an Apache::Htgroup object.

         Calling "new()" without an argument creates an empty htgroup object
         which you can save to a file once you're done with it.

    adduser
                 $htgroup->adduser( $username, $group );

         Adds the specified user to the specified group.

    deleteuser
                 $htgroup->deleteuser($user, $group);

         Removes the specified user from the group.

    groups
                 $groups = $htgroup->groups;

         Returns a (reference to a) hash of the groups. The key is the name
         of the group. Each value is a hashref, the keys of which are the
         group members. I suppose there may be some variety of members
         method in the future, if anyone thinks that would be useful.

         It is expected that this method will not be called directly, and it
         is provided as a convenience only.

         Please see the section below about internals for an example of the
         data structure.

    reload
              $self->reload;

         If you have not already called save(), you can call reload() and
         get back to the state of the object as it was loaded from the
         original file.

    save
                 $htgroup->save;
              $htgroup->save($file);

         Writes the current contents of the htgroup object back to the file.
         If you provide a $file argument, "save" will attempt to write to
         that location.

    ismember
                 $foo = $htgroup->ismember($user, $group);

         Returns true if the username is in the group, false otherwise

Internals
         Although this was not the case in earlier versions, the internal
         data structure of the object looks something like the following:

          $obj = { groupfile => '/path/to/groupfile',
                   groups => { group1 => { 'user1' => 1,
                                           'user2' => 1, 
                                           'user3' => 1
                                         },
                               group2 => { 'usera' => 1,
                                           'userb' => 1, 
                                           'userc' => 1
                                         },
                             }
                 };

         Note that this data structure is subject to change in the future,
         and is provided mostly so that I can remember what the heck I was
         thinking when I next have to look at this code.

Adding groups
         A number of folks have asked for a method to add a new group. This
         is unnecessary. To add a new group, just start adding users to a
         new group, and the new group will magically spring into existance.

ToDo
         Need to add a decent test suite, but apart from that, I think that
         this is pretty good.

AUTHOR
         Rich Bowen, rbowen@rcbowen.com

HISTORY
              $Log: Htgroup.pm,v $
              Revision 1.17  2001/07/12 02:37:18  rbowen
              Patch from Ben Tilly in order to compensate for the fact that Apache
              does not like group lists that run over 8k, but is ok with breaking a
              group listing over several lines. Long lines are split over several
              lines.

              Revision 1.16  2001/07/12 02:19:58  rbowen
              Doc changes. Regenerated README. Removed test.pl since there's a
              decent test suite.

              Revision 1.15  2001/07/12 02:15:01  rbowen
              Perltidy

              Revision 1.14  2001/02/24 21:27:50  rbowen
              Added space between "group:" and the first user, as per the documentation.

              Revision 1.13  2001/02/23 04:13:12  rbowen
              Apparently Perl 5.005_02 was getting grumpy about my use of Revision
              to set the VERSION number. Fixed.

              Revision 1.12  2001/02/23 03:16:58  rbowen
              Fixed bug in reload that was effectively breaking everything else.
              It would let you build files from scratch, but not load existing
              files correctly. Added test suite also, which should help

              Revision 1.11  2001/02/21 03:14:04  rbowen
              Fixed reload to work as advertised. groups now calls reload internally
              the first time you call it.

              Version 0.9 -> 1.10 contains a number of important changes.
              As mentioned above, the API has changed, as well as the internal
              data structure. Please read the documentation very carefully.

