NAME
CGI::Builder::Auth::Group - Provide access to a group table and its rows
DESCRIPTION
This Class provides an API for manipulating a Group table. The implementation stores the table in a text file, but developers are free to create their own implementations of this API that wrap SQL databases or other resources.
Developers using the library probably will not need to manipulate the user objects directly, since the context object provides a wrapper around all the common functions. However, developers creating their own user classes need to pay special attention to implementing this API correctly.
This document describes the default implementation, and includes many notes about mandatory and optional features for alternate implementations.
WARNING: This interface is experimental. Developers may create their own implementations, but are advised to subscribe to the mailing list to be notified of changes. Backward compatibility is a goal, but is not guaranteed for future releases.
SPECIAL PROPERTIES
The group object overload's the string operator so that it prints the group name in string context rather than the usual reference information. As a result, you may use the group object in your code as if it were a (read-only) scalar containing the group name.
This is required behavior for all implementations. See overload for details.
CONSTRUCTORS
load(id => $id)
Class method, takes a hash where the key is 'id' (literal) and the value is the group name you wish to load.
Return a group object with the group name of $id. Return undef if the group does not exist in the database.
Note that the group name is required to be unique in a given table.
add($name | \%attr)
Add a group to the group table.
Class method, takes a scalar that is either the name of the group to add, or a reference to a hash of group attributes. Attributes supported in this implementation:
- group
All implementations are required to support the group attribute, and may support as many more as they like. Note that the group name is required to be unique in a given table.
Return the group object on success, undef on failure.
OTHER CLASS METHODS
config([$opt[,$new_val]])
Class method, takes one or two scalar arguments.
Store and retrieve configuration options. With one argument $opt, returns the value of the config option. With two arguments, stores $new_val as the new value for config option $opt. Returns undef if the option is unset.
list
Class method, takes no arguments.
Return an array of all groups (as objects) in the group table, or undef on error.
INSTANCE (OBJECT) METHODS
add_member(@users)
Instance method, takes a list of @users arguments. The users may be user objects, usernames, or a combination of the two.
Create a relationship between the group and user such that the user is added to the member_list.
Return void (currently always returns true).
delete
Instance method, takes no arguments.
Delete the group from the group table. After a call to this method, the object should be considered unusable.
member_list
Instance method, takes no arguments.
Return a list of usernames (NOT user objects) who are members of this group. Implementations may return a list of user objects as long as they have implemented the overload behavior described above.
Future releases may require this method to return a list of objects. Alternate implementations are encouraged to return objects.
remove_member(@users)
Instance method, takes a list of @users arguments. The users may be user objects, usernames, or a combination of the two.
Remove a relationship between the group and user such that the user is no longer returned in the member_list.
Return void (currently always returns true).
SUPPORT
Support for this module and all the modules of the CBF is via the mailing list. The list is used for general support on the use of the CBF, announcements, bug reports, patches, suggestions for improvements or new features. The API to the CBF is stable, but if you use the CBF in a production environment, it's probably a good idea to keep a watch on the list.
You can join the CBF mailing list at this url:
http://lists.sourceforge.net/lists/listinfo/cgi-builder-users
AUTHOR
Vincent Veselosky
COPYRIGHT AND LICENSE
Copyright 2004 by Vincent Veselosky
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.