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

NAME

6       User::Identity - maintain 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" 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
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
38       Extends "DESCRIPTION" in User::Identity::Item.
39

OVERLOADED

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
45           example:
46
47            my $me = User::Identity->new(...)
48            print $me;          # same as  print $me->fullName
49            print "I am $me\n"; # also stringification
50

METHODS

52       Extends "METHODS" in User::Identity::Item.
53
54   Constructors
55       Extends "Constructors" in User::Identity::Item.
56
57       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
64            -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
82           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
99   Attributes
100       Extends "Attributes" in User::Identity::Item.
101
102       $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
106       $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
113       $obj->charset()
114           The user's preferred character set, which defaults to the value of
115           LC_CTYPE environment variable.
116
117       $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
123       $obj->dateOfBirth()
124           Returns the date of birth, as specified during instantiation.
125
126       $obj->description()
127           Inherited, see "Attributes" in User::Identity::Item
128
129       $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
134       $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
141       $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
149       $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
155       $obj->initials()
156           The initials, which may be derived from the first letters of the
157           firstname.
158
159       $obj->isFemale()
160           See isMale(): return true if we are sure the user is a woman.
161
162       $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
169       $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
174       $obj->name( [$newname] )
175           Inherited, see "Attributes" in User::Identity::Item
176
177       $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
182       $obj->prefix()
183           The words which are between the firstname (or initials) and the
184           surname.
185
186       $obj->surname()
187           Returns the surname of person, or "undef" if that is not known.
188
189       $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
194   Collections
195       Extends "Collections" in User::Identity::Item.
196
197       $obj->add($collection, $role)
198           Inherited, see "Collections" in User::Identity::Item
199
200       $obj->addCollection( $object | <[$type], %options> )
201           Inherited, see "Collections" in User::Identity::Item
202
203       $obj->collection($name)
204           Inherited, see "Collections" in User::Identity::Item
205
206       $obj->parent( [$parent] )
207           Inherited, see "Collections" in User::Identity::Item
208
209       $obj->removeCollection($object|$name)
210           Inherited, see "Collections" in User::Identity::Item
211
212       $obj->type()
213       User::Identity->type()
214           Inherited, see "Collections" in User::Identity::Item
215
216       $obj->user()
217           Inherited, see "Collections" in User::Identity::Item
218
219   Searching
220       Extends "Searching" in User::Identity::Item.
221
222       $obj->find($collection, $role)
223           Inherited, see "Searching" in User::Identity::Item
224

DIAGNOSTICS

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
230       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
237       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
241       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
246       Warning: No collection $name
247           The collection with $name does not exist and can not be created.
248

SEE ALSO

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

LICENSE

254       Copyrights 2003-2023 by [Mark Overmeer <markov@cpan.org>]. For other
255       contributors see ChangeLog.
256
257       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/
259
260
261
262perl v5.36.1                      2023-04-30                 User::Identity(3)
Impressum