NAME¶
Mail::Message::Field::Attribute - one attribute of a full field
INHERITANCE¶
Mail::Message::Field::Attribute
is a Mail::Reporter
SYNOPSIS¶
my $field = $msg->head->get('Content-Disposition') or return;
my $full = $field->study; # full understanding in unicode
my $filename = $full->attribute('filename') or return;
print ref $filename; # this class name
print $filename; # the attributes content in utf-8
print $filename->value; # same
print $filename->string; # print string as was found in the file
$filename->print(\*OUT); # print as was found in the file
DESCRIPTION¶
Attributes within MIME fields can be quite complex, and therefore be slow and
consumes a lot of memory. The Mail::Message::Field::Fast and
Mail::Message::Field::Flex simplify them the attributes a lot, which may
result in erroneous behavior in rare cases. With the increase of non-western
languages on Internet, the need for the complex headers becomes more and more
in demand.
A "Mail::Message::Field::Attribute" can be found in any structured
Mail::Message::Field::Full header field.
OVERLOADED¶
- overload: comparison()
- When the second argument is a field, then both attribute
name (case-sensitive) and the decoded value must be the same. Otherwise,
the value is compared.
- overload: stringification()
- Returns the decoded content of the attribute.
METHODS¶
Constructors¶
- Mail::Message::Field::Attribute->new((NAME,
[VALUE] | STRING), OPTIONS)
- Create a new attribute NAME with the optional VALUE. If no
VALUE is specified, the first argument of this method is inspected for an
equals sign '='. If that character is present, the argument is taken as
STRING, containing a preformatted attribute which is processed. Otherwise,
the argument is taken as name without VALUE: set the value later with
value().
Whether encoding takes place depends on the OPTIONS and the existence of
non-ascii characters in the VALUE. The NAME can only contain ascii
characters, hence is never encoded.
To speed things up, attributes are not derived from the Mail::Reporter
base-class.
-Option --Defined in --Default
charset 'us-ascii'
language undef
log Mail::Reporter 'WARNINGS'
trace Mail::Reporter 'WARNINGS'
use_continuations <true>
- charset => STRING
- The VALUE is translated from utf-8 (Perl internal) to this
character set, and the resulting string is encoded if required.
"us-ascii" is the normal encoding for e-mail. Valid character
sets can be found with Encode::encodings(':all').
- language => STRING
- RFC2231 adds the possiblity to specify a language with the
field. When no language is specified, none is included in the encoding.
Valid language names are defined by RFC2130. This module has only limited
support for this feature.
- log => LEVEL
- trace => LEVEL
- use_continuations => BOOLEAN
- Continuations are used to break-up long parameters into
pieces which are no longer than 76 characters. Encodings are specified in
RFC2231, but not supported by some Mail User Agents.
example:
my $fn = Mail::Message::Field::Attribute
->new(filename => 'xyz');
my $fattr = 'Mail::Message::Field::Attribute'; # abbrev
my $fn = $fattr->new
( filename => "Re\xC7u"
, charset => 'iso-8859-15'
, language => 'nl-BE'
);
print $fn;
# --> filename*=iso-8859-15'nl-BE'Re%C7u
Error handling¶
- $obj->AUTOLOAD()
- See "Error handling" in Mail::Reporter
- $obj->addReport(OBJECT)
- See "Error handling" in Mail::Reporter
- $obj->defaultTrace([LEVEL]|[LOGLEVEL,
TRACELEVEL]|[LEVEL, CALLBACK])
- Mail::Message::Field::Attribute->defaultTrace([LEVEL]|[LOGLEVEL,
TRACELEVEL]|[LEVEL, CALLBACK])
- See "Error handling" in Mail::Reporter
- $obj->errors()
- See "Error handling" in Mail::Reporter
- $obj->log([LEVEL [,STRINGS]])
- Mail::Message::Field::Attribute->log([LEVEL
[,STRINGS]])
- See "Error handling" in Mail::Reporter
- $obj->logPriority(LEVEL)
- Mail::Message::Field::Attribute->logPriority(LEVEL)
- See "Error handling" in Mail::Reporter
- $obj->logSettings()
- See "Error handling" in Mail::Reporter
- $obj->notImplemented()
- See "Error handling" in Mail::Reporter
- $obj->report([LEVEL])
- See "Error handling" in Mail::Reporter
- $obj->reportAll([LEVEL])
- See "Error handling" in Mail::Reporter
- $obj->trace([LEVEL])
- See "Error handling" in Mail::Reporter
- $obj->warnings()
- See "Error handling" in Mail::Reporter
Cleanup¶
- $obj->DESTROY()
- See "Cleanup" in Mail::Reporter
- $obj->inGlobalDestruction()
- See "Cleanup" in Mail::Reporter
The attribute¶
- $obj->addComponent(STRING)
- A component is a parameter as defined by RFC2045,
optionally using encoding or continuations as defined by RFC2231.
Components of an attribute are found when a field is being parsed. The
RFCs are very strict on valid characters, but we cannot be: you have to
accept what is coming in if you can.
example:
my $param = Mail::Message::Field::Attribute->new;
$param->addComponent("filename*=iso10646'nl-BE'%Re\47u");
- $obj->charset()
- Returns the character set which is used for this parameter.
If any component is added which contains character set information, this
is directly available. Be warned that a character-set is case
insensitive.
- $obj->language()
- Returns the language which is defined in the argument. If
no language is defined "undef" is returned, which should be
interpreted as "ANY"
- $obj->name()
- Returns the name of this attribute.
- $obj->string()
- Returns the parameter as reference to an array of lines.
When only one line is returned, it may be short enough to fit on the same
line with other components of the header field.
- $obj->value([STRING])
- Returns the value of this parameter, optionally after
setting it first.
Attribute encoding¶
- $obj->decode()
- Translate all known continuations into a value. The
produced value is returned and may be utf-8 encoded or a plain
string.
- $obj->encode()
Internals¶
- $obj->mergeComponent(ATTRIBUTE)
- Merge the components from the specified attribute into this
attribute. This is needed when components of the same attribute are
created separately. Merging is required by the field parsing.
DIAGNOSTICS¶
- Warning: Illegal character in parameter name '$name'
- The specified parameter name contains characters which are
not permitted by the RFCs. You can better change the name into something
which is accepted, or risk applications to corrupt or ignore the
message.
- Error: Package $package does not implement $method.
- Fatal error: the specific package (or one of its
superclasses) does not implement this method where it should. This message
means that some other related classes do implement this method however the
class at hand does not. Probably you should investigate this and probably
inform the author of the package.
- Error: Too late to merge: value already changed.
SEE ALSO¶
This module is part of Mail-Box distribution version 2.105, built on May 07,
2012. Website:
http://perl.overmeer.net/mailbox/
LICENSE¶
Copyrights 2001-2012 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself. See
http://www.perl.com/perl/misc/Artistic.html