User::Identity(3) User Contributed Perl Documentation User::Identity(3)
NAME
User::Identity - maintain info about a physical person
INHERITANCE
User::Identity
is a User::Identity::Item
SYNOPSIS
use User::Identity;
my $me = User::Identity->new(
'john',
firstname => 'John',
surname => 'Doe'
);
print $me->fullName # prints "John Doe"
print $me; # same
DESCRIPTION
The "User-Identity" distribution is created to maintain a set of
informational objects which are related to one user. The
"User::Identity" module tries to be smart providing defaults,
conversions and often required combinations.
Be aware: This module versions 4.0 and up is not fully compatible with
older releases: mainly the exception handling has changed. When you
need to upgrade, please read the wiki
. Version 3 is still
maintained and may see new releases as well.
The identities are not implementing any kind of storage, and can
therefore be created by any simple or complex Perl program. This way,
it is more flexible than an XML file to store the data. For instance,
you can decide to store the data with Data::Dumper, Storable, DBI,
AddressBook or whatever. Extension to simplify this task are still to
be developed.
If you need more kinds of user information, then please contact the
module author.
Extends "DESCRIPTION" in User::Identity::Item.
OVERLOADED
overload: "" stringification
When an "User::Identity" is used as string, it is automatically
translated into the fullName() of the user involved.
>> example:
my $me = User::Identity->new(...)
print $me; # same as print $me->fullName
print "I am $me\n"; # also stringification
METHODS
Extends "METHODS" in User::Identity::Item.
Constructors
Extends "Constructors" in User::Identity::Item.
$class->new( [$name], %options )
Create a new user identity, which will contain all data related to
a single physical human being. Most user data can only be
specified at object construction, because they should never change.
A $name may be specified as first argument, but also as option, one
way or the other is required.
-Option --Defined in --Default
birth undef
charset $ENV{LC_CTYPE}
courtesy undef
description User::Identity::Item undef
firstname undef
formal_name undef
full_name undef
gender undef
initials undef
language 'en'
name User::Identity::Item
nickname undef
parent User::Identity::Item undef
prefix undef
surname undef
titles undef
birth => DATE
charset => STRING
courtesy => STRING
description => STRING
firstname => STRING
formal_name => STRING
full_name => STRING
gender => STRING
initials => STRING
language => STRING
name => STRING
nickname => STRING
parent => OBJECT
prefix => STRING
surname => STRING
titles => STRING
Attributes
Extends "Attributes" in User::Identity::Item.
$obj->age()
Calcuted from the datge of birth to the current moment, as integer.
On the birthday, the number is incremented already.
$obj->birth()
Returns the date in standardized format: YYYYMMDD, easy to sort and
select. This may return "undef", even if the dateOfBirth()
contains a value, simply because the format is not understood.
Month or day may contain '00' to indicate that those values are not
known.
$obj->charset()
The user's preferred character set, which defaults to the value of
LC_CTYPE environment variable.
$obj->courtesy()
The courtesy is used to address people in a very formal way.
Values are like "Mr.", "Mrs.", "Sir", "Frau", "Heer", "de heer",
"mevrouw". This often provides a way to find the gender of someone
addressed.
$obj->dateOfBirth()
Returns the date of birth, as specified during instantiation.
$obj->description()
Inherited, see "Attributes" in User::Identity::Item
$obj->firstname()
Returns the first name of the user. If it is not defined
explicitly, it is derived from the nickname, and than capitalized
if needed.
$obj->formalName()
Returns a formal name for the user. If not defined as
instantiation parameter (see new()), it is constructed from other
available information, which may result in an incorrect or an
incomplete name. The result is built from "courtesy initials
prefix surname title".
$obj->fullName()
If this is not specified as value during object construction, it is
guessed based on other known values like "firstname prefix
surname". If a surname is provided without firstname, the nickname
is taken as firstname. When a firstname is provided without
surname, the nickname is taken as surname. If both are not
provided, then the nickname is used as fullname.
$obj->gender()
Returns the specified gender of the person, as specified during
instantiation, which could be like 'Male', 'm', 'homme', 'man'.
There is no smart behavior on this: the exact specified value is
returned. Methods isMale(), isFemale(), and courtesy() are smart.
$obj->initials()
The initials, which may be derived from the first letters of the
firstname.
$obj->isFemale()
See isMale(): return "true" if we are sure the user is a woman.
$obj->isMale()
Returns "true" if we are sure that the user is male. This is
specified as gender at instantiation, or derived from the courtesy
value. Methods isMale and isFemale are not complementatory: they
can both return "false" for the same user, in which case the gender
is undertermined.
$obj->language()
Can contain a list or a single language name, as defined by the RFC
Examples are 'en', 'en-GB', 'nl-BE'. The default language is 'en'
(English).
$obj->name( [$newname] )
Inherited, see "Attributes" in User::Identity::Item
$obj->nickname()
Returns the user's nickname, which could be used as username,
e-mail alias, or such. When no nickname was explicitly specified,
the name is used.
$obj->prefix()
The words which are between the firstname (or initials) and the
surname.
$obj->surname()
Returns the surname of person, or "undef" if that is not known.
$obj->titles()
The titles, degrees in education or of other kind. If these are
complex, you may need to specify the formal name of the users as
well, because smart formatting probably failes.
Collections
Extends "Collections" in User::Identity::Item.
$obj->add($collection, $role)
Inherited, see "Collections" in User::Identity::Item
$obj->addCollection( $object | <[$type], %options> )
Inherited, see "Collections" in User::Identity::Item
$obj->collection($name)
Inherited, see "Collections" in User::Identity::Item
$obj->parent( [$parent] )
Inherited, see "Collections" in User::Identity::Item
$obj->removeCollection($object|$name)
Inherited, see "Collections" in User::Identity::Item
$any->type()
Inherited, see "Collections" in User::Identity::Item
$obj->user()
Inherited, see "Collections" in User::Identity::Item
Searching
Extends "Searching" in User::Identity::Item.
$obj->find($collection, $role)
Inherited, see "Searching" in User::Identity::Item
DIAGNOSTICS
Error: cannot load collection module for $type ($class): $@
Either the specified $type does not exist, or that module named
$class returns compilation errors. If the type as specified in the
warning is not the name of a package, you specified a nickname
which was not defined. Maybe you forgot the 'require' the package
which defines the nickname. Cast by addCollection()
Error: nvalid collection $name.
The collection with $name does not exist and can not be created.
Cast by add()
Error: this $object is not a collection.
Cast by addCollection()
SEE ALSO
This module is part of User-Identity version 4.00, built on December
12, 2025. Website: http://perl.overmeer.net/CPAN/
LICENSE
For contributors see file ChangeLog.
This software is copyright (c) 2003-2025 by Mark Overmeer.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.42.0 2025-12-14 User::Identity(3)