User::Identity::Collection(3pm)

1User::Identity::CollectUisoenr(3C)ontributed Perl DocumeUnsteart:i:oIndentity::Collection(3)
2
3
4

NAME

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

INHERITANCE

9        User::Identity::Collection
10          is a User::Identity::Item
11
12        User::Identity::Collection is extended by
13          User::Identity::Collection::Emails
14          User::Identity::Collection::Locations
15          User::Identity::Collection::Systems
16          User::Identity::Collection::Users
17

SYNOPSIS

19        use User::Identity;
20        use User::Identity::Collection;
21        my $me    = User::Identity->new(...);
22        my $set   = User::Identity::Collection::Emails->new(...);
23        $me->addCollection($set);
24
25        # Simpler
26        use User::Identity;
27        my $me    = User::Identity->new(...);
28        my $set   = $me->addCollection(type => 'email', ...)
29        my $set   = $me->addCollection('email', ...)
30
31        my @roles = $me->collection('email');  # list of collected items
32
33        my $coll  = $me->collection('email');  # a User::Identity::Collection
34        my @roles = $coll->roles;
35        my @roles = @$coll;                    # same, by overloading
36
37        my $role  = $me->collection('email')->find($coderef);
38        my $role  = $me->collection('location')->find('work');
39        my $role  = $me->find(location => 'work');
40

DESCRIPTION

42       The "User::Identity::Collection" object maintains a set user related
43       objects.  It helps selecting these objects, which is partially common
44       to all collections (for instance, each object has a name so you can
45       search on names), and sometimes specific to the extension of this
46       collection.
47
48       Currently imlemented extensions are
49
50       ·   people is a collection of users
51
52       ·   whereabouts are locations
53
54       ·   a mailinglist is a
55
56           collection of email addresses
57
58       ·   a network contains
59
60           groups of systems
61

OVERLOADED

63       overload: @{}
64
65           When the reference to a collection object is used as array-
66           reference, it will be shown as list of roles.
67
68           example:
69
70            my $locations = $ui->collection('location');
71            foreach my $loc (@$location) ...
72            print $location->[0];
73
74       overload: stringification
75
76           Returns the name of the collection and a sorted list of defined
77           items.
78
79           example:
80
81            print "$collection\n";  #   location: home, work
82

METHODS

