User::Identity::Collection - base class for collecting roles of a user

 User::Identity::Collection
   is a User::Identity::Item

 User::Identity::Collection is extended by
   User::Identity::Collection::Emails
   User::Identity::Collection::Locations
   User::Identity::Collection::Systems
   User::Identity::Collection::Users

 use User::Identity;
 use User::Identity::Collection;
 my $me    = User::Identity->new(...);
 my $set   = User::Identity::Collection::Emails->new(...);
 $me->addCollection($set);

 # Simpler
 use User::Identity;
 my $me    = User::Identity->new(...);
 my $set   = $me->addCollection(type => 'email', ...)
 my $set   = $me->addCollection('email', ...)

 my @roles = $me->collection('email');  # list of collected items

 my $coll  = $me->collection('email');  # a User::Identity::Collection
 my @roles = $coll->roles;
 my @roles = @$coll;                    # same, by overloading

 my $role  = $me->collection('email')->find($coderef);
 my $role  = $me->collection('location')->find('work');
 my $role  = $me->find(location => 'work');

The CWUser::Identity::Collection object maintains a set user related objects. It helps selecting these objects, which is partially common to all collections (for instance, each object has a name so you can search on names), and sometimes specific to the extension of this collection.

Currently imlemented extensions are

* people is a collection of users

* whereabouts are locations =item * a mailinglist is a

collection of email addresses =item * a network contains groups of systems =back

overload: @{} When the reference to a collection object is used as array-reference, it will be shown as list of roles. Example:

 my $locations = $ui->collection('location');
 foreach my $loc (@$location) ...
 print $location->[0];

 print "$collection\n";  #   location: home, work

User::Identity::Collection->new([NAME], OPTIONS)

 Option       Defined in       Default   
 description  L<User::Identity::Item>  undef     
 item_type                     <required>
 name         L<User::Identity::Item>  <required>
 parent       L<User::Identity::Item>  C<undef>  
 roles                         undef

$obj->description See Attributes in User::Identity::Item $obj->itemType Returns the type of the items collected. $obj->name([NEWNAME]) See Attributes in User::Identity::Item $obj->roles Returns all defined roles within this collection. Be warned: the rules are returned in random (hash) order.

$obj->add(COLLECTION, ROLE) See Collections in User::Identity::Item $obj->addCollection(OBJECT | ([TYPE], OPTIONS)) See Collections in User::Identity::Item $obj->collection(NAME) See Collections in User::Identity::Item $obj->parent([PARENT]) See Collections in User::Identity::Item $obj->removeCollection(OBJECT|NAME) See Collections in User::Identity::Item $obj->type User::Identity::Collection->type See Collections in User::Identity::Item $obj->user See Collections in User::Identity::Item

$obj->addRole(ROLE| ( [NAME],OPTIONS ) | ARRAY-OF-OPTIONS) Adds a new role to this collection. ROLE is an object of the right type (depends on the extension of this module which type that is) or a list of OPTIONS which are used to create such role. The options can also be passed as reference to an array. The added role is returned. Example:

 my $uicl = User::Identity::Collection::Locations->new;

 my $uil  = User::Identity::Location->new(home => ...);
 $uicl->addRole($uil);

 $uicl->addRole( home => address => 'street 32' );
 $uicl->addRole( [home => address => 'street 32'] );

 $ui      = User::Identity;
 $ui->add(location => 'home', address => 'street 32' );
 $ui->add(location => [ 'home', address => 'street 32' ] );

$obj->find(NAME|CODE|undef) Find the object with the specified NAME in this collection. With CWundef, a randomly selected role is returned. When a code reference is specified, all collected roles are scanned one after the other (in unknown order). For each role,

 CODE->($object, $collection)

 my $emails = $ui->collection('emails');
 $emails->find('work');

 sub find_work($$) {
    my ($mail, $emails) = @_;
    $mail->location->name eq 'work';
 }
 my @at_work = $emails->find(\&find_work);
 my @at_work = $ui->find(location => \&find_work);
 my $any     = $ui->find(location => undef );

Error: CW$object is not a collection. The first argument is an object, but not of a class which extends User::Identity::Collection. Error: Cannot create a CW$type to add this to my collection. Some options are specified to create a CW$type object, which is native to this collection. However, for some reason this failed. Error: Cannot load collection module for CW$type ($class). Either the specified CW$type does not exist, or that module named CW$class returns compilation errors. If the type as specified in the warning is not the name of a package, you specified a nickname which was not defined. Maybe you forgot the 'require' the package which defines the nickname. Error: Cannot rename CW$name into CW$newname: already exists Error: Cannot rename CW$name into CW$newname: doesn't exist Error: Creation of a collection via CW$class failed. The CW$class did compile, but it was not possible to create an object of that class using the options you specified. Error: Don't know what type of collection you want to add. If you add a collection, it must either by a collection object or a list of options which can be used to create a collection object. In the latter case, the type of collection must be specified. Warning: No collection CW$name The collection with CW$name does not exist and can not be created. Error: Wrong type of role for CW$collection: requires a CW$expect but got a CW$type Each CW$collection groups sets of roles of one specific type ($expect). You cannot add objects of a different CW$type.

See the User::Identity website at <http://perl.overmeer.net/userid/> for more details.

User::Identity version 0.90. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors. Copyright (c) 2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.