User::Identity(3)

📦
version 4.00 · 9 versions
, in fedora 44

💖 User::Identity — the manual, but make it a group chat 💖

Okay bestie, so this is User::Identity(3) from the User Contributed Perl Documentation set — it's the module that keeps track of info about a whole entire physical human person. Not a login, not an account, a human. Iconic concept, honestly. 🫶

✨ 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 💅

So the User-Identity distribution exists to maintain a whole little set of informational objects that are all related to one single user. And User::Identity itself is trying to be smart about it — it gives you defaults, it does conversions, and it handles the combos people keep asking for. Lowkey a service. ✨

⚠️ Real talk: this module, versions 4.0 and up, is not fully compatible with older releases — mainly the exception handling changed. So if you're upgrading, please go read the wiki <https://github.com/markov2/perl5-Mail-Box/wiki/>. Version 3 is still maintained and may see new releases as well. No cap, go read it. 📖

The identities do not implement any kind of storage, which means you can create them from literally any simple or complex Perl program you want. And that's the whole point — it's more flexible than an XML file for storing the data. Like, you can decide to store the data with Data::Dumper, Storable, DBI, AddressBook, or whatever you feel like. Extensions to simplify this task are still to be developed. (Somebody get on that bestie 😭)

If you need more kinds of user information, then please contact the module author. They wanna know. 💌

Extends "DESCRIPTION" in User::Identity::Item.

🎀 OVERLOADED 🎀

  • overload: "" stringification — when a User::Identity gets used as a string, it is automatically translated into the fullName() of the user involved. The way that just works. 💫

» 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 ) — creates a brand new user identity, which will contain all the data related to a single physical human being. Most user data can only be specified at object construction, because it should never change. A $name may be specified as the first argument, but also as an option — one way or the other is required, bestie. No name, no identity. 🚫
 -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  <required>
  nickname                           undef
  parent       User::Identity::Item  undef
  prefix                             undef
  surname                            undef
  titles                             undef

Here's every single one of them, spelled out, no skipping:

  • 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() — calculated from the date of birth to the current moment, as an integer. And on the birthday, the number is incremented already. 🎂 (yes, you get the new number on the day, not after)
  • $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 the 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 then capitalized if needed. 💖
  • $obj->formalName() — returns a formal name for the user. If not defined as an 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". So yeah — sometimes it's giving perfect, sometimes it's giving mystery. 😭
  • $obj->fullName() — if this is not specified as a value during object construction, it is guessed based on other known values like "firstname prefix surname". If a surname is provided without a firstname, the nickname is taken as firstname. When a firstname is provided without a surname, the nickname is taken as surname. And if both are not provided, then the nickname is used as fullname. It's doing its best fr fr. 🫶
  • $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 one: the exact specified value is returned. The methods isMale(), isFemale(), and courtesy() are the smart ones.
  • $obj->initials() — the initials, which may be derived from the first letters of the firstname. 🔤
  • $obj->isFemale() — see isMale(): returns "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 undetermined. Yeah. Both false. That's allowed. 💀
  • $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 fails. 💅

🧚 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 to '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(). (Yes, "nvalid". We are leaving it exactly as it is, bestie. 😌)
  • 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. 🫶

and that's the whole page bestie, you ate it, go build some identities 💅✨

Sign-off corner: this beauty is perl v5.42.0, dated 2026-01-17, filed under User::Identity(3) — periodt 🎀🦋

📦 where this page comes from