1User::Identity::CollectUisoenr(3C)ontributed Perl DocumeUnsteart:i:oIndentity::Collection(3)
2
6 User::Identity::Collection - base class for collecting roles of a user
7
9 User::Identity::Collection
10 is an User::Identity::Item
11 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
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 # 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 my @roles = $me->collection('email'); # list of collected items
32 my $coll = $me->collection('email'); # a User::Identity::Collection
34 my @roles = $coll->roles;
35 my @roles = @$coll; # same, by overloading
36 my $role = $me->collection('email')->find($coderef);
38 my $role = $me->collection('location')->find('work');
39 my $role = $me->find(location => 'work');
40
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 Currently imlemented extensions are
49 · people is a collection of users
51 · whereabouts are locations
53 · a mailinglist is a
55 collection of email addresses
57 · a network contains
59 groups of systems
61 Extends "DESCRIPTION" in User::Identity::Item.
63
65 overload: @{}
66 When the reference to a collection object is used as array-
67 reference, it will be shown as list of roles.
68 example:
70 my $locations = $ui->collection('location');
72 foreach my $loc (@$location) ...
73 print $location->[0];
74 overload: stringification
76 Returns the name of the collection and a sorted list of defined
77 items.
78 example:
80 print "$collection\n"; # location: home, work
82
84 Extends "METHODS" in User::Identity::Item.
85 Constructors
87 Extends "Constructors" in User::Identity::Item.
88 User::Identity::Collection->new( [$name], %options )
90 -Option --Defined in --Default
91 description User::Identity::Item undef
92 item_type <required>
93 name User::Identity::Item <required>
94 parent User::Identity::Item undef
95 roles undef
96 description => STRING
98 item_type => CLASS
99 The CLASS which is used to store the information for each of the
100 maintained objects within this collection.
101 name => STRING
103 parent => OBJECT
104 roles => ROLE|ARRAY
105 Immediately add some roles to this collection. In case of an
106 ARRAY, each element of the array is passed separately to
107 addRole(). So, you may end-up with an ARRAY of arrays each
108 grouping a set of options to create a role.
109 Attributes
111 Extends "Attributes" in User::Identity::Item.
112 $obj->description()
114 Inherited, see "Attributes" in User::Identity::Item
115 $obj->itemType()
117 Returns the type of the items collected.
118 $obj->name( [$newname] )
120 Inherited, see "Attributes" in User::Identity::Item
121 $obj->roles()
123 Returns all defined roles within this collection. Be warned: the
124 rules are returned in random (hash) order.
125 Collections
127 Extends "Collections" in User::Identity::Item.
128 $obj->add($collection, $role)
130 Inherited, see "Collections" in User::Identity::Item
131 $obj->addCollection( $object | <[$type], %options> )
133 Inherited, see "Collections" in User::Identity::Item
134 $obj->collection($name)
136 Inherited, see "Collections" in User::Identity::Item
137 $obj->parent( [$parent] )
139 Inherited, see "Collections" in User::Identity::Item
140 $obj->removeCollection($object|$name)
142 Inherited, see "Collections" in User::Identity::Item
143 $obj->type()
145 User::Identity::Collection->type()
146 Inherited, see "Collections" in User::Identity::Item
147 $obj->user()
149 Inherited, see "Collections" in User::Identity::Item
150 Maintaining roles
152 $obj->addRole($role| <[$name],%options> | ARRAY)
153 Adds a new role to this collection. $role is an object of the
154 right type (depends on the extension of this module which type that
155 is) or a list of %options which are used to create such role. The
156 options can also be passed as reference to an ARRAY. The added
157 role is returned.
158 example:
160 my $uicl = User::Identity::Collection::Locations->new;
162 my $uil = User::Identity::Location->new(home => ...);
164 $uicl->addRole($uil);
165 $uicl->addRole( home => address => 'street 32' );
167 $uicl->addRole( [home => address => 'street 32'] );
168 Easier
170 $ui = User::Identity;
172 $ui->add(location => 'home', address => 'street 32' );
173 $ui->add(location => [ 'home', address => 'street 32' ] );
174 $obj->removeRole($role|$name)
176 The deleted role is returned (if it existed).
177 $obj->renameRole( <$role|$oldname>, $newname )
179 Give the role a different name, and move it in the collection.
180 $obj->sorted()
182 Returns the roles sorted by name, alphabetically and case-
183 sensitive.
184 Searching
186 Extends "Searching" in User::Identity::Item.
187 $obj->find($name|CODE|undef)
189 Find the object with the specified $name in this collection. With
190 "undef", a randomly selected role is returned.
191 When a code reference is specified, all collected roles are scanned
193 one after the other (in unknown order). For each role,
194 CODE->($object, $collection)
196 is called. When the CODE returns true, the role is selected. In
198 list context, all selected roles are returned. In scalar context,
199 the first match is returned and the scan is aborted immediately.
200 example:
202 my $emails = $ui->collection('emails');
204 $emails->find('work');
205 sub find_work($$) {
207 my ($mail, $emails) = @_;
208 $mail->location->name eq 'work';
209 }
210 my @at_work = $emails->find(\&find_work);
211 my @at_work = $ui->find(location => \&find_work);
212 my $any = $ui->find(location => undef );
213
215 Error: $object is not a collection.
216 The first argument is an object, but not of a class which extends
217 User::Identity::Collection.
218 Error: Cannot create a $type to add this to my collection.
220 Some options are specified to create a $type object, which is
221 native to this collection. However, for some reason this failed.
222 Error: Cannot load collection module for $type ($class).
224 Either the specified $type does not exist, or that module named
225 $class returns compilation errors. If the type as specified in the
226 warning is not the name of a package, you specified a nickname
227 which was not defined. Maybe you forgot the 'require' the package
228 which defines the nickname.
229 Error: Cannot rename $name into $newname: already exists
231 Error: Cannot rename $name into $newname: doesn't exist
232 Error: Creation of a collection via $class failed.
233 The $class did compile, but it was not possible to create an object
234 of that class using the options you specified.
235 Error: Don't know what type of collection you want to add.
237 If you add a collection, it must either by a collection object or a
238 list of options which can be used to create a collection object.
239 In the latter case, the type of collection must be specified.
240 Warning: No collection $name
242 The collection with $name does not exist and can not be created.
243 Error: Wrong type of role for $collection: requires a $expect but got a
245 $type
246 Each $collection groups sets of roles of one specific type
247 ($expect). You cannot add objects of a different $type.
248
250 This module is part of User-Identity distribution version 0.99, built
251 on January 24, 2018. Website: http://perl.overmeer.net/CPAN/
252
254 Copyrights 2003-2018 by [Mark Overmeer]. For other contributors see
255 ChangeLog.
256 This program is free software; you can redistribute it and/or modify it
258 under the same terms as Perl itself. See http://dev.perl.org/licenses/
259perl v5.32.0 2020-07-28 User::Identity::Collection(3)