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

DIAGNOSTICS

192       Warning: Illegal character in parameter name '$name'
193           The specified parameter name contains characters which are not
194           permitted by the RFCs.  You can better change the name into
195           something which is accepted, or risk applications to corrupt or
196           ignore the message.
197
198       Error: Package $package does not implement $method.
199           Fatal error: the specific package (or one of its superclasses) does
200           not implement this method where it should. This message means that
201           some other related classes do implement this method however the
202           class at hand does not.  Probably you should investigate this and
203           probably inform the author of the package.
204
205       Error: Too late to merge: value already changed.
206

LICENSE

212       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
213       ChangeLog.
214
215       This program is free software; you can redistribute it and/or modify it
216       under the same terms as Perl itself.  See
217       http://www.perl.com/perl/misc/Artistic.html
218
219
220
221perl v5.12.3                      2011-01-26Mail::Message::Field::Attribute(3)