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

DIAGNOSTICS

169       Error: $object is not a collection.
170
171           The first argument is an object, but not of a class which extends
172           User::Identity::Collection.
173
174       Error: Cannot load collection module for $type ($class).
175
176           Either the specified $type does not exist, or that module named
177           $class returns compilation errors.  If the type as specified in the
178           warning is not the name of a package, you specified a nickname
179           which was not defined.  Maybe you forgot the 'require' the package
180           which defines the nickname.
181
182       Error: Creation of a collection via $class failed.
183
184           The $class did compile, but it was not possible to create an object
185           of that class using the options you specified.
186
187       Error: Don't know what type of collection you want to add.
188
189           If you add a collection, it must either by a collection object or a
190           list of options which can be used to create a collection object.
191           In the latter case, the type of collection must be specified.
192
193       Error: Each item requires a name
194
195           You have to specify a name for each item.  These names need to be
196           unique within one collection, but feel free to give the same name
197           to an e-mail address and a location.
198
199       Warning: No collection $name
200
201           The collection with $name does not exist and can not be created.
202
203       Warning: Unknown option $name for a $class
204
205           One used option is not defined.  Check the manual page of the class
206           to see which options are accepted.
207
208       Warning: Unknown options @names for a $class
209
210           More than one option is not defined.
211

LICENSE

217       Copyrights 2003,2004,2007-2009 by Mark Overmeer <perl@overmeer.net>.
218       For other contributors see Changes.
219
220       This program is free software; you can redistribute it and/or modify it
221       under the same terms as Perl itself.  See
222       http://www.perl.com/perl/misc/Artistic.html
223
224
225
226perl v5.12.1                      2009-12-24           User::Identity::Item(3)