/usr/share/perl5/Mail/Message/Field/AddrGroup.pod is in libmail-box-perl 2.099-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | =head1 NAME
Mail::Message::Field::AddrGroup - A group of Mail::Message::Field::Address objects
=head1 INHERITANCE
Mail::Message::Field::AddrGroup
is a User::Identity::Collection::Emails
is a User::Identity::Collection
is a User::Identity::Item
=head1 SYNOPSIS
my $g = Mail::Message::Field::AddrGroup->new(name => 'name');
my $a = Mail::Message::Field::Address->new(...);
$g->addAddress($a);
my $f = Mail::Message::Field::Addresses->new;
$f->addGroup($g);
=head1 DESCRIPTION
An address group collects a set of e-mail addresses (in this case they
are L<Mail::Message::Field::Address|Mail::Message::Field::Address> objects).
=head1 OVERLOADED
=over 4
=item overload: B<@{}>
See L<User::Identity::Collection/"OVERLOADED">
=item overload: B<stringification>
Returns the L<string()|Mail::Message::Field::AddrGroup/"METHODS"> value.
=back
=head1 METHODS
=head2 Constructors
=over 4
=item $obj-E<gt>B<coerce>(OBJECT)
Coerce an OBJECT into a L<Mail::Message::Field::AddrGroup|Mail::Message::Field::AddrGroup>. Currently,
you can only coerce L<User::Identity::Collection::Emails|User::Identity::Collection::Emails> (which is
the base class for this one) into this one.
=item Mail::Message::Field::AddrGroup-E<gt>B<new>([NAME], OPTIONS)
See L<User::Identity::Collection::Emails/"Constructors">
=back
=head2 Attributes
=over 4
=item $obj-E<gt>B<description>
See L<User::Identity::Item/"Attributes">
=item $obj-E<gt>B<itemType>
See L<User::Identity::Collection/"Attributes">
=item $obj-E<gt>B<name>([NEWNAME])
See L<User::Identity::Item/"Attributes">
=item $obj-E<gt>B<roles>
See L<User::Identity::Collection/"Attributes">
=back
=head2 Collections
=over 4
=item $obj-E<gt>B<add>(COLLECTION, ROLE)
See L<User::Identity::Item/"Collections">
=item $obj-E<gt>B<addCollection>(OBJECT | ([TYPE], OPTIONS))
See L<User::Identity::Item/"Collections">
=item $obj-E<gt>B<collection>(NAME)
See L<User::Identity::Item/"Collections">
=item $obj-E<gt>B<parent>([PARENT])
See L<User::Identity::Item/"Collections">
=item $obj-E<gt>B<removeCollection>(OBJECT|NAME)
See L<User::Identity::Item/"Collections">
=item $obj-E<gt>B<type>
=item Mail::Message::Field::AddrGroup-E<gt>B<type>
See L<User::Identity::Item/"Collections">
=item $obj-E<gt>B<user>
See L<User::Identity::Item/"Collections">
=back
=head2 Maintaining roles
=over 4
=item $obj-E<gt>B<addRole>(ROLE| ( [NAME],OPTIONS ) | ARRAY-OF-OPTIONS)
See L<User::Identity::Collection/"Maintaining roles">
=item $obj-E<gt>B<removeRole>(ROLE|NAME)
See L<User::Identity::Collection/"Maintaining roles">
=item $obj-E<gt>B<renameRole>(ROLE|OLDNAME, NEWNAME)
See L<User::Identity::Collection/"Maintaining roles">
=item $obj-E<gt>B<sorted>
See L<User::Identity::Collection/"Maintaining roles">
=back
=head2 Searching
=over 4
=item $obj-E<gt>B<find>(NAME|CODE|undef)
See L<User::Identity::Collection/"Searching">
=back
=head2 Addresses
=over 4
=item $obj-E<gt>B<addAddress>(STRING|ADDRESS|OPTIONS)
Add one e-mail address to the list which is maintained in the group. This
is a wrapper around L<addRole()|User::Identity::Collection/"Maintaining roles"> adding flexibility on how addresses
are specified. An ADDRESS can be anything which is acceptable for
L<Mail::Message::Field::Address::coerce()|Mail::Message::Field::Address/"Constructors"> or a list of options which
will create such an object.
example: of adding an address to an address group
my @data = (full_name => "Myself", address => 'me@tux.org');
$group->addAddress(@data);
my $addr = Mail::Message::Field::Address->new(@data);
$group->addAddress(@data);
my $ma = Mail::Address->new(...);
$group->addAddress($ma);
=item $obj-E<gt>B<addresses>
Returns all addresses defined in this group. The addresses will be
ordered alphabetically to make automated testing possible: roles are
stored in a hash, so have an unpredictable order by default.
example: getting all addresses from a group
my @addrs = $group->addresses;
my @addrs = map { $_->address } $self->roles; #same
=back
=head2 Error handling
=over 4
=item $obj-E<gt>B<string>
Returns the address group as string. When no name is specified, it will
only be a comma separated list of addresses. With a name, the groups
name will be prepended and a semi-colon appended. When no addresses
where included and there is no name, then C<undef> is returned.
=back
=head1 DIAGNOSTICS
=over 4
=item Error: $object is not a collection.
The first argument is an object, but not of a class which extends
L<User::Identity::Collection|User::Identity::Collection>.
=item Error: Cannot coerce a $type into a Mail::Message::Field::AddrGroup
=item Error: Cannot create a $type to add this to my collection.
Some options are specified to create a $type object, which is native to
this collection. However, for some reason this failed.
=item Error: Cannot load collection module for $type ($class).
Either the specified $type does not exist, or that module named $class returns
compilation errors. If the type as specified in the warning is not
the name of a package, you specified a nickname which was not defined.
Maybe you forgot the 'require' the package which defines the nickname.
=item Error: Cannot rename $name into $newname: already exists
=item Error: Cannot rename $name into $newname: doesn't exist
=item Error: Creation of a collection via $class failed.
The $class did compile, but it was not possible to create an object
of that class using the options you specified.
=item Error: Don't know what type of collection you want to add.
If you add a collection, it must either by a collection object or a
list of options which can be used to create a collection object. In
the latter case, the type of collection must be specified.
=item Warning: No collection $name
The collection with $name does not exist and can not be created.
=item Error: Wrong type of role for $collection: requires a $expect but got a $type
Each $collection groups sets of roles of one specific type ($expect). You
cannot add objects of a different $type.
=back
=head1 SEE ALSO
This module is part of Mail-Box distribution version 2.099,
built on July 07, 2011. Website: F<http://perl.overmeer.net/mailbox/>
=head1 LICENSE
Copyrights 2001-2011 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 F<http://www.perl.com/perl/misc/Artistic.html>
|