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

1Mail::Message::Field::AUtsterribCuotnet(r3i)buted Perl DMoaciulm:e:nMteastsiaogne::Field::Attribute(3)
2
3
4

NAME

6       Mail::Message::Field::Attribute - one attribute of a full field
7

INHERITANCE

9        Mail::Message::Field::Attribute
10          is a Mail::Reporter
11

SYNOPSIS

13        my $field    = $msg->head->get('Content-Disposition') or return;
14        my $full     = $field->study;   # full understanding in unicode
15        my $filename = $full->attribute('filename')           or return;
16
17        print ref $filename;     # this class name
18        print $filename;         # the attributes content in utf-8
19        print $filename->value;  # same
20        print $filename->string; # print string as was found in the file
21        $filename->print(\*OUT); # print as was found in the file
22

DESCRIPTION

24       Attributes within MIME fields can be quite complex, and therefore be
25       slow and consumes a lot of memory.  The Mail::Message::Field::Fast and
26       Mail::Message::Field::Flex simplify them the attributes a lot, which
27       may result in erroneous behavior in rare cases.  With the increase of
28       non-western languages on Internet, the need for the complex headers
29       becomes more and more in demand.
30
31       A "Mail::Message::Field::Attribute" can be found in any structured
32       Mail::Message::Field::Full header field.
33

METHODS

