Mail::M...eldGroup(3)

📦

version 4.04 · 11 versions

💖 Mail::Message::Head::FieldGroup — a sub set of fields in a header 💖

okay so bestie, this is the manual page for Mail::Message::Head::FieldGroup (yes the title gets truncated to Mail::M...eldGroup(3) in the header, that's just how it renders, don't worry about it 💅). This page ships with the User Contributed Perl Documentation. Grab a strawberry drink 🍓 and let's get into it.

🌈 INHERITANCE 🌈

 Mail::Message::Head::FieldGroup
   is a Mail::Reporter

 Mail::Message::Head::FieldGroup is extended by
   Mail::Message::Head::ListGroup
   Mail::Message::Head::ResentGroup
   Mail::Message::Head::SpamGroup

so it is a Mail::Reporter, and it's the parent energy for three whole subclasses. main character behavior, honestly 👑

✨ SYNOPSIS ✨

Never instantiated directly.

literally that's it. you never new this one yourself, bestie. it's giving "abstract base class" and it's giving it hard. 🎀

🌸 DESCRIPTION 🌸

so here's the tea ☕: some fields in a mail header only make sense as a squad. like, a whole set of fields that represent one intermediate step while the message was being transported (that's a resent group, and it lives in Mail::Message::Head::ResentGroup). or fields that mailing list software tacked on (that's Mail::Message::Head::ListGroup). or fields that spam detection software added (that's Mail::Message::Head::SpamGroup). 🔥

each one of those sets of fields can be pulled out or added as a group, using objects that are all based on the implementation in this class. so this class is like... the blueprint. the group chat rules. the vibe. 🦋

Extends "DESCRIPTION" in Mail::Reporter.

💜 METHODS 💜

Extends "METHODS" in Mail::Reporter.

🧚 Constructors

Extends "Constructors" in Mail::Reporter.

$obj->clone() — makes a copy of this object. the collected fieldnames get copied, and so does the list type information. no deep copy for the header though — the header is only copied as a reference. so like, same header, new wrapper. iykyk ✨
$obj->from($head|$message) — creates a group of fields based on the $message you gave it, or the message $head. it might return one or more objects, and which one you get depends on the type of group. mailing list fields all get stored in one object, but resent and spam groups can show up more than once. one is not like the others, periodt 💅
$any->implementedTypes() — returns a list of strings with every possible return value that type() could give you. it's the full menu, bestie 📋
$class->new(@fields, %options) — constructs an object that maintains one set of header @fields. the @fields can be Mail::Message::Field objects, or they can be key-value pairs. the %options and the @fields (as key-value pairs) can be mixed together — they're told apart by their name, because fields always start with a capital letter. and heads up: the field objects must always come before the %options. improves the base, see "Constructors" in Mail::Reporter.

 -Option  --Default
  head      undef
  software  undef
  type      undef
  version   undef

head => $head — the $head object is where the grouped fields get stored. if you don't give it a header, a Mail::Message::Head::Partial gets created for you. but if you actually want to scan the fields that already exist in a header, use the from() method instead. 🙈
software => STRING — the name of the software that produced the fields.
type => STRING — the group name for the fields. often it's the same as the "software" option's STRING, or close to it.
version => STRING — the version number of the software that produced the fields.

💫 Attributes

Extends "Attributes" in Mail::Reporter.

🎀 The header

$obj->add( <$field, $value> | $object ) — adds a field to the header, via the field group. if the field group is already attached to a real message header, the field shows up in that header too, and it also gets registered in this set. if no header is defined, the field only exists internally. 🌸

» example: adding a field to a detached list group

my $this = Mail::Message::Head::ListGroup->new(...);
$this->add('List-Id' => 'mailbox');
$msg->addListGroup($this);
$msg->send;

» example: adding a field to an attached list group

my $lg = Mail::Message::Head::ListGroup->from($msg);
$lg->add('List-Id' => 'mailbox');

$obj->addFields( [$fieldnames] ) — adds some $fieldnames to the set. 🫶
$obj->attach($head) — adds a group of fields to a message $head. the fields get cloned(!) into the header, so that the field group object can be reused later. cloning, bestie, that's the whole point 🔥

» example: attaching a list group to a message

my $lg = Mail::Message::Head::ListGroup->new(...);
$lg->attach($msg->head);
$msg->head->addListGroup($lg);   # same

$msg->head->addSpamGroup($sg);   # also implemented with attach

$obj->delete() — removes all the header lines that are combined in this fields group, from the header. gone. deleted. blocked. 💀
$obj->fieldNames() — returns the names of the fields used in this group.
$obj->fields() — returns the fields that are defined for this group.
$obj->head() — returns the header object that includes these fields.

🌈 Access to the header

$obj->software() — returns the name of the software as defined in the headers. this might be slightly different from what type() returns, but usually it's not too different. cousins, basically 🧚
$obj->type() — returns an abstract name for the field group; i.e. which software is controlling it. "undef" comes back if the type isn't known. the valid names depend on the group type — check the applicable manual pages. you can get a list of all types with implementedTypes(). 👑
$obj->version() — returns the version number of the software used to produce the fields. some kinds of software leave a trace like that, other cases just return "undef". mystery vibes 🕵️

💅 Internals

$obj->collectFields( [$name] ) — scans the header for fields that are usually contained in a field group with the specified $name. for mailinglist groups you can not specify a $name: only one set of headers will be found, because all headers are considered to be produced by exactly one package of mailinglist software. one group, one package, no exceptions 💖

this method gets called automatically when a field group is constructed via from() on an existing header or message.

returned are the names of the list header fields found; in scalar context, you get the amount of fields. an empty list / zero means there was no group to be found. nada. zero. ghosted 👻

Please warn the author of MailBox if you see that to few or too many fields are included.

$obj->detected($type, $software, $version) — sets the values for the field group type, software, and version — possibly to "undef". yes, the typo "prossibly" in spirit, but the args are $type, $software, $version and that's that ✨

😭 Error handling

Extends "Error handling" in Mail::Reporter.

$obj->AUTOLOAD() — inherited, see "Error handling" in Mail::Reporter.
$obj->details() — produces information about the detected/created field group, which may help while debugging. you get a nicely formatted string back. pretty and useful, we love that 🎀
$obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter.
$obj->print( [$fh] ) — prints the group to the specified $fh. this is probably only useful for debugging purposes. the output defaults to the selected file handle. 🖨️

🧼 Cleanup

Extends "Cleanup" in Mail::Reporter.

$obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter.

💀 DIAGNOSTICS 💀

Error: class $package does not implement method $method. — fatal error, bestie, no cap. the specific $package (or one of its superclasses) does not implement this method where it should. this message means some other related classes do implement this method, but the class at hand does not. you should probably investigate this, and probably inform the author of the package. cast by notImplemented(). 😭

🔥 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. 💖

and that's the whole page, bestie!! this one came from perl version v5.42.0, dated 2026-02-05, and it's filed under Mail::M...eldGroup(3) in the manual. slay, go forth and group your fields 🌸🦋💅

📦 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