1Mail::Identity(3) User Contributed Perl Documentation Mail::Identity(3)
2
6 Mail::Identity - an e-mail role
7
9 Mail::Identity
10 is a User::Identity::Item
11
13 use User::Identity;
14 use Mail::Identity;
15 my $me = User::Identity->new(...);
16 my $addr = Mail::Identity->new(address => 'x@y');
17 $me->add(email => $addr);
18 # Simpler
20 use User::Identity;
22 my $me = User::Identity->new(...);
23 my $addr = $me->add(email => 'x@y');
24 my $addr = $me->add( email => 'home'
25 , address => 'x@y');
26 # Conversion
28 my $ma = Mail::Address->new(...);
29 my $mi = Mail::Identity->coerce($ma);
30
32 The "Mail::Identity" object contains the description of role played by
33 a human when sending e-mail. Most people have more than one role these
34 days: for instance, a private and a company role with different e-mail
35 addresses.
36 An "Mail::Identity" object combines an e-mail address, user description
38 ("phrase"), a signature, pgp-key, and so on. All fields are optional,
39 and some fields are smart. One such set of data represents one role.
40 "Mail::Identity" is therefore the smart cousine of the Mail::Address
41 object.
42
44 Constructors
45 $obj->from(OBJECT)
46 Convert an OBJECT into a "Mail::Identity". On the moment, you can
48 specify Mail::Address and User::Identity objects. In the former
49 case, a new "Mail::Identity" is created containing the same
50 information. In the latter, the first address of the user is
51 picked and returned.
52 Mail::Identity->new([NAME], OPTIONS)
54 Option --Defined in --Default
56 address <username@domain or name>
57 charset <user's charset>
58 comment <user's fullname if phrase is different>
59 description User::Identity::Item undef
60 domain <from email or localhost>
61 language <from user>
62 location <random user's location>
63 name User::Identity::Item <phrase or user's fullName>
64 organization <location's organization>
65 parent User::Identity::Item undef
66 pgp_key undef
67 phrase <user's fullName>
68 signature undef
69 username <from address or user's nickname>
70 . address => STRING
72 The e-mail address is constructed from the username/domain, but
74 when both do not exist, the name is taken.
75 . charset => STRING
77 . comment => STRING
79 . description => STRING
81 . domain => STRING
83 . language => STRING
85 . location => NAME|OBJECT
87 The user's location which relates to this mail identity. This
89 can be specified as location name (which will be looked-up when
90 needed), or as User::Identity::Location object.
91 . name => STRING
93 . organization => STRING
95 Usually defined for e-mail addresses which are used by a
97 company or other organization, but less common for personal
98 addresses. This value will be used to fill the "Organization"
99 header field of messages.
100 . parent => OBJECT
102 . pgp_key => STRING|FILENAME
104 . phrase => STRING
106 . signature => STRING
108 . username => STRING
110 Constructors
112 Attributes
113 $obj->address
114 Returns the e-mail address for this role. If none was specified,
116 it will be constructed from the username and domain. If those are
117 not present as well, then the name() is used when it contains a
118 "@", else the user's nickname is taken.
119 $obj->charset
121 Returns the character set used in comment and phrase. When set to
123 "undef", the strings (are already encoded to) contain only ASCII
124 characters. This defaults to the value of the user's charset, if a
125 user is defined.
126 $obj->comment([STRING])
128 E-mail address -when included in message MIME headers- can contain
130 a comment. The RFCs advice not to store useful information in
131 these comments, but it you really want to, you can do it. The
132 comment defaults to the user's fullname if the phrase is not the
133 fullname and there is a user defined.
134 Comments will be enclosed in parenthesis when used. Parenthesis
136 (matching) or non-matching) which are already in the string will
137 carefully escaped when needed. You do not need to worry.
138 $obj->description
140 See "Attributes" in User::Identity::Item
142 $obj->domain
144 The domain is the part of the e-mail address after the "@"-sign.
146 When this is not defined, it can be deducted from the email address
147 (see address()). If nothing is known, "localhost" is returned.
148 $obj->language
150 Returns the language which is used for the description fields of
152 this e-mail address, which defaults to the user's language.
153 $obj->location
155 Returns the object which describes to which location this mail
157 address relates. The location may be used to find the name of the
158 organization involved, or to create a signature. If no location is
159 specified, but a user is defined which has locations, one of those
160 is randomly chosen.
161 $obj->name([NEWNAME])
163 See "Attributes" in User::Identity::Item
165 $obj->organization
167 Returns the organization which relates to this e-mail identity. If
169 not explicitly specified, it is tried to be found via the location.
170 $obj->phrase
172 The phrase is used in an e-mail address to explain who is sending
174 the message. This usually is the fullname (the user's fullname is
175 used by default), description of your function (Webmaster), or any
176 other text.
177 When an email string is produced, the phase will be quoted if
179 needed. Quotes which are within the string will automatically be
180 escaped, so you do no need to worry: input cannot break the
181 outcome!
182 $obj->username
184 Returns the username of this e-mail address. If none is specified,
186 first it is tried to extract it from the specified e-mail address.
187 If there is also no username in the e-mail address, the user
188 identity's nickname is taken.
189 Collections
191 $obj->add(COLLECTION, ROLE)
192 See "Collections" in User::Identity::Item
194 $obj->addCollection(OBJECT | ([TYPE], OPTIONS))
196 See "Collections" in User::Identity::Item
198 $obj->collection(NAME)
200 See "Collections" in User::Identity::Item
202 $obj->find(COLLECTION, ROLE)
204 See "Collections" in User::Identity::Item
206 $obj->parent([PARENT])
208 See "Collections" in User::Identity::Item
210 $obj->removeCollection(OBJECT|NAME)
212 See "Collections" in User::Identity::Item
214 $obj->type
216 Mail::Identity->type
218 See "Collections" in User::Identity::Item
220 $obj->user
222 See "Collections" in User::Identity::Item
224
226 Error: $object is not a collection.
227 The first argument is an object, but not of a class which extends
229 User::Identity::Collection.
230 Error: Cannot load collection module for $type ($class).
232 Either the specified $type does not exist, or that module named
234 $class returns compilation errors. If the type as specified in the
235 warning is not the name of a package, you specified a nickname
236 which was not defined. Maybe you forgot the 'require' the package
237 which defines the nickname.
238 Error: Creation of a collection via $class failed.
240 The $class did compile, but it was not possible to create an object
242 of that class using the options you specified.
243 Error: Don't know what type of collection you want to add.
245 If you add a collection, it must either by a collection object or a
247 list of options which can be used to create a collection object.
248 In the latter case, the type of collection must be specified.
249 Warning: No collection $name
251 The collection with $name does not exist and can not be created.
253
255 This module is part of User-Identity distribution version 0.93, built
256 on December 24, 2009. Website: http://perl.overmeer.net/userid/
257
259 Copyrights 2003,2004,2007-2009 by Mark Overmeer <perl@overmeer.net>.
260 For other contributors see Changes.
261 This program is free software; you can redistribute it and/or modify it
263 under the same terms as Perl itself. See
264 http://www.perl.com/perl/misc/Artistic.html
265perl v5.12.1 2009-12-24 Mail::Identity(3)