84   Constructors
85       User::Identity::Collection->new([NAME], OPTIONS)
86
87        Option     --Defined in     --Default
88        description  User::Identity::Item  undef
89        item_type                     <required>
90        name         User::Identity::Item  <required>
91        parent       User::Identity::Item  undef
92        roles                         undef
93
94           . description => STRING
95
96           . item_type => CLASS
97
98               The CLASS which is used to store the information for each of
99               the maintained objects within this collection.
100
101           . name => STRING
102
103           . parent => OBJECT
104
105           . roles => ROLE|ARRAY
106
107               Immediately add some roles to this collection.  In case of an
108               ARRAY, each element of the array is passed separately to
109               addRole(). So, you may end-up with an ARRAY of arrays each
110               grouping a set of options to create a role.
111
112   Attributes
113       $obj->description
114
115           See "Attributes" in User::Identity::Item
116
117       $obj->itemType
118
119           Returns the type of the items collected.
120
121       $obj->name([NEWNAME])
122
123           See "Attributes" in User::Identity::Item
124
125       $obj->roles
126
127           Returns all defined roles within this collection.  Be warned: the
128           rules are returned in random (hash) order.
129
130   Collections
131       $obj->add(COLLECTION, ROLE)
132
133           See "Collections" in User::Identity::Item
134
135       $obj->addCollection(OBJECT | ([TYPE], OPTIONS))
136
137           See "Collections" in User::Identity::Item
138
139       $obj->collection(NAME)
140
141           See "Collections" in User::Identity::Item
142
143       $obj->parent([PARENT])
144
145           See "Collections" in User::Identity::Item
146
147       $obj->removeCollection(OBJECT|NAME)
148
149           See "Collections" in User::Identity::Item
150
151       $obj->type
152
153       User::Identity::Collection->type
154
155           See "Collections" in User::Identity::Item
156
157       $obj->user
158
159           See "Collections" in User::Identity::Item
160
161   Maintaining roles
162       $obj->addRole(ROLE| ( [NAME],OPTIONS ) | ARRAY-OF-OPTIONS)
163
164           Adds a new role to this collection.  ROLE is an object of the right
165           type (depends on the extension of this module which type that is)
166           or a list of OPTIONS which are used to create such role.  The
167           options can also be passed as reference to an array.  The added
168           role is returned.
169
170           example:
171
172            my $uicl = User::Identity::Collection::Locations->new;
173
174            my $uil  = User::Identity::Location->new(home => ...);
175            $uicl->addRole($uil);
176
177            $uicl->addRole( home => address => 'street 32' );
178            $uicl->addRole( [home => address => 'street 32'] );
179
180           Easier
181
182            $ui      = User::Identity;
183            $ui->add(location => 'home', address => 'street 32' );
184            $ui->add(location => [ 'home', address => 'street 32' ] );
185
186       $obj->removeRole(ROLE|NAME)
187
188           The deleted role is returned (if it existed).
189
190       $obj->renameRole(ROLE|OLDNAME, NEWNAME)
191
192           Give the role a different name, and move it in the collection.
193
194       $obj->sorted
195
196           Returns the roles sorted by name, alphabetically and case-
197           sensitive.
198
199   Searching
200       $obj->find(NAME|CODE|undef)
201
202           Find the object with the specified NAME in this collection.  With
203           "undef", a randomly selected role is returned.
204
205           When a code reference is specified, all collected roles are scanned
206           one after the other (in unknown order).  For each role,
207
208            CODE->($object, $collection)
209
210           is called.  When the CODE returns true, the role is selected.  In
211           list context, all selected roles are returned.  In scalar context,
212           the first match is returned and the scan is aborted immediately.
213
214           example:
215
216            my $emails = $ui->collection('emails');
217            $emails->find('work');
218
219            sub find_work($$) {
220               my ($mail, $emails) = @_;
221               $mail->location->name eq 'work';
222            }
223            my @at_work = $emails->find(\&find_work);
224            my @at_work = $ui->find(location => \&find_work);
225            my $any     = $ui->find(location => undef );
226

DIAGNOSTICS

228       Error: $object is not a collection.
229
230           The first argument is an object, but not of a class which extends
231           User::Identity::Collection.
232
233       Error: Cannot create a $type to add this to my collection.
234
235           Some options are specified to create a $type object, which is
236           native to this collection.  However, for some reason this failed.
237
238       Error: Cannot load collection module for $type ($class).
239
240           Either the specified $type does not exist, or that module named
241           $class returns compilation errors.  If the type as specified in the
242           warning is not the name of a package, you specified a nickname
243           which was not defined.  Maybe you forgot the 'require' the package
244           which defines the nickname.
245
246       Error: Cannot rename $name into $newname: already exists
247
248       Error: Cannot rename $name into $newname: doesn't exist
249
250       Error: Creation of a collection via $class failed.
251
252           The $class did compile, but it was not possible to create an object
253           of that class using the options you specified.
254
255       Error: Don't know what type of collection you want to add.
256
257           If you add a collection, it must either by a collection object or a
258           list of options which can be used to create a collection object.
259           In the latter case, the type of collection must be specified.
260
261       Warning: No collection $name
262
263           The collection with $name does not exist and can not be created.
264
265       Error: Wrong type of role for $collection: requires a $expect but got a
266       $type
267
268           Each $collection groups sets of roles of one specific type
269           ($expect).  You cannot add objects of a different $type.
270

LICENSE

276       Copyrights 2003,2004,2007-2009 by Mark Overmeer <perl@overmeer.net>.
277       For other contributors see Changes.
278
279       This program is free software; you can redistribute it and/or modify it
280       under the same terms as Perl itself.  See
281       http://www.perl.com/perl/misc/Artistic.html
282
283
284
285perl v5.12.1                      2009-12-24     User::Identity::Collection(3)