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
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
62       Extends "DESCRIPTION" in User::Identity::Item.
63

OVERLOADED

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
69           example:
70
71            my $locations = $ui->collection('location');
72            foreach my $loc (@$location) ...
73            print $location->[0];
74
75       overload: stringification
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       Extends "METHODS" in User::Identity::Item.
85
86   Constructors
87       Extends "Constructors" in User::Identity::Item.
88
89       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
97           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
102           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
110   Attributes
111       Extends "Attributes" in User::Identity::Item.
112
113       $obj->description()
114           Inherited, see "Attributes" in User::Identity::Item
115
116       $obj->itemType()
117           Returns the type of the items collected.
118
119       $obj->name( [$newname] )
120           Inherited, see "Attributes" in User::Identity::Item
121
122       $obj->roles()
123           Returns all defined roles within this collection.  Be warned: the
124           rules are returned in random (hash) order.
125
126   Collections
127       Extends "Collections" in User::Identity::Item.
128
129       $obj->add($collection, $role)
130           Inherited, see "Collections" in User::Identity::Item
131
132       $obj->addCollection( $object | <[$type], %options> )
133           Inherited, see "Collections" in User::Identity::Item
134
135       $obj->collection($name)
136           Inherited, see "Collections" in User::Identity::Item
137
138       $obj->parent( [$parent] )
139           Inherited, see "Collections" in User::Identity::Item
140
141       $obj->removeCollection($object|$name)
142           Inherited, see "Collections" in User::Identity::Item
143
144       $obj->type()
145       User::Identity::Collection->type()
146           Inherited, see "Collections" in User::Identity::Item
147
148       $obj->user()
149           Inherited, see "Collections" in User::Identity::Item
150
151   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
159           example:
160
161            my $uicl = User::Identity::Collection::Locations->new;
162
163            my $uil  = User::Identity::Location->new(home => ...);
164            $uicl->addRole($uil);
165
166            $uicl->addRole( home => address => 'street 32' );
167            $uicl->addRole( [home => address => 'street 32'] );
168
169           Easier
170
171            $ui      = User::Identity;
172            $ui->add(location => 'home', address => 'street 32' );
173            $ui->add(location => [ 'home', address => 'street 32' ] );
174
175       $obj->removeRole($role|$name)
176           The deleted role is returned (if it existed).
177
178       $obj->renameRole( <$role|$oldname>, $newname )
179           Give the role a different name, and move it in the collection.
180
181       $obj->sorted()
182           Returns the roles sorted by name, alphabetically and case-
183           sensitive.
184
185   Searching
186       Extends "Searching" in User::Identity::Item.
187
188       $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
192           When a code reference is specified, all collected roles are scanned
193           one after the other (in unknown order).  For each role,
194
195            CODE->($object, $collection)
196
197           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
201           example:
202
203            my $emails = $ui->collection('emails');
204            $emails->find('work');
205
206            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

DIAGNOSTICS

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
219       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
223       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
230       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
236       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
241       Warning: No collection $name
242           The collection with $name does not exist and can not be created.
243
244       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

SEE ALSO

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

LICENSE

254       Copyrights 2003-2018 by [Mark Overmeer]. For other contributors see
255       ChangeLog.
256
257       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/
259
260
261
262perl v5.30.1                      2020-01-30     User::Identity::Collection(3)
Impressum