Mail::Message::Field::Address(3pm)

1Mail::Message::Field::AUdsderresCso(n3t)ributed Perl DocMuamieln:t:aMteisosnage::Field::Address(3)
2
3
4

NAME

6       Mail::Message::Field::Address - One e-mail address
7

INHERITANCE

9        Mail::Message::Field::Address
10          is a Mail::Identity
11          is a User::Identity::Item
12

SYNOPSIS

14        my $addr = Mail::Message::Field::Address->new(...);
15
16        my $ui   = User::Identity->new(...);
17        my $addr = Mail::Message::Field::Address->coerce($ui);
18
19        my $mi   = Mail::Identity->new(...);
20        my $addr = Mail::Message::Field::Address->coerce($mi);
21
22        print $addr->address;
23        print $addr->fullName;   # possibly unicode!
24        print $addr->domain;
25

DESCRIPTION

27       Many header fields can contain e-mail addresses.  Each e-mail address
28       can be represented by an object of this class.  These objects will
29       handle interpretation and character set encoding and decoding for you.
30

OVERLOADED

32       overload: boolean
33           The object used as boolean will always return "true"
34
35       overload: stringification
36           When the object is used in string context, it will return the
37           encoded representation of the e-mail address, just like string()
38           does.
39

METHODS

41   Constructors
42       $obj->coerce(STRING|OBJECT, OPTIONS)
43           Try to coerce the OBJECT into a "Mail::Message::Field::Address".
44           In case of a STRING, it is interpreted as an email address.
45
46           The OPTIONS are passed to the object creation, and overrule the
47           values found in the OBJECT.  The result may be "undef" or a newly
48           created object.  If the OBJECT is already of the correct type, it
49           is returned unmodified.
50
51           The OBJECT may currently be a Mail::Address, a Mail::Identity, or a
52           User::Identity.  In case of the latter, one of the user's addresses
53           is chosen at random.
54
55       Mail::Message::Field::Address->new([NAME], OPTIONS)
56           See "Constructors" in Mail::Identity
57
58       $obj->parse(STRING)
59           Parse the string for an address.  You never know whether one or
60           more addresses are specified on a line (often applications are
61           wrong), therefore, the STRING is first parsed for as many addresses
62           as possible and then the one is taken at random.
63
64   Attributes
65       $obj->address
66           See "Attributes" in Mail::Identity
67
68       $obj->charset
69           See "Attributes" in Mail::Identity
70
71       $obj->comment([STRING])
72           See "Attributes" in Mail::Identity
73
74       $obj->description
75           See "Attributes" in User::Identity::Item
76
77       $obj->domain
78           See "Attributes" in Mail::Identity
79
80       $obj->language
81           See "Attributes" in Mail::Identity
82
83       $obj->location
84           See "Attributes" in Mail::Identity
85
86       $obj->name([NEWNAME])
87           See "Attributes" in User::Identity::Item
88
89       $obj->organization
90           See "Attributes" in Mail::Identity
91
92       $obj->phrase
93           See "Attributes" in Mail::Identity
94
95       $obj->username
96           See "Attributes" in Mail::Identity
97
98   Collections
99       $obj->add(COLLECTION, ROLE)
100           See "Collections" in User::Identity::Item
101
102       $obj->addCollection(OBJECT | ([TYPE], OPTIONS))
103           See "Collections" in User::Identity::Item
104
105       $obj->collection(NAME)
106           See "Collections" in User::Identity::Item
107
108       $obj->find(COLLECTION, ROLE)
109           See "Collections" in User::Identity::Item
110
111       $obj->parent([PARENT])
112           See "Collections" in User::Identity::Item
113
114       $obj->removeCollection(OBJECT|NAME)
115           See "Collections" in User::Identity::Item
116
117       $obj->type
118           Mail::Message::Field::Address->type
119
120           See "Collections" in User::Identity::Item
121
122       $obj->user
123           See "Collections" in User::Identity::Item
124
125   Accessors
126       $obj->encoding
127           Character-set encoding, like 'q' and 'b', to be used when non-ascii
128           characters are to be transmitted.
129
130   Access to the content
131       $obj->string
132           Returns an RFC compliant e-mail address, which will have character
133           set encoding if needed.  The objects are also overloaded to call
134           this method in string context.
135
136           example:
137
138            print $address->string;
139            print $address;          # via overloading
140

DIAGNOSTICS

142       Error: $object is not a collection.
143           The first argument is an object, but not of a class which extends
144           User::Identity::Collection.
145
146       Error: Cannot coerce a $type into a Mail::Message::Field::Address
147           When addresses are specified to be included in header fields, they
148           may be coerced into Mail::Message::Field::Address objects first.
149           What you specify is not accepted as address specification.  This
150           may be an internal error.
151
152       Error: Cannot load collection module for $type ($class).
153           Either the specified $type does not exist, or that module named
154           $class returns compilation errors.  If the type as specified in the
155           warning is not the name of a package, you specified a nickname
156           which was not defined.  Maybe you forgot the 'require' the package
157           which defines the nickname.
158
159       Error: Creation of a collection via $class failed.
160           The $class did compile, but it was not possible to create an object
161           of that class using the options you specified.
162
163       Error: Don't know what type of collection you want to add.
164           If you add a collection, it must either by a collection object or a
165           list of options which can be used to create a collection object.
166           In the latter case, the type of collection must be specified.
167
168       Warning: No collection $name
169           The collection with $name does not exist and can not be created.
170

LICENSE

176       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
177       ChangeLog.
178
179       This program is free software; you can redistribute it and/or modify it
180       under the same terms as Perl itself.  See
181       http://www.perl.com/perl/misc/Artistic.html
182
183
184
185perl v5.12.3                      2011-01-26  Mail::Message::Field::Address(3)