35       Constructors
36
37       Mail::Message::Field::Attribute->new((NAME, [VALUE] ⎪ STRING), OPTIONS)
38
39           Create a new attribute NAME with the optional VALUE.  If no VALUE
40           is specified, the first argument of this method is inspected for an
41           equals sign '='.  If that character is present, the argument is
42           taken as STRING, containing a preformatted attribute which is pro‐
43           cessed.  Otherwise, the argument is taken as name without VALUE:
44           set the value later with value().
45
46           Whether encoding takes place depends on the OPTIONS and the exis‐
47           tence of non-ascii characters in the VALUE.  The NAME can only con‐
48           tain ascii characters, hence is never encoded.
49
50           To speed things up, attributes are not derived from the
51           Mail::Reporter base-class.
52
53            Option           --Defined in     --Default
54            charset                             'us-ascii'
55            language                            undef
56            log                Mail::Reporter   'WARNINGS'
57            trace              Mail::Reporter   'WARNINGS'
58            use_continuations                   <true>
59
60           . charset STRING
61
62               The VALUE is translated from utf-8 (Perl internal) to this
63               character set, and the resulting string is encoded if required.
64               "us-ascii" is the normal encoding for e-mail.  Valid character
65               sets can be found with Encode::encodings(':all').
66
67           . language STRING
68
69               RFC2231 adds the possiblity to specify a language with the
70               field.  When no language is specified, none is included in the
71               encoding.  Valid language names are defined by RFC2130.  This
72               module has only limited support for this feature.
73
74           . log LEVEL
75
76           . trace LEVEL
77
78           . use_continuations BOOLEAN
79
80               Continuations are used to break-up long parameters into pieces
81               which are no longer than 76 characters. Encodings are specified
82               in RFC2231, but not supported by some Mail User Agents.
83
84           Example:
85
86            my $fn    = Mail::Message::Field::Attribute
87                           ->new(filename => 'xyz');
88
89            my $fattr = 'Mail::Message::Field::Attribute';  # abbrev
90            my $fn    = $fattr->new
91                ( filename => "Re\xC7u"
92                , charset  => 'iso-8859-15'
93                , language => 'nl-BE'
94                );
95            print $fn;
96              # -->  filename*=iso-8859-15'nl-BE'Re%C7u
97
98       The attribute
99
100       $obj->addComponent(STRING)
101
102           A component is a parameter as defined by RFC2045, optionally using
103           encoding or continuations as defined by RFC2231.  Components of an
104           attribute are found when a field is being parsed.  The RFCs are
105           very strict on valid characters, but we cannot be: you have to
106           accept what is coming in if you can.
107
108           Example:
109
110            my $param = Mail::Message::Field::Attribute->new;
111            $param->addComponent("filename*=iso10646'nl-BE'%Re\47u");
112
113       $obj->charset
114
115           Returns the character set which is used for this parameter.  If any
116           component is added which contains character set information, this
117           is directly available.  Be warned that a character-set is case
118           insensitive.
119
120       $obj->language
121
122           Returns the language which is defined in the argument.  If no lan‐
123           guage is defined "undef" is returned, which should be interpreted
124           as "ANY"
125
126       $obj->name
127
128           Returns the name of this attribute.
129
130       $obj->string
131
132           Returns the parameter as reference to an array of lines.  When only
133           one line is returned, it may be short enough to fit on the same
134           line with other components of the header field.
135
136       $obj->value([STRING])
137
138           Returns the value of this parameter, optionally after setting it
139           first.
140
141       Attribute encoding
142
143       $obj->decode
144
145           Translate all known continuations into a value.  The produced value
146           is returned and may be utf-8 encoded or a plain string.
147
148       $obj->encode
149
150       Internals
151
152       $obj->mergeComponent(ATTRIBUTE)
153
154           Merge the components from the specified attribute in this
155           attribute.  This is needed when components of the same attribute
156           are created separately.  Merging is required by the field parsing.
157
158       Error handling
159
160       This class does not extend Mail::Reporter for obvious performance rea‐
161       sons: there is no logging or tracing available.
162
163       $obj->AUTOLOAD
164
165           See "Error handling" in Mail::Reporter
166
167       $obj->addReport(OBJECT)
168
169           See "Error handling" in Mail::Reporter
170
171       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
172
173       Mail::Message::Field::Attribute->defaultTrace([LEVEL]⎪[LOGLEVEL,
174       TRACELEVEL]⎪[LEVEL, CALLBACK])
175
176           See "Error handling" in Mail::Reporter
177
178       $obj->errors
179
180           See "Error handling" in Mail::Reporter
181
182       $obj->log([LEVEL [,STRINGS]])
183
184       Mail::Message::Field::Attribute->log([LEVEL [,STRINGS]])
185
186           See "Error handling" in Mail::Reporter
187
188       $obj->logPriority(LEVEL)
189
190       Mail::Message::Field::Attribute->logPriority(LEVEL)
191
192           See "Error handling" in Mail::Reporter
193
194       $obj->logSettings
195
196           See "Error handling" in Mail::Reporter
197
198       $obj->notImplemented
199
200           See "Error handling" in Mail::Reporter
201
202       $obj->report([LEVEL])
203
204           See "Error handling" in Mail::Reporter
205
206       $obj->reportAll([LEVEL])
207
208           See "Error handling" in Mail::Reporter
209
210       $obj->trace([LEVEL])
211
212           See "Error handling" in Mail::Reporter
213
214       $obj->warnings
215
216           See "Error handling" in Mail::Reporter
217
218       Cleanup
219
220       $obj->DESTROY
221
222           See "Cleanup" in Mail::Reporter
223
224       $obj->inGlobalDestruction
225
226           See "Cleanup" in Mail::Reporter
227

DIAGNOSTICS

229       Warning: Illegal character in parameter name '$name'
230
231       The specified parameter name contains characters which are not permit‐
232       ted by the RFCs.  You can better change the name into something which
233       is accepted, or risk applications to corrupt or ignore the message.
234
235       Error: Package $package does not implement $method.
236
237       Fatal error: the specific package (or one of its superclasses) does not
238       implement this method where it should. This message means that some
239       other related classes do implement this method however the class at
240       hand does not.  Probably you should investigate this and probably
241       inform the author of the package.
242
243       Error: Too late to merge: value already changed.
244

LICENSE

250       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
251       ChangeLog.
252
253       This program is free software; you can redistribute it and/or modify it
254       under the same terms as Perl itself.  See
255       http://www.perl.com/perl/misc/Artistic.html
256
257
258
259perl v5.8.8                       2007-03-25Mail::Message::Field::Attribute(3)