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 an 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 col‐
46       lection.
47
48       Currently imlemented extensions are
49
50       * people is a collection of users
51       * whereabouts are locations
52       * a mailinglist is a
53           collection of email addresses
54
55       * a network contains
56           groups of systems
57

OVERLOADED

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

METHODS

80       Constructors
81
82       User::Identity::Collection->new([NAME], OPTIONS)
83
84        Option     --Defined in     --Default
85        description  User::Identity::Item  undef
86        item_type                     <required>
87        name         User::Identity::Item  <required>
88        parent       User::Identity::Item  undef
89        roles                         undef
90
91           . description STRING
92
93           . item_type CLASS
94
95               The CLASS which is used to store the information for each of
96               the maintained objects within this collection.
97
98           . name STRING
99
100           . parent OBJECT
101
102           . roles ROLE⎪ARRAY
103
104               Immediately add some roles to this collection.  In case of an
105               ARRAY, each element of the array is passed separately to add‐
106               Role(). So, you may end-up with an ARRAY of arrays each group‐
107               ing a set of options to create a role.
108
109       Attributes
110
111       $obj->description
112
113           See "Attributes" in User::Identity::Item
114
115       $obj->itemType
116
117           Returns the type of the items collected.
118
119       $obj->name([NEWNAME])
120
121           See "Attributes" in User::Identity::Item
122
123       $obj->roles
124
125           Returns all defined roles within this collection.  Be warned: the
126           rules are returned in random (hash) order.
127
128       Collections
129
130       $obj->add(COLLECTION, ROLE)
131
132           See "Collections" in User::Identity::Item
133
134       $obj->addCollection(OBJECT ⎪ ([TYPE], OPTIONS))
135
136           See "Collections" in User::Identity::Item
137
138       $obj->collection(NAME)
139
140           See "Collections" in User::Identity::Item
141
142       $obj->parent([PARENT])
143
144           See "Collections" in User::Identity::Item
145
146       $obj->removeCollection(OBJECT⎪NAME)
147
148           See "Collections" in User::Identity::Item
149
150       $obj->type
151
152       User::Identity::Collection->type
153
154           See "Collections" in User::Identity::Item
155
156       $obj->user
157
158           See "Collections" in User::Identity::Item
159
160       Maintaining roles
161
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-sensi‐
197           tive.
198
199       Searching
200
201       $obj->find(NAME⎪CODE⎪undef)
202
203           Find the object with the specified NAME in this collection.  With
204           "undef", a randomly selected role is returned.
205
206           When a code reference is specified, all collected roles are scanned
207           one after the other (in unknown order).  For each role,
208
209            CODE->($object, $collection)
210
211           is called.  When the CODE returns true, the role is selected.  In
212           list context, all selected roles are returned.  In scalar context,
213           the first match is returned and the scan is aborted immediately.
214
215           Example:
216
217            my $emails = $ui->collection('emails');
218            $emails->find('work');
219
220            sub find_work($$) {
221               my ($mail, $emails) = @_;
222               $mail->location->name eq 'work';
223            }
224            my @at_work = $emails->find(\&find_work);
225            my @at_work = $ui->find(location => \&find_work);
226            my $any     = $ui->find(location => undef );
227

DIAGNOSTICS

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

LICENSE

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