1=encoding utf8
2
3=head1 NAME
4
5Mail::Message::Field::Attribute - one attribute of a full field
6
7=head1 INHERITANCE
8
9 Mail::Message::Field::Attribute
10   is a Mail::Reporter
11
12=head1 SYNOPSIS
13
14 my $field    = $msg->head->get('Content-Disposition') or return;
15 my $full     = $field->study;   # full understanding in unicode
16 my $filename = $full->attribute('filename')           or return;
17
18 print ref $filename;     # this class name
19 print $filename;         # the attributes content in utf-8
20 print $filename->value;  # same
21 print $filename->string; # print string as was found in the file
22 $filename->print(\*OUT); # print as was found in the file
23
24=head1 DESCRIPTION
25
26Attributes within MIME fields can be quite complex, and therefore be slow
27and consumes a lot of memory.  The L<Mail::Message::Field::Fast|Mail::Message::Field::Fast> and
28L<Mail::Message::Field::Flex|Mail::Message::Field::Flex> simplify them the attributes a lot, which
29may result in erroneous behavior in rare cases.  With the increase of
30non-western languages on Internet, the need for the complex headers
31becomes more and more in demand.
32
33A C<Mail::Message::Field::Attribute> can be found in any structured
34L<Mail::Message::Field::Full|Mail::Message::Field::Full> header field.
35
36Extends L<"DESCRIPTION" in Mail::Reporter|Mail::Reporter/"DESCRIPTION">.
37
38=head1 OVERLOADED
39
40=over 4
41
42=item overload: B<comparison>
43
44When the second argument is a field, then both attribute name (case-sensitive)
45and the decoded value must be the same.  Otherwise, the value is compared.
46
47=item overload: B<stringification>
48
49Returns the decoded content of the attribute.
50
51=back
52
53=head1 METHODS
54
55Extends L<"METHODS" in Mail::Reporter|Mail::Reporter/"METHODS">.
56
57=head2 Constructors
58
59Extends L<"Constructors" in Mail::Reporter|Mail::Reporter/"Constructors">.
60
61=over 4
62
63=item Mail::Message::Field::Attribute-E<gt>B<new>( <$name, [$value] | STRING>, %options )
64
65Create a new attribute $name with the optional $value.  If no $value is specified,
66the first argument of this method is inspected for an equals sign C<'='>.
67If that character is present, the argument is taken as STRING, containing
68a preformatted attribute which is processed.  Otherwise, the argument is
69taken as name without $value: set the value later with value().
70
71Whether encoding takes place depends on the %options and the existence
72of non-ascii characters in the $value.  The $name can only contain ascii
73characters, hence is never encoded.
74
75To speed things up, attributes are not derived from the L<Mail::Reporter|Mail::Reporter>
76base-class.
77
78 -Option           --Defined in     --Default
79  charset                             'us-ascii'
80  language                            undef
81  log                Mail::Reporter   'WARNINGS'
82  trace              Mail::Reporter   'WARNINGS'
83  use_continuations                   <true>
84
85=over 2
86
87=item charset => STRING
88
89The $value is translated from utf-8 (Perl internal) to this character set,
90and the resulting string is encoded if required.  C<us-ascii> is the normal
91encoding for e-mail.  Valid character sets can be found with
92Encode::encodings(':all').
93
94=item language => STRING
95
96RFC2231 adds the possibility to specify a language with the field.  When no
97language is specified, none is included in the encoding.  Valid language
98names are defined by RFC2130.  This module has only limited support for
99this feature.
100
101=item log => LEVEL
102
103=item trace => LEVEL
104
105=item use_continuations => BOOLEAN
106
107Continuations are used to break-up long parameters into pieces which
108are no longer than 76 characters. Encodings are specified in RFC2231,
109but not supported by some Mail User Agents.
110
111=back
112
113example:
114
115 my $fn    = Mail::Message::Field::Attribute
116                ->new(filename => 'xyz');
117
118 my $fattr = 'Mail::Message::Field::Attribute';  # abbrev
119 my $fn    = $fattr->new
120   ( filename => "Re\xC7u"
121   , charset  => 'iso-8859-15'
122   , language => 'nl-BE'
123   );
124 print $fn;
125   # -->  filename*=iso-8859-15'nl-BE'Re%C7u
126
127=back
128
129=head2 Error handling
130
131Extends L<"Error handling" in Mail::Reporter|Mail::Reporter/"Error handling">.
132
133=over 4
134
135=item $obj-E<gt>B<AUTOLOAD>()
136
137Inherited, see L<Mail::Reporter/"Error handling">
138
139=item $obj-E<gt>B<addReport>($object)
140
141Inherited, see L<Mail::Reporter/"Error handling">
142
143=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
144
145=item Mail::Message::Field::Attribute-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
146
147Inherited, see L<Mail::Reporter/"Error handling">
148
149=item $obj-E<gt>B<errors>()
150
151Inherited, see L<Mail::Reporter/"Error handling">
152
153=item $obj-E<gt>B<log>( [$level, [$strings]] )
154
155=item Mail::Message::Field::Attribute-E<gt>B<log>( [$level, [$strings]] )
156
157Inherited, see L<Mail::Reporter/"Error handling">
158
159=item $obj-E<gt>B<logPriority>($level)
160
161=item Mail::Message::Field::Attribute-E<gt>B<logPriority>($level)
162
163Inherited, see L<Mail::Reporter/"Error handling">
164
165=item $obj-E<gt>B<logSettings>()
166
167Inherited, see L<Mail::Reporter/"Error handling">
168
169=item $obj-E<gt>B<notImplemented>()
170
171Inherited, see L<Mail::Reporter/"Error handling">
172
173=item $obj-E<gt>B<report>( [$level] )
174
175Inherited, see L<Mail::Reporter/"Error handling">
176
177=item $obj-E<gt>B<reportAll>( [$level] )
178
179Inherited, see L<Mail::Reporter/"Error handling">
180
181=item $obj-E<gt>B<trace>( [$level] )
182
183Inherited, see L<Mail::Reporter/"Error handling">
184
185=item $obj-E<gt>B<warnings>()
186
187Inherited, see L<Mail::Reporter/"Error handling">
188
189=back
190
191=head2 Cleanup
192
193Extends L<"Cleanup" in Mail::Reporter|Mail::Reporter/"Cleanup">.
194
195=over 4
196
197=item $obj-E<gt>B<DESTROY>()
198
199Inherited, see L<Mail::Reporter/"Cleanup">
200
201=back
202
203=head2 The attribute
204
205=over 4
206
207=item $obj-E<gt>B<addComponent>(STRING)
208
209A component is a parameter as defined by RFC2045, optionally using
210encoding or continuations as defined by RFC2231.  Components of an
211attribute are found when a field is being parsed.  The RFCs are
212very strict on valid characters, but we cannot be: you have to accept
213what is coming in if you can.
214
215example:
216
217 my $param = Mail::Message::Field::Attribute->new;
218 $param->addComponent("filename*=iso10646'nl-BE'%Re\47u");
219
220=item $obj-E<gt>B<charset>()
221
222Returns the character set which is used for this parameter.  If any component
223is added which contains character set information, this is directly
224available.  Be warned that a character-set is case insensitive.
225
226=item $obj-E<gt>B<language>()
227
228Returns the language which is defined in the argument.  If no language is
229defined C<undef> is returned, which should be interpreted as "ANY"
230
231=item $obj-E<gt>B<name>()
232
233Returns the name of this attribute.
234
235=item $obj-E<gt>B<string>()
236
237Returns the parameter as reference to an array of lines.  When only one line
238is returned, it may be short enough to fit on the same line with other
239components of the header field.
240
241=item $obj-E<gt>B<value>( [STRING] )
242
243Returns the value of this parameter, optionally after setting it first.
244
245=back
246
247=head2 Attribute encoding
248
249=over 4
250
251=item $obj-E<gt>B<decode>()
252
253Translate all known continuations into a value.  The produced value is
254returned and may be utf-8 encoded or a plain string.
255
256=item $obj-E<gt>B<encode>()
257
258=back
259
260=head2 Internals
261
262=over 4
263
264=item $obj-E<gt>B<mergeComponent>($attribute)
265
266Merge the components from the specified attribute into this attribute.  This
267is needed when components of the same attribute are created separately.
268Merging is required by the field parsing.
269
270=back
271
272=head1 DIAGNOSTICS
273
274=over 4
275
276=item Warning: Illegal character in parameter name '$name'
277
278The specified parameter name contains characters which are not permitted by
279the RFCs.  You can better change the name into something which is accepted,
280or risk applications to corrupt or ignore the message.
281
282=item Error: Package $package does not implement $method.
283
284Fatal error: the specific package (or one of its superclasses) does not
285implement this method where it should. This message means that some other
286related classes do implement this method however the class at hand does
287not.  Probably you should investigate this and probably inform the author
288of the package.
289
290=item Error: Too late to merge: value already changed.
291
292=back
293
294=head1 SEE ALSO
295
296This module is part of Mail-Message distribution version 3.011,
297built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/>
298
299=head1 LICENSE
300
301Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
302
303This program is free software; you can redistribute it and/or modify it
304under the same terms as Perl itself.
305See F<http://dev.perl.org/licenses/>
306
307