.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "User::Identity 3"
.TH User::Identity 3 2025-12-14 "perl v5.42.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
User::Identity \- maintain info about a physical person
.SH INHERITANCE
.IX Header "INHERITANCE"
.Vb 2
\& User::Identity
\&   is a User::Identity::Item
.Ve
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 8
\&  use User::Identity;
\&  my $me = User::Identity\->new(
\&    \*(Aqjohn\*(Aq,
\&    firstname => \*(AqJohn\*(Aq,
\&    surname   => \*(AqDoe\*(Aq
\&   );
\&  print $me\->fullName  # prints "John Doe"
\&  print $me;           # same
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`User\-Identity\*(C'\fR distribution is created to maintain a set of informational
objects which are related to one user.  The \f(CW\*(C`User::Identity\*(C'\fR module tries to
be smart providing defaults, conversions and often required combinations.
.PP
\&\fBBe aware:\fR
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 <https://github.com/markov2/perl5-Mail-Box/wiki/>.
\&\fBVersion 3 is still maintained\fR and may see new releases as well.
.PP
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.
.PP
If you need more kinds of user information, then please contact the
module author.
.PP
Extends "DESCRIPTION" in User::Identity::Item.
.SH OVERLOADED
.IX Header "OVERLOADED"
.IP "overload: \fB""""\fR stringification" 4
.IX Item "overload: """" stringification"
When an \f(CW\*(C`User::Identity\*(C'\fR is used as string, it is automatically
translated into the \fBfullName()\fR of the user involved.
.Sp
» example:
.Sp
.Vb 3
\&  my $me = User::Identity\->new(...)
\&  print $me;          # same as  print $me\->fullName
\&  print "I am $me\en"; # also stringification
.Ve
.SH METHODS
.IX Header "METHODS"
Extends "METHODS" in User::Identity::Item.
.SS Constructors
.IX Subsection "Constructors"
Extends "Constructors" in User::Identity::Item.
.ie n .IP "$class\->\fBnew\fR( [$name], %options )" 4
.el .IP "\f(CW$class\fR\->\fBnew\fR( [$name], \f(CW%options\fR )" 4
.IX 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 \f(CW$name\fR may be specified as first argument, but also
as option, one way or the other is required.
.Sp
.Vb 10
\& \-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                           \*(Aqen\*(Aq
\&  name         User::Identity::Item  <required>
\&  nickname                           undef
\&  parent       User::Identity::Item  undef
\&  prefix                             undef
\&  surname                            undef
\&  titles                             undef
.Ve
.RS 4
.IP "birth => DATE" 2
.IX Item "birth => DATE"
.PD 0
.IP "charset => STRING" 2
.IX Item "charset => STRING"
.IP "courtesy => STRING" 2
.IX Item "courtesy => STRING"
.IP "description => STRING" 2
.IX Item "description => STRING"
.IP "firstname => STRING" 2
.IX Item "firstname => STRING"
.IP "formal_name => STRING" 2
.IX Item "formal_name => STRING"
.IP "full_name => STRING" 2
.IX Item "full_name => STRING"
.IP "gender => STRING" 2
.IX Item "gender => STRING"
.IP "initials => STRING" 2
.IX Item "initials => STRING"
.IP "language => STRING" 2
.IX Item "language => STRING"
.IP "name => STRING" 2
.IX Item "name => STRING"
.IP "nickname => STRING" 2
.IX Item "nickname => STRING"
.IP "parent => OBJECT" 2
.IX Item "parent => OBJECT"
.IP "prefix => STRING" 2
.IX Item "prefix => STRING"
.IP "surname => STRING" 2
.IX Item "surname => STRING"
.IP "titles => STRING" 2
.IX Item "titles => STRING"
.PD
.RE
.RS 4
.RE
.SS Attributes
.IX Subsection "Attributes"
Extends "Attributes" in User::Identity::Item.
.ie n .IP $obj\->\fBage\fR() 4
.el .IP \f(CW$obj\fR\->\fBage\fR() 4
.IX Item "$obj->age()"
Calcuted from the datge of birth to the current moment, as integer.  On the
birthday, the number is incremented already.
.ie n .IP $obj\->\fBbirth\fR() 4
.el .IP \f(CW$obj\fR\->\fBbirth\fR() 4
.IX Item "$obj->birth()"
Returns the date in standardized format: YYYYMMDD, easy to sort and
select.  This may return \f(CW\*(C`undef\*(C'\fR, even if the \fBdateOfBirth()\fR contains
a value, simply because the format is not understood. Month or day may
contain \f(CW\*(Aq00\*(Aq\fR to indicate that those values are not known.
.ie n .IP $obj\->\fBcharset\fR() 4
.el .IP \f(CW$obj\fR\->\fBcharset\fR() 4
.IX Item "$obj->charset()"
The user\*(Aqs preferred character set, which defaults to the value of
LC_CTYPE environment variable.
.ie n .IP $obj\->\fBcourtesy\fR() 4
.el .IP \f(CW$obj\fR\->\fBcourtesy\fR() 4
.IX Item "$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.
.ie n .IP $obj\->\fBdateOfBirth\fR() 4
.el .IP \f(CW$obj\fR\->\fBdateOfBirth\fR() 4
.IX Item "$obj->dateOfBirth()"
Returns the date of birth, as specified during instantiation.
.ie n .IP $obj\->\fBdescription\fR() 4
.el .IP \f(CW$obj\fR\->\fBdescription\fR() 4
.IX Item "$obj->description()"
Inherited, see "Attributes" in User::Identity::Item
.ie n .IP $obj\->\fBfirstname\fR() 4
.el .IP \f(CW$obj\fR\->\fBfirstname\fR() 4
.IX 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.
.ie n .IP $obj\->\fBformalName\fR() 4
.el .IP \f(CW$obj\fR\->\fBformalName\fR() 4
.IX Item "$obj->formalName()"
Returns a formal name for the user.  If not defined as instantiation
parameter (see \fBnew()\fR), 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".
.ie n .IP $obj\->\fBfullName\fR() 4
.el .IP \f(CW$obj\fR\->\fBfullName\fR() 4
.IX Item "$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.
.ie n .IP $obj\->\fBgender\fR() 4
.el .IP \f(CW$obj\fR\->\fBgender\fR() 4
.IX Item "$obj->gender()"
Returns the specified gender of the person, as specified during
instantiation, which could be like \*(AqMale\*(Aq, \*(Aqm\*(Aq, \*(Aqhomme\*(Aq, \*(Aqman\*(Aq.
There is no smart behavior on this: the exact specified value is
returned. Methods \fBisMale()\fR, \fBisFemale()\fR, and \fBcourtesy()\fR are smart.
.ie n .IP $obj\->\fBinitials\fR() 4
.el .IP \f(CW$obj\fR\->\fBinitials\fR() 4
.IX Item "$obj->initials()"
The initials, which may be derived from the first letters of the
firstname.
.ie n .IP $obj\->\fBisFemale\fR() 4
.el .IP \f(CW$obj\fR\->\fBisFemale\fR() 4
.IX Item "$obj->isFemale()"
See \fBisMale()\fR: return \f(CW\*(C`true\*(C'\fR if we are sure the user is a woman.
.ie n .IP $obj\->\fBisMale\fR() 4
.el .IP \f(CW$obj\fR\->\fBisMale\fR() 4
.IX Item "$obj->isMale()"
Returns \f(CW\*(C`true\*(C'\fR 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 \f(CW\*(C`false\*(C'\fR
for the same user, in which case the gender is undertermined.
.ie n .IP $obj\->\fBlanguage\fR() 4
.el .IP \f(CW$obj\fR\->\fBlanguage\fR() 4
.IX Item "$obj->language()"
Can contain a list or a single language name, as defined by the RFC
Examples are \*(Aqen\*(Aq, \*(Aqen\-GB\*(Aq, \*(Aqnl\-BE\*(Aq.  The default language  is \*(Aqen\*(Aq
(English).
.ie n .IP "$obj\->\fBname\fR( [$newname] )" 4
.el .IP "\f(CW$obj\fR\->\fBname\fR( [$newname] )" 4
.IX Item "$obj->name( [$newname] )"
Inherited, see "Attributes" in User::Identity::Item
.ie n .IP $obj\->\fBnickname\fR() 4
.el .IP \f(CW$obj\fR\->\fBnickname\fR() 4
.IX Item "$obj->nickname()"
Returns the user\*(Aqs nickname, which could be used as username, e\-mail
alias, or such.  When no nickname was explicitly specified, the name is
used.
.ie n .IP $obj\->\fBprefix\fR() 4
.el .IP \f(CW$obj\fR\->\fBprefix\fR() 4
.IX Item "$obj->prefix()"
The words which are between the firstname (or initials) and the surname.
.ie n .IP $obj\->\fBsurname\fR() 4
.el .IP \f(CW$obj\fR\->\fBsurname\fR() 4
.IX Item "$obj->surname()"
Returns the surname of person, or \f(CW\*(C`undef\*(C'\fR if that is not known.
.ie n .IP $obj\->\fBtitles\fR() 4
.el .IP \f(CW$obj\fR\->\fBtitles\fR() 4
.IX Item "$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.
.SS Collections
.IX Subsection "Collections"
Extends "Collections" in User::Identity::Item.
.ie n .IP "$obj\->\fBadd\fR($collection, $role)" 4
.el .IP "\f(CW$obj\fR\->\fBadd\fR($collection, \f(CW$role\fR)" 4
.IX Item "$obj->add($collection, $role)"
Inherited, see "Collections" in User::Identity::Item
.ie n .IP "$obj\->\fBaddCollection\fR( $object | <[$type], %options> )" 4
.el .IP "\f(CW$obj\fR\->\fBaddCollection\fR( \f(CW$object\fR | <[$type], \f(CW%options\fR> )" 4
.IX Item "$obj->addCollection( $object | <[$type], %options> )"
Inherited, see "Collections" in User::Identity::Item
.ie n .IP $obj\->\fBcollection\fR($name) 4
.el .IP \f(CW$obj\fR\->\fBcollection\fR($name) 4
.IX Item "$obj->collection($name)"
Inherited, see "Collections" in User::Identity::Item
.ie n .IP "$obj\->\fBparent\fR( [$parent] )" 4
.el .IP "\f(CW$obj\fR\->\fBparent\fR( [$parent] )" 4
.IX Item "$obj->parent( [$parent] )"
Inherited, see "Collections" in User::Identity::Item
.ie n .IP $obj\->\fBremoveCollection\fR($object|$name) 4
.el .IP \f(CW$obj\fR\->\fBremoveCollection\fR($object|$name) 4
.IX Item "$obj->removeCollection($object|$name)"
Inherited, see "Collections" in User::Identity::Item
.ie n .IP $any\->\fBtype\fR() 4
.el .IP \f(CW$any\fR\->\fBtype\fR() 4
.IX Item "$any->type()"
Inherited, see "Collections" in User::Identity::Item
.ie n .IP $obj\->\fBuser\fR() 4
.el .IP \f(CW$obj\fR\->\fBuser\fR() 4
.IX Item "$obj->user()"
Inherited, see "Collections" in User::Identity::Item
.SS Searching
.IX Subsection "Searching"
Extends "Searching" in User::Identity::Item.
.ie n .IP "$obj\->\fBfind\fR($collection, $role)" 4
.el .IP "\f(CW$obj\fR\->\fBfind\fR($collection, \f(CW$role\fR)" 4
.IX Item "$obj->find($collection, $role)"
Inherited, see "Searching" in User::Identity::Item
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
.ie n .IP "Error: cannot load collection module for $type ($class): $@" 4
.el .IP "Error: cannot load collection module for \f(CW$type\fR ($class): $@" 4
.IX Item "Error: cannot load collection module for $type ($class): $@"
Either the specified \f(CW$type\fR does not exist, or that module named \f(CW$class\fR 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 \*(Aqrequire\*(Aq the package which defines the nickname.
Cast by \f(CWaddCollection()\fR
.ie n .IP "Error: nvalid collection $name." 4
.el .IP "Error: nvalid collection \f(CW$name\fR." 4
.IX Item "Error: nvalid collection $name."
The collection with \f(CW$name\fR does not exist and can not be created.
Cast by \f(CWadd()\fR
.ie n .IP "Error: this $object is not a collection." 4
.el .IP "Error: this \f(CW$object\fR is not a collection." 4
.IX Item "Error: this $object is not a collection."
Cast by \f(CWaddCollection()\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of User\-Identity version 4.00,
built on December 12, 2025. Website: \fIhttp://perl.overmeer.net/CPAN/\fR
.SH LICENSE
.IX Header "LICENSE"
For contributors see file ChangeLog.
.PP
This software is copyright (c) 2003\-2025 by Mark Overmeer.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.