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

DIAGNOSTICS

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

LICENSE

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