User::Identity::Item(3pm)

1User::Identity::Item(3)User Contributed Perl DocumentatioUnser::Identity::Item(3)
2
3
4

NAME

6       User::Identity::Item - general base class for User::Identity
7

INHERITANCE

9        User::Identity::Item is extended by
10          Mail::Identity
11          User::Identity
12          User::Identity::Archive
13          User::Identity::Collection
14          User::Identity::Location
15          User::Identity::System
16

SYNOPSIS

DESCRIPTION

19       The "User::Identity::Item" base class is extended into useful modules:
20       it has no use by its own.
21

METHODS

23   Constructors
24       User::Identity::Item->new( [$name], %options )
25            -Option     --Default
26             description  undef
27             name         <required>
28             parent       undef
29
30           description => STRING
31             Free format description on the collected item.
32
33           name => STRING
34             A simple name for this item.  Try to give a useful name in the
35             context of the item time.  Each time when you lookup items, you
36             need to specify this name, so it should be unique and not to hard
37             to handle in your program.  For instance, when a person is
38             addressed, you usually will give him/her this a nickname.
39
40           parent => OBJECT
41             The encapsulating object: the object which collects this one.
42
43   Attributes
44       $obj->description()
45           Free format description on this item.  Please do not add any
46           significance to the content of this field: if you are in need for
47           an extra attribute, please contact the author of the module to
48           implement it, or extend the object to suit your needs.
49
50       $obj->name( [$newname] )
51           The name of this item.  Names are unique within a collection... a
52           second object with the same name within any collection will destroy
53           the already existing object with that name.
54
55           Changing the name of an item is quite dangerous.  You probably want
56           to call User::Identity::Collection::renameRole() instead.
57
58   Collections
59       $obj->add($collection, $role)
60           The $role is added to the $collection.  The $collection is the name
61           of a collection, which will be created automatically with
62           addCollection() if needed.  The $collection can also be specified
63           as existing collection object.
64
65           The $role is anything what is acceptable to
66           User::Identity::Collection::addRole() of the collection at hand,
67           and is returned.  $role typically is a list of parameters for one
68           role, or a reference to an array containing these values.
69
70           example:
71
72            my $ui   = User::Identity->new(...);
73            my $home = $ui->add(location => [home => street => '27 Roadstreet', ...] );
74            my $work = $ui->add(location => work, tel => '+31-2231-342-13', ... );
75
76            my $travel = User::Identity::Location->new(travel => ...);
77            $ui->add(location => $travel);
78
79            my $system = User::Identity::Collection::System->new(...);
80            $ui->add($system => 'localhost');
81
82       $obj->addCollection( $object | <[$type], %options> )
83           Add a new collection of roles to an item.  This can be achieved in
84           two ways: either create an User::Identity::Collection $object
85           yourself and then pass that to this method, or supply all the
86           %options needed to create such an object and it will be created for
87           you.  The object which is added is returned, and can be used for
88           many methods directly.
89
90           For %options, see the specific type of collection.  Additional
91           options are listed below.
92
93            -Option--Default
94             type    <required>
95
96           type => STRING|CLASS
97             The nickname of a collection class or the CLASS name itself of
98             the object to be created.  Required if an object has to be
99             created.  Predefined type nicknames are "email", "system", and
100             "location".
101
102           example:
103
104            my $me   = User::Identity->new(...);
105            my $locs = User::Identity::Collection::Locations->new();
106            $me->addCollection($locs);
107
108            my $email = $me->addCollection(type => 'email');
109            my $email = $me->addCollection('email');
110
111       $obj->collection($name)
112           In scalar context the collection object with the $name is returned.
113           In list context, all the roles within the collection are returned.
114
115           example:
116
117            my @roles = $me->collection('email');        # list of collected items
118            my @roles = $me->collection('email')->roles; # same of collected items
119            my $coll  = $me->collection('email');        # a User::Identity::Collection
120
121       $obj->parent( [$parent] )
122           Returns the parent of an Item (the enclosing item).  This may
123           return "undef" if the object is stand-alone.
124
125       $obj->removeCollection($object|$name)
126       $obj->type()
127       User::Identity::Item->type()
128           Returns a nice symbolic name for the type.
129
130       $obj->user()
131           Go from this object to its parent, to its parent, and so on, until
132           a User::Identity is found or the top of the object tree has been
133           reached.
134
135           example:
136
137            print $email->user->fullName;
138
139   Searching
140       $obj->find($collection, $role)
141           Returns the object with the specified $role within the named
142           collection.  The collection can be specified as name or object.
143
144           example:
145
146            my $role  = $me->find(location => 'work');       # one location
147            my $role  = $me->collection('location')->find('work'); # same
148
149            my $email = $me->addCollection('email');
150            $me->find($email => 'work');
151            $email->find('work');   # same
152

DIAGNOSTICS

154       Error: $object is not a collection.
155           The first argument is an object, but not of a class which extends
156           User::Identity::Collection.
157
158       Error: Cannot load collection module for $type ($class).
159           Either the specified $type does not exist, or that module named
160           $class returns compilation errors.  If the type as specified in the
161           warning is not the name of a package, you specified a nickname
162           which was not defined.  Maybe you forgot the 'require' the package
163           which defines the nickname.
164
165       Error: Creation of a collection via $class failed.
166           The $class did compile, but it was not possible to create an object
167           of that class using the options you specified.
168
169       Error: Don't know what type of collection you want to add.
170           If you add a collection, it must either by a collection object or a
171           list of options which can be used to create a collection object.
172           In the latter case, the type of collection must be specified.
173
174       Error: Each item requires a name
175           You have to specify a name for each item.  These names need to be
176           unique within one collection, but feel free to give the same name
177           to an e-mail address and a location.
178
179       Warning: No collection $name
180           The collection with $name does not exist and can not be created.
181
182       Warning: Unknown option $name for a $class
183           One used option is not defined.  Check the manual page of the class
184           to see which options are accepted.
185
186       Warning: Unknown options @names for a $class
187           More than one option is not defined.
188

LICENSE

194       Copyrights 2003-2020 by [Mark Overmeer <markov@cpan.org>]. For other
195       contributors see ChangeLog.
196
197       This program is free software; you can redistribute it and/or modify it
198       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
199
200
201
202perl v5.32.1                      2021-01-27           User::Identity::Item(3)