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
31       Extends "DESCRIPTION" in Mail::Identity.
32

OVERLOADED

34       overload: boolean
35           The object used as boolean will always return "true"
36
37       overload: string $comparison
38           Two address objects are the same when their email addresses are the
39           same.
40
41       overload: stringification
42           When the object is used in string context, it will return the
43           encoded representation of the e-mail address, just like string()
44           does.
45

METHODS

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

DIAGNOSTICS

158       Error: $object is not a collection.
159           The first argument is an object, but not of a class which extends
160           User::Identity::Collection.
161
162       Error: Cannot coerce a $type into a Mail::Message::Field::Address
163           When addresses are specified to be included in header fields, they
164           may be coerced into Mail::Message::Field::Address objects first.
165           What you specify is not accepted as address specification.  This
166           may be an internal error.
167
168       Error: Cannot load collection module for $type ($class).
169           Either the specified $type does not exist, or that module named
170           $class returns compilation errors.  If the type as specified in the
171           warning is not the name of a package, you specified a nickname
172           which was not defined.  Maybe you forgot the 'require' the package
173           which defines the nickname.
174
175       Error: Creation of a collection via $class failed.
176           The $class did compile, but it was not possible to create an object
177           of that class using the options you specified.
178
179       Error: Don't know what type of collection you want to add.
180           If you add a collection, it must either by a collection object or a
181           list of options which can be used to create a collection object.
182           In the latter case, the type of collection must be specified.
183
184       Warning: No collection $name
185           The collection with $name does not exist and can not be created.
186

LICENSE

192       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
193       contributors see ChangeLog.
194
195       This program is free software; you can redistribute it and/or modify it
196       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
197
198
199
200perl v5.36.0                      2022-07-22  Mail::Message::Field::Address(3)