Mail::M...ttribute(3)

📦

version 4.04 · 11 versions

💖 Mail::M...ttribute(3) — bestie edition 💖

okay so this is the page for Mail::Message::Field::Attribute(3), straight out of the User Contributed Perl Documentation section. it's one attribute of a full field, and it's about to be your new obsession. let's go 🫶

✨ NAME ✨

Mail::Message::Field::Attribute — one attribute of a full field. that's it. that's the whole vibe. 💅

🌈 INHERITANCE 🌈

Mail::Message::Field::Attribute
  is a Mail::Reporter

so yeah, it's a Mail::Reporter girlie at heart. 💖

🌸 SYNOPSIS 🌸

here's the little taste test, copy it exactly bestie:

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

see how $filename is out here living its main character life? you can print its class, its utf-8 content, the exact same thing via value, the raw string as it appeared in the file, or dump it straight to a filehandle with print. iconic behaviour honestly. ✨

🦋 DESCRIPTION 🦋

so attributes inside MIME fields can get really complex, which means they can be slow and they consume a lot of memory. 😭 Mail::Message::Field::Fast and Mail::Message::Field::Flex simplify those attributes a whole lot, but — and this is the important part — that can result in erroneous behavior in rare cases. no cap.

and with the increase of non-western languages on the Internet, the need for the complex headers becomes more and more in demand. the girlies need proper unicode. 🌍

a Mail::Message::Field::Attribute can be found in any structured Mail::Message::Field::Full header field. that's the whole point of her existence.

extends "DESCRIPTION" in Mail::Reporter. 💜

👑 OVERLOADED 👑

overload: `""` stringification

returns the decoded content of the attribute. so when you just print her, you get the decoded goodness. slay.

overload: `cmp` string comparison

when the second argument is a field, then both the attribute name (case-sensitive!!) and the decoded value must be the same. otherwise, the value is compared. periodt. 💅

⭐ METHODS ⭐

extends "METHODS" in Mail::Reporter.

🎀 Constructors

extends "Constructors" in Mail::Reporter.

`$class->new( <$name, [$value] | STRING>, %options )`

create a new attribute $name with the optional $value. now listen, because this is the plot twist: 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. (name stays plain, always. she's lowkey minimalist like that.)

to speed things up, attributes are not derived from the Mail::Reporter base-class. improves base, see "Constructors" in Mail::Reporter.

here's the option lineup:

 -Option           --Default
  charset            'us-ascii'
  language           undef
  use_continuations  <C<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'). go look them up bestie, there's so many. 🌈
language => STRING — RFC2231 adds the possibility 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, so don't come for her about it. 🙈
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. so like, it's giving risk, but it's giving tidy too.

» 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

look at that output. filename*=iso-8859-15'nl-BE'Re%C7u. that's the encoded flex. 🔥

🧚 Attributes

extends "Attributes" in Mail::Reporter.

(yes bestie, that's genuinely all she wrote here. no extra methods hiding under this heading. the restraint!)

💜 Error handling

extends "Error handling" in Mail::Reporter.

$obj->AUTOLOAD() — inherited, see "Error handling" in Mail::Reporter
$obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter

🍓 Cleanup

extends "Cleanup" in Mail::Reporter.

$obj->DESTROY() — inherited, 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. that's the assignment. 😤

» 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. keep that in mind or get humbled. 💀
$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". she's flexible like that.
$obj->name() — returns the name of this attribute. short, sweet, iconic.
$obj->string() — when called in LIST context, the lines are returned to be post-processed one after the other. in SCALAR context, this returns the formatted attribute list. context matters bestie, always read the context. ✨
$obj->value( [STRING] ) — returns the value of this parameter, optionally after setting it first. getter and setter, dual threat. 💅

🌸 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. either way she ate.
$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. teamwork makes the dream work. 🫶

💀 DIAGNOSTICS 💀

Error: class $package does not implement method $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. cast by notImplemented()

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. cast by new()

⚠️ bestie, don't ignore this one. the RFCs will absolutely catch you lacking.

Error: too late to merge: value already changed.

cast by mergeComponent()

🦋 SEE ALSO 🦋

this module is part of Mail-Message version 4.04, built on February 04, 2026. website: http://perl.overmeer.net/CPAN/

💖 LICENSE 💖

for contributors see file ChangeLog.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so yes, you can share her, remix her, pass her around the group chat. 🫶

okay that's the whole page bestie, you're officially fluent 💅✨

sign-off time: this lovely thing came from perl v5.42.0, dated 2026-02-05, and yes the page title is Mail::M...ttribute(3) — she's so real for the abbreviation. mwah. 💖

📦 where this page comes from

fedora 44: perl-Mail-Message 4.04-1.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms