User::Identity(3pm)

1User::Identity(3)     User Contributed Perl Documentation    User::Identity(3)
2
3
4

NAME

6       User::Identity - maintains info about a physical person
7

INHERITANCE

9        User::Identity
10          is a User::Identity::Item
11

SYNOPSIS

13        use User::Identity;
14        my $me = User::Identity->new
15         ( 'john'
16         , firstname => 'John'
17         , surname   => 'Doe'
18         );
19        print $me->fullName  # prints "John Doe"
20        print $me;           # same
21

DESCRIPTION

23       The "User::Identity" object is created to maintain a set of
24       informational objects which are related to one user.  The
25       "User::Identity" module tries to be smart providing defaults,
26       conversions and often required combinations.
27
28       The identities are not implementing any kind of storage, and can
29       therefore be created by any simple or complex Perl program.  This way,
30       it is more flexible than an XML file to store the data.  For instance,
31       you can decide to store the data with Data::Dumper, Storable, DBI,
32       AddressBook or whatever.  Extension to simplify this task are still to
33       be developed.
34
35       If you need more kinds of user information, then please contact the
36       module author.
37

OVERLOADED

39       $obj->stringification
40
41           When an "User::Identity" is used as string, it is automatically
42           translated into the fullName() of the user involved.
43
44           example:
45
46            my $me = User::Identity->new(...)
47            print $me;          # same as  print $me->fullName
48            print "I am $me\n"; # also stringification
49

METHODS

51   Constructors
52       User::Identity->new([NAME], OPTIONS)
53
54           Create a new user identity, which will contain all data related to
55           a single physical human being.  Most user data can only be
56           specified at object construction, because they should never change.
57           A NAME may be specified as first argument, but also as option, one
58           way or the other is required.
59
60            Option     --Defined in     --Default
61            birth                         undef
62            charset                       $ENV{LC_CTYPE}
63            courtesy                      undef
64            description  User::Identity::Item  undef
65            firstname                     undef
66            formal_name                   undef
67            full_name                     undef
68            gender                        undef
69            initials                      undef
70            language                      'en'
71            name         User::Identity::Item  <required>
72            nickname                      undef
73            parent       User::Identity::Item  undef
74            prefix                        undef
75            surname                       undef
76            titles                        undef
77
78           . birth => DATE
79
80           . charset => STRING
81
82           . courtesy => STRING
83
84           . description => STRING
85
86           . firstname => STRING
87
88           . formal_name => STRING
89
90           . full_name => STRING
91
92           . gender => STRING
93
94           . initials => STRING
95
96           . language => STRING
97
98           . name => STRING
99
100           . nickname => STRING
101
102           . parent => OBJECT
103
104           . prefix => STRING
105
106           . surname => STRING
107
108           . titles => STRING
109
110   Attributes
111       $obj->age
112
113           Calcuted from the datge of birth to the current moment, as integer.
114           On the birthday, the number is incremented already.
115
116       $obj->birth
117
118           Returns the date in standardized format: YYYYMMDD, easy to sort and
119           select.  This may return "undef", even if the dateOfBirth()
120           contains a value, simply because the format is not understood.
121           Month or day may contain '00' to indicate that those values are not
122           known.
123
124       $obj->charset
125
126           The user's prefered character set, which defaults to the value of
127           LC_CTYPE environment variable.
128
129       $obj->courtesy
130
131           The courtesy is used to address people in a very formal way.
132           Values are like "Mr.", "Mrs.", "Sir", "Frau", "Heer", "de heer",
133           "mevrouw".  This often provides a way to find the gender of someone
134           addressed.
135
136       $obj->dateOfBirth
137
138           Returns the date of birth, as specified during instantiation.
139
140       $obj->description
141
142           See "Attributes" in User::Identity::Item
143
144       $obj->firstname
145
146           Returns the first name of the user.  If it is not defined
147           explicitly, it is derived from the nickname, and than capitalized
148           if needed.
149
150       $obj->formalName
151
152           Returns a formal name for the user.  If not defined as
153           instantiation parameter (see new()), it is constructed from other
154           available information, which may result in an incorrect or an
155           incomplete name.  The result is built from "courtesy initials
156           prefix surname title".
157
158       $obj->fullName
159
160           If this is not specified as value during object construction, it is
161           guessed based on other known values like "firstname prefix
162           surname".  If a surname is provided without firstname, the nickname
163           is taken as firstname.  When a firstname is provided without
164           surname, the nickname is taken as surname.  If both are not
165           provided, then the nickname is used as fullname.
166
167       $obj->gender
168
169           Returns the specified gender of the person, as specified during
170           instantiation, which could be like 'Male', 'm', 'homme', 'man'.
171           There is no smart behavior on this: the exact specified value is
172           returned. Methods isMale(), isFemale(), and courtesy() are smart.
173
174       $obj->initials
175
176           The initials, which may be derived from the first letters of the
177           firstname.
178
179       $obj->isFemale
180
181           See isMale(): return true if we are sure the user is a woman.
182
183       $obj->isMale
184
185           Returns true if we are sure that the user is male.  This is
186           specified as gender at instantiation, or derived from the courtesy
187           value.  Methods isMale and isFemale are not complementatory: they
188           can both return false for the same user, in which case the gender
189           is undertermined.
190
191       $obj->language
192
193           Can contain a list or a single language name, as defined by the RFC
194           Examples are 'en', 'en-GB', 'nl-BE'.  The default language  is 'en'
195           (English).
196
197       $obj->name([NEWNAME])
198
199           See "Attributes" in User::Identity::Item
200
201       $obj->nickname
202
203           Returns the user's nickname, which could be used as username,
204           e-mail alias, or such.  When no nickname was explicitly specified,
205           the name is used.
206
207       $obj->prefix
208
209           The words which are between the firstname (or initials) and the
210           surname.
211
212       $obj->surname
213
214           Returns the surname of person, or "undef" if that is not known.
215
216       $obj->titles
217
218           The titles, degrees in education or of other kind.  If these are
219           complex, you may need to specify the formal name of the users as
220           well, because smart formatting probably failes.
221
222   Collections
223       $obj->add(COLLECTION, ROLE)
224
225           See "Collections" in User::Identity::Item
226
227       $obj->addCollection(OBJECT | ([TYPE], OPTIONS))
228
229           See "Collections" in User::Identity::Item
230
231       $obj->collection(NAME)
232
233           See "Collections" in User::Identity::Item
234
235       $obj->find(COLLECTION, ROLE)
236
237           See "Collections" in User::Identity::Item
238
239       $obj->parent([PARENT])
240
241           See "Collections" in User::Identity::Item
242
243       $obj->removeCollection(OBJECT|NAME)
244
245           See "Collections" in User::Identity::Item
246
247       $obj->type
248
249       User::Identity->type
250
251           See "Collections" in User::Identity::Item
252
253       $obj->user
254
255           See "Collections" in User::Identity::Item
256

DIAGNOSTICS

258       Error: $object is not a collection.
259
260           The first argument is an object, but not of a class which extends
261           User::Identity::Collection.
262
263       Error: Cannot load collection module for $type ($class).
264
265           Either the specified $type does not exist, or that module named
266           $class returns compilation errors.  If the type as specified in the
267           warning is not the name of a package, you specified a nickname
268           which was not defined.  Maybe you forgot the 'require' the package
269           which defines the nickname.
270
271       Error: Creation of a collection via $class failed.
272
273           The $class did compile, but it was not possible to create an object
274           of that class using the options you specified.
275
276       Error: Don't know what type of collection you want to add.
277
278           If you add a collection, it must either by a collection object or a
279           list of options which can be used to create a collection object.
280           In the latter case, the type of collection must be specified.
281
282       Warning: No collection $name
283
284           The collection with $name does not exist and can not be created.
285

LICENSE

291       Copyrights 2003,2004,2007-2009 by Mark Overmeer <perl@overmeer.net>.
292       For other contributors see Changes.
293
294       This program is free software; you can redistribute it and/or modify it
295       under the same terms as Perl itself.  See
296       http://www.perl.com/perl/misc/Artistic.html
297
298
299
300perl v5.12.1                      2009-12-24                 User::Identity(3)