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