1User::Identity(3) User Contributed Perl Documentation User::Identity(3)
2
6 User::Identity - maintain info about a physical person
7
9 User::Identity
10 is a User::Identity::Item
11
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
23 The "User-Identity" distribution 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 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 If you need more kinds of user information, then please contact the
36 module author.
37 Extends "DESCRIPTION" in User::Identity::Item.
39
41 $obj->stringification()
42 When an "User::Identity" is used as string, it is automatically
43 translated into the fullName() of the user involved.
44 example:
46 my $me = User::Identity->new(...)
48 print $me; # same as print $me->fullName
49 print "I am $me\n"; # also stringification
50
52 Extends "METHODS" in User::Identity::Item.
53 Constructors
55 Extends "Constructors" in User::Identity::Item.
56 User::Identity->new( [$name], %options )
58 Create a new user identity, which will contain all data related to
59 a single physical human being. Most user data can only be
60 specified at object construction, because they should never change.
61 A $name may be specified as first argument, but also as option, one
62 way or the other is required.
63 -Option --Defined in --Default
65 birth undef
66 charset $ENV{LC_CTYPE}
67 courtesy undef
68 description User::Identity::Item undef
69 firstname undef
70 formal_name undef
71 full_name undef
72 gender undef
73 initials undef
74 language 'en'
75 name User::Identity::Item <required>
76 nickname undef
77 parent User::Identity::Item undef
78 prefix undef
79 surname undef
80 titles undef
81 birth => DATE
83 charset => STRING
84 courtesy => STRING
85 description => STRING
86 firstname => STRING
87 formal_name => STRING
88 full_name => STRING
89 gender => STRING
90 initials => STRING
91 language => STRING
92 name => STRING
93 nickname => STRING
94 parent => OBJECT
95 prefix => STRING
96 surname => STRING
97 titles => STRING
98 Attributes
100 Extends "Attributes" in User::Identity::Item.
101 $obj->age()
103 Calcuted from the datge of birth to the current moment, as integer.
104 On the birthday, the number is incremented already.
105 $obj->birth()
107 Returns the date in standardized format: YYYYMMDD, easy to sort and
108 select. This may return "undef", even if the dateOfBirth()
109 contains a value, simply because the format is not understood.
110 Month or day may contain '00' to indicate that those values are not
111 known.
112 $obj->charset()
114 The user's preferred character set, which defaults to the value of
115 LC_CTYPE environment variable.
116 $obj->courtesy()
118 The courtesy is used to address people in a very formal way.
119 Values are like "Mr.", "Mrs.", "Sir", "Frau", "Heer", "de heer",
120 "mevrouw". This often provides a way to find the gender of someone
121 addressed.
122 $obj->dateOfBirth()
124 Returns the date of birth, as specified during instantiation.
125 $obj->description()
127 Inherited, see "Attributes" in User::Identity::Item
128 $obj->firstname()
130 Returns the first name of the user. If it is not defined
131 explicitly, it is derived from the nickname, and than capitalized
132 if needed.
133 $obj->formalName()
135 Returns a formal name for the user. If not defined as
136 instantiation parameter (see new()), it is constructed from other
137 available information, which may result in an incorrect or an
138 incomplete name. The result is built from "courtesy initials
139 prefix surname title".
140 $obj->fullName()
142 If this is not specified as value during object construction, it is
143 guessed based on other known values like "firstname prefix
144 surname". If a surname is provided without firstname, the nickname
145 is taken as firstname. When a firstname is provided without
146 surname, the nickname is taken as surname. If both are not
147 provided, then the nickname is used as fullname.
148 $obj->gender()
150 Returns the specified gender of the person, as specified during
151 instantiation, which could be like 'Male', 'm', 'homme', 'man'.
152 There is no smart behavior on this: the exact specified value is
153 returned. Methods isMale(), isFemale(), and courtesy() are smart.
154 $obj->initials()
156 The initials, which may be derived from the first letters of the
157 firstname.
158 $obj->isFemale()
160 See isMale(): return true if we are sure the user is a woman.
161 $obj->isMale()
163 Returns true if we are sure that the user is male. This is
164 specified as gender at instantiation, or derived from the courtesy
165 value. Methods isMale and isFemale are not complementatory: they
166 can both return false for the same user, in which case the gender
167 is undertermined.
168 $obj->language()
170 Can contain a list or a single language name, as defined by the RFC
171 Examples are 'en', 'en-GB', 'nl-BE'. The default language is 'en'
172 (English).
173 $obj->name( [$newname] )
175 Inherited, see "Attributes" in User::Identity::Item
176 $obj->nickname()
178 Returns the user's nickname, which could be used as username,
179 e-mail alias, or such. When no nickname was explicitly specified,
180 the name is used.
181 $obj->prefix()
183 The words which are between the firstname (or initials) and the
184 surname.
185 $obj->surname()
187 Returns the surname of person, or "undef" if that is not known.
188 $obj->titles()
190 The titles, degrees in education or of other kind. If these are
191 complex, you may need to specify the formal name of the users as
192 well, because smart formatting probably failes.
193 Collections
195 Extends "Collections" in User::Identity::Item.
196 $obj->add($collection, $role)
198 Inherited, see "Collections" in User::Identity::Item
199 $obj->addCollection( $object | <[$type], %options> )
201 Inherited, see "Collections" in User::Identity::Item
202 $obj->collection($name)
204 Inherited, see "Collections" in User::Identity::Item
205 $obj->parent( [$parent] )
207 Inherited, see "Collections" in User::Identity::Item
208 $obj->removeCollection($object|$name)
210 Inherited, see "Collections" in User::Identity::Item
211 $obj->type()
213 User::Identity->type()
214 Inherited, see "Collections" in User::Identity::Item
215 $obj->user()
217 Inherited, see "Collections" in User::Identity::Item
218 Searching
220 Extends "Searching" in User::Identity::Item.
221 $obj->find($collection, $role)
223 Inherited, see "Searching" in User::Identity::Item
224
226 Error: $object is not a collection.
227 The first argument is an object, but not of a class which extends
228 User::Identity::Collection.
229 Error: Cannot load collection module for $type ($class).
231 Either the specified $type does not exist, or that module named
232 $class returns compilation errors. If the type as specified in the
233 warning is not the name of a package, you specified a nickname
234 which was not defined. Maybe you forgot the 'require' the package
235 which defines the nickname.
236 Error: Creation of a collection via $class failed.
238 The $class did compile, but it was not possible to create an object
239 of that class using the options you specified.
240 Error: Don't know what type of collection you want to add.
242 If you add a collection, it must either by a collection object or a
243 list of options which can be used to create a collection object.
244 In the latter case, the type of collection must be specified.
245 Warning: No collection $name
247 The collection with $name does not exist and can not be created.
248
250 This module is part of User-Identity distribution version 1.02, built
251 on April 17, 2023. Website: http://perl.overmeer.net/CPAN/
252
254 Copyrights 2003-2023 by [Mark Overmeer <markov@cpan.org>]. For other
255 contributors see ChangeLog.
256 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/
259perl v5.36.1 2023-04-30 User::Identity(3)