unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

User::Identity(3pm)   User Contributed Perl Documentation  User::Identity(3pm)



NAME
       User::Identity - maintains info about a physical person

INHERITANCE
        User::Identity
          is an 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" object is created to maintain a set of informa-
       tional objects which are related to one user.  The "User::Identity"
       module tries to be smart providing defaults, conversions and often
       required combinations.

       The identities are not implementing any kind of storage, and can there-
       fore 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, Address-
       Book 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.

OVERLOADED
       $obj->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
       Constructors

       User::Identity->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 speci-
           fied 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  <required>
            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

       $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() con-
           tains 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 prefered 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.  Val-
           ues 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

           See "Attributes" in User::Identity::Item

       $obj->firstname

           Returns the first name of the user.  If it is not defined explic-
           itly, it is derived from the nickname, and than capitalized if
           needed.

       $obj->formalName

           Returns a formal name for the user.  If not defined as instantia-
           tion 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 sur-
           name".  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 speci-
           fied 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])

           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

       $obj->add(COLLECTION, ROLE)

           See "Collections" in User::Identity::Item

       $obj->addCollection(OBJECT | ([TYPE], OPTIONS))

           See "Collections" in User::Identity::Item

       $obj->collection(NAME)

           See "Collections" in User::Identity::Item

       $obj->find(COLLECTION, ROLE)

           See "Collections" in User::Identity::Item

       $obj->parent([PARENT])

           See "Collections" in User::Identity::Item

       $obj->removeCollection(OBJECT|NAME)

           See "Collections" in User::Identity::Item

       $obj->type

       User::Identity->type

           See "Collections" in User::Identity::Item

       $obj->user

           See "Collections" in User::Identity::Item

DIAGNOSTICS
       Error: $object is not a collection.

           The first argument is an object, but not of a class which extends
           User::Identity::Collection.

       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.

       Error: Creation of a collection via $class failed.

           The $class did compile, but it was not possible to create an object
           of that class using the options you specified.

       Error: Don't know what type of collection you want to add.

           If you add a collection, it must either by a collection object or a
           list of options which can be used to create a collection object.
           In the latter case, the type of collection must be specified.

       Warning: No collection $name

           The collection with $name does not exist and can not be created.

SEE ALSO
       This module is part of User-Identity distribution version 0.92, built
       on July 25, 2007. Website: http://perl.overmeer.net/userid/

LICENSE
       Copyrights 2003,2004,2007 by Mark Overmeer <perlATovermeer.net>. For
       other contributors see Changes.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html



perl v5.8.8                       2008-02-28               User::Identity(3pm)