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

AUTHOR

       Rich Bowen, rbowen@rcbowen.com

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.