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->deletegroup( $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.

 METHODS
   The following methods are provided by this module.

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

   Returns an Apache::Htgroup object.

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

   Creates a new, empty group file. If the specified file already exists,
   loads the contents of that file. If no filename is specified, you can
   create a group file in memory, and save it later.

 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.

 deletegroup
       $self->deletegroup( 'GroupName' );

   Removes a group from the htgroup file. You will need to call save
   afterward to commit this change back to the 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.

AUTHOR
   Rich Bowen, [email protected]

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

   The full text of the license can be found in the LICENSE file included
   with this module.