
=head1 NAME

User::Identity - info about a physical person

=head1 SYNOPSIS

 use User::Identity;
 my $me = User::Indentity->new
  ( firstname => 'John'
  , surname   => 'Doe'
  );
 print $me;           # prints "John Doe"
 print $me->fullName  # same

=head1 DESCRIPTION

The User::Identity object is created to maintain a set of information
which is related to one user.  The identity can be created by any
simple or complex Perl program, and is therefore more flexible than
an XML file.  If you need more kinds of user information, then please
contact the author.

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> [NICKNAME], OPTIONS

(Class method) 
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 NICKNAME may be specified as first argument, but also
as option.

 OPTION               DEFAULT
 charset              'us-ascii'
 courtesy             undef
 date_of_birth        undef
 firstname            undef
 formal_name          undef
 full_name            undef
 gender               undef
 initials             undef
 language             undef
 nickname             undef
 prefix               undef
 surname              undef
 titles               undef

=over 4

=item B<charset> =E<gt> STRING

=item B<courtesy> =E<gt> STRING

=item B<date_of_birth> =E<gt> DATE

=item B<firstname> =E<gt> STRING

=item B<formal_name> =E<gt> STRING

=item B<full_name> =E<gt> STRING

=item B<gender> =E<gt> STRING

=item B<initials> =E<gt> STRING

=item B<language> =E<gt> STRING

=item B<nickname> =E<gt> STRING

=item B<prefix> =E<gt> STRING

=item B<surname> =E<gt> STRING

=item B<titles> =E<gt> STRING

=back

=back

=head2 Overloading

=over 4

=item B<stringification> 

When an User::Identity is used as string, it is automatically
translated into the fullName() of the user involved.

Examples:

 my $me = User::Identity->new(...)
 print $me;          # same as  print $me->fullName
 print "I am $me\n"; # also stringification

=back

=head2 Attributes

=over 4

=item B<age> 

Calcuted from the datge of birth to the current moment, as integer.  On the
birthday, the number is incremented already.

=item B<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.

=item B<charset> 

The user's prefered character set.

=item B<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.

=item B<dateOfBirth> 

Returns the date of birth, as specified during instantiation.

=item B<firstname> 

=item B<formalName> 

Returns a formal name for the user.  If not defined as instantiation
parameter, 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".

=item B<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.

=item B<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.

=item B<initials> 

The initials, which may be derived from the first letters of the
firstname.

=item B<isFemale> 

See isMale(): return true if we are sure it is a woman.

=item B<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.  Method
isMale and isFemale are not complementatory: they can both return false
for the same user, in which case the gender is undertermined.

=item B<language> 

Can contain a list or a single language name, as defined by the RFC
Examples are 'en', 'en-GB', 'nl-BE'.

in scalar context only one value
is returned (the first in case of a list) as preferred language of the
person.  In list context, all (or the only one) value is returned.

=item B<nickname> 

Returns the user's nickname, which could be used as username, e-mail
alias, or such.  When no nick is specified, firstname() is called,
and all characters converted to lower case.

=item B<prefix> 

The words which are between the firstname (or initials) and the surname.

=item B<surname> 

Returns the surname of person, or C<undef> if that is not known.

=item B<titles> 

The titles, degrees in education or of other kind.  If these are complex, you
may need to specify a formal name as well because formatting sometimes
failes.

=back

=head2 Collections

=over 4

=item B<add> COLLECTION, ROLE

The ROLE is added to the COLLECTION.  The COLLECTION is the name of a
collection, which will be created automatically with addCollection if
needed.  The ROLE is anything what is acceptable to addRole() of the
collection at hand, and is returned.

Examples:

 my $ui   = User::Identity->new(...);
 my $home = $ui->add(location => [home => street => '27 Roadstreet', ...] );
 my $work = $ui->add(location => work, tel => '+31-2231-342-13', ... );

 my $travel = User::Identity::Location->new(travel => ...);
 $ui->add(location => $travel);

=item B<addCollection> OBJECT | ([TYPE], OPTIONS)

Add a new collect of roles to the user.  This can be achieved in two ways:
either create anu User::Identity::Collection OBJECT yourself and then
pass that to this method, or supply all the OPTIONS needed to create such
an object and it will be created for you.  The object which is added is
returned.

For OPTIONS, see the specific type of collection.  Additional options are
listed below.

 OPTION               DEFAULT
 type                 <required>

=over 4

=item B<type> =E<gt> STRING|CLASS

The nickname of a collection class or the CLASS name itself of the
object to be created.  Required if an object has to be created.
Predefined type nicknames are C<email> and C<location>.

=back

Examples:

 my $me   = User::Identity->new(...);
 my $locs = User::Identity::Collection::Locations->new();
 $me->addCollection($locs);

 my $email = $me->addCollection(type => 'email');
 my $email = $me->addCollection('email');

=item B<collection> NAME

In scalar context with only a NAME, the collection object is returned.
In list context, all the roles within the collection are returned.

Examples:

 my @roles = $me->collection('email');        # list of collected items
 my @roles = $me->collection('email')->roles; # same of collected items
 my $coll  = $me->collection('email');        # a User::Identity::Collection

=item B<find> COLLECTION, ROLE

Returns the object with the specified ROLE within the named collection.

Examples:

 my $role  = $me->find(location => 'work');       # one location
 my $role  = $me->collection('location')->find('work'); # same

=back

=head1 SEE ALSO

See the website at L<http://perl.overmeer.net/userid/>.

=head1 AUTHOR

Written by Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>)
with the help of many.  See the ChangeLog for details.

=head1 VERSION

This code is beta, version 0.02.

Copyright (c) 2003 by the authors. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
