Mail-Message-3.016/0000755000175000001440000000000014721576361014521 5ustar00markovusers00000000000000Mail-Message-3.016/lib/0000755000175000001440000000000014721576361015267 5ustar00markovusers00000000000000Mail-Message-3.016/lib/Mail/0000755000175000001440000000000014721576361016151 5ustar00markovusers00000000000000Mail-Message-3.016/lib/Mail/Message/0000755000175000001440000000000014721576361017535 5ustar00markovusers00000000000000Mail-Message-3.016/lib/Mail/Message/Field/0000755000175000001440000000000014721576361020560 5ustar00markovusers00000000000000Mail-Message-3.016/lib/Mail/Message/Field/Date.pm0000644000175000001440000000533514721576345022003 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::Date;{ our $VERSION = '3.016'; } use base 'Mail::Message::Field::Structured'; use warnings; use strict; use POSIX qw/mktime tzset/; my $dayname = qr/Mon|Tue|Wed|Thu|Fri|Sat|Sun/; my @months = qw/Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec/; my %monthnr; { my $i; $monthnr{$_} = ++$i for @months } my %tz = qw/EDT -0400 EST -0500 CDT -0500 CST -0600 MDT -0600 MST -0700 PDT -0700 PST -0800 UT +0000 GMT +0000/; sub parse($) { my ($self, $string) = @_; my ($dn, $d, $mon, $y, $h, $min, $s, $z) = $string =~ m/ ^ \s* (?: ($dayname) \s* \, \s* )? ( 0?[1-9] | [12][0-9] | 3[01] ) \s* # day \s+ ( [A-Z][a-z][a-z]|[0-9][0-9] ) \s+ # month ( (?: 19 | 20 | ) [0-9][0-9] ) \s+ # year ( [0-1]?[0-9] | 2[0-3] ) \s* # hour [:.] ( [0-5][0-9] ) \s* # minute (?: [:.] ( [0-5][0-9] ) )? \s+ # second ( [+-][0-9]{4} | [A-Z]+ )? # zone \s* /x or return undef; defined $dn or $dn = ''; $dn =~ s/\s+//g; $mon = $months[$mon-1] if $mon =~ /[0-9]+/; # Broken mail clients $y += 2000 if $y < 50; $y += 1900 if $y < 100; $z ||= '-0000'; $z = $tz{$z} || '-0000' if $z =~ m/[A-Z]/; $self->{MMFD_date} = sprintf "%s%s%02d %s %04d %02d:%02d:%02d %s" , $dn, (length $dn ? ', ' : ''), $d, $mon, $y, $h, $min, $s, $z; $self; } sub produceBody() { shift->{MMFD_date} } sub date() { shift->{MMFD_date} } #------------------------------------------ sub addAttribute($;@) { my $self = shift; $self->log(ERROR => 'No attributes for date fields.'); $self; } sub time() { my $date = shift->{MMFD_date}; my ($d, $mon, $y, $h, $min, $s, $z) = $date =~ m/^ (?:\w\w\w\,\s+)? (\d\d)\s+(\w+)\s+(\d\d\d\d) \s+ (\d\d)\:(\d\d)\:(\d\d) \s+ ([+-]\d\d\d\d)? \s*$ /x; my $oldtz = $ENV{TZ}; $ENV{TZ} = 'UTC'; tzset; my $timestamp = mktime $s, $min, $h, $d, $monthnr{$mon}-1, $y-1900; if(defined $oldtz) { $ENV{TZ} = $oldtz } else { delete $ENV{TZ} } tzset; $timestamp += ($1 eq '-' ? 1 : -1) * ($2*3600 + $3*60) if $z =~ m/^([+-])(\d\d)(\d\d)$/; $timestamp; } #------------------------------------------ 1; Mail-Message-3.016/lib/Mail/Message/Field/Unstructured.pod0000644000175000001440000003123714721576347024005 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Unstructured - smart unstructured field =head1 INHERITANCE Mail::Message::Field::Unstructured is a Mail::Message::Field::Full is a Mail::Message::Field is a Mail::Reporter =head1 SYNOPSIS my $f = Mail::Message::Field::Unstructured->new('Comments', 'hi!'); =head1 DESCRIPTION Unstructured fields do contain information which is not restricted in any way. RFC2822 defines some unstructured fields, but by default all unknown fields are unstructured as well. Things like attributes and comments have no meaning for unstructured fields, but encoding does. Extends L<"DESCRIPTION" in Mail::Message::Field::Full|Mail::Message::Field::Full/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in Mail::Message::Field::Full|Mail::Message::Field::Full/"OVERLOADED">. =over 4 =item overload: B<""> Inherited, see L =item overload: B<0+> Inherited, see L =item overload: B<<=>> Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =back =head1 METHODS Extends L<"METHODS" in Mail::Message::Field::Full|Mail::Message::Field::Full/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Constructors">. =over 4 =item $obj-EB() Inherited, see L =item Mail::Message::Field::Unstructured-EB($field, %options) Inherited, see L =item Mail::Message::Field::Unstructured-EB($data) When the $data is specified as single line, the content part is considered to be correcly (character) encoded and escaped. Typically, it is a line as read from file. The folding of the line is kept as is. In case more than one argument is provided, the second is considered the BODY. Attributes and other special things are not defined for unstructured fields, and therefore not valid options. The BODY can be a single string, a single OBJECT, or an array of OBJECTS. The objects are stringified (into a comma separated list). Each BODY element is interpreted with the specified encoding. When the BODY is empty, the construction of the object fails: C is returned. -Option --Defined in --Default charset Mail::Message::Field::Full undef encoding Mail::Message::Field::Full 'q' force Mail::Message::Field::Full false language Mail::Message::Field::Full undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' =over 2 =item charset => STRING =item encoding => 'q'|'Q'|'b'|'B' =item force => BOOLEAN =item language => STRING =item log => LEVEL =item trace => LEVEL =back example: my $s = Mail::Message::Field::Unstructured->new('Comment', 'Hi!'); # Use autodetect my $s = Mail::Message::Field::Full->new('Comment', 'Hi!'); my $s = Mail::Message::Field::Full->new('Comment: Hi!'); =back =head2 The field Extends L<"The field" in Mail::Message::Field::Full|Mail::Message::Field::Full/"The field">. =over 4 =item $obj-EB() =item Mail::Message::Field::Unstructured-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$fh] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$wrap] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Access to the name Extends L<"Access to the name" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Access to the name">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =back =head2 Access to the body Extends L<"Access to the body" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Access to the body">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$body] ) Inherited, see L =item $obj-EB( [STRING] ) =item Mail::Message::Field::Unstructured-EB( [STRING] ) Inherited, see L =item $obj-EB( [$body, [$wrap]] ) Inherited, see L =back =head2 Access to the content Extends L<"Access to the content" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Access to the content">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB( $name, [$value] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Unstructured-EB(STRING, %options) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Unstructured-EB(STRING, %options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$time] ) =item Mail::Message::Field::Unstructured-EB( [$time] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Other methods Extends L<"Other methods" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Other methods">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Unstructured-EB(STRING) Inherited, see L =back =head2 Internals Extends L<"Internals" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Internals">. =over 4 =item $obj-EB( $line | <$name,<$body|$objects>> ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Unstructured-EB(STRING, %options) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING, %options) Inherited, see L =item $obj-EB( $name, $body, [$maxchars] ) =item Mail::Message::Field::Unstructured-EB( $name, $body, [$maxchars] ) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING|ARRAY|$objects) Inherited, see L =item $obj-EB(STRING) Inherited, see L =back =head2 Parsing Extends L<"Parsing" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Parsing">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Unstructured-EB(STRING) Inherited, see L =item $obj-EB(STRING) Inherited, see L =item $obj-EB(STRING) =item Mail::Message::Field::Unstructured-EB(STRING) Inherited, see L =item $obj-EB(STRING) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Error handling Extends L<"Error handling" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Error handling">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB($object) Inherited, see L =item $obj-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) =item Mail::Message::Field::Unstructured-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level, [$strings]] ) =item Mail::Message::Field::Unstructured-EB( [$level, [$strings]] ) Inherited, see L =item $obj-EB($level) =item Mail::Message::Field::Unstructured-EB($level) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Cleanup Extends L<"Cleanup" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Cleanup">. =over 4 =item $obj-EB() Inherited, see L =back =head1 DETAILS Extends L<"DETAILS" in Mail::Message::Field::Full|Mail::Message::Field::Full/"DETAILS">. =head1 DIAGNOSTICS =over 4 =item Warning: Field content is not numerical: $content The numeric value of a field is requested (for instance the C or C fields should be numerical), however the data contains weird characters. =item Error: Field name too long (max $length), in '$name' It is not specified in the RFCs how long a field name can be, but at least it should be a few characters shorter than the line wrap. =item Warning: Illegal character in charset '$charset' The field is created with an utf8 string which only contains data from the specified character set. However, that character set can never be a valid name because it contains characters which are not permitted. =item Warning: Illegal character in field name $name A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. =item Warning: Illegal character in language '$lang' The field is created with data which is specified to be in a certain language, however, the name of the language cannot be valid: it contains characters which are not permitted by the RFCs. =item Warning: Illegal encoding '$encoding', used 'q' The RFCs only permit base64 (C or C) or quoted-printable (C or C) encoding. Other than these four options are illegal. =item 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. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/URIs.pod0000644000175000001440000003266714721576347022130 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::URIs - message header field with uris =head1 INHERITANCE Mail::Message::Field::URIs is a Mail::Message::Field::Structured is a Mail::Message::Field::Full is a Mail::Message::Field is a Mail::Reporter =head1 SYNOPSIS my $f = Mail::Message::Field->new('List-Post' => 'http://x.org/'); my $g = Mail::Message::Field->new('List-Post'); $g->addURI('http://x.org'); my $uri = URI->new(...); $g->addURI($uri); my @uris = $g->URIs; =head1 DESCRIPTION More recent RFCs prefer uri field notation over the various differentiated syntaxes. Especially the mailing-list RFCs use these fields all the time. This class can maintain these fields. Extends L<"DESCRIPTION" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"OVERLOADED">. =over 4 =item overload: B<""> Inherited, see L =item overload: B<0+> Inherited, see L =item overload: B<<=>> Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =back =head1 METHODS Extends L<"METHODS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Constructors">. =over 4 =item $obj-EB() Inherited, see L =item Mail::Message::Field::URIs-EB($field, %options) Inherited, see L =item Mail::Message::Field::URIs-EB($data) -Option --Defined in --Default attributes Mail::Message::Field::Structured charset Mail::Message::Field::Full undef datum Mail::Message::Field::Structured undef encoding Mail::Message::Field::Full 'q' force Mail::Message::Field::Full false language Mail::Message::Field::Full undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' =over 2 =item attributes => ATTRS =item charset => STRING =item datum => STRING =item encoding => 'q'|'Q'|'b'|'B' =item force => BOOLEAN =item language => STRING =item log => LEVEL =item trace => LEVEL =back example: my $mmfu = 'Mail::Message::Field::URIs; my $f = $mmfu->new('List-Post' => 'mailto:x@y.com'); my $f = $mmfu->new('List-Post' => ''); my $f = $mmfu->new('List-Post: '); my $f = $mmfu->new('List-Post' => [ $uri, 'http://x.org' ]); =back =head2 The field Extends L<"The field" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"The field">. =over 4 =item $obj-EB() =item Mail::Message::Field::URIs-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$fh] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$wrap] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Access to the name Extends L<"Access to the name" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the name">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =back =head2 Access to the body Extends L<"Access to the body" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the body">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$body] ) Inherited, see L =item $obj-EB( [STRING] ) =item Mail::Message::Field::URIs-EB( [STRING] ) Inherited, see L =item $obj-EB( [$body, [$wrap]] ) Inherited, see L =back =head2 Access to the content Extends L<"Access to the content" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the content">. =over 4 =item $obj-EB() Returns a list with all URIs defined by the field. Mind the lower-case 's' at the enc of the name. example: my @uris = $field->URIs; =item $obj-EB(...) Attributes are not supported for URI fields. =item $obj-EB($uri) Add an $uri to the field. The $uri can be specified as URI object or as string which will be turned into an $uri object. The added $uri is returned. example: adding an URI to an URI field my $f = Mail::Message::Field::URI->new('List-Post'); my $uri = URI->new("http://x.org"); $f->addURI($uri); $f->addURI("http://y.org"); # simpler $f->addURI("//y.org", "http"); =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( $object||<$name,$value,%options> ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::URIs-EB(STRING, %options) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::URIs-EB(STRING, %options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$time] ) =item Mail::Message::Field::URIs-EB( [$time] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Other methods Extends L<"Other methods" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Other methods">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::URIs-EB(STRING) Inherited, see L =back =head2 Internals Extends L<"Internals" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Internals">. =over 4 =item $obj-EB( $line | <$name,<$body|$objects>> ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::URIs-EB(STRING, %options) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING, %options) Inherited, see L =item $obj-EB( $name, $body, [$maxchars] ) =item Mail::Message::Field::URIs-EB( $name, $body, [$maxchars] ) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING|ARRAY|$objects) Inherited, see L =item $obj-EB(STRING) Inherited, see L =back =head2 Parsing Extends L<"Parsing" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Parsing">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::URIs-EB(STRING) Inherited, see L =item $obj-EB(STRING) Inherited, see L =item $obj-EB(STRING) =item Mail::Message::Field::URIs-EB(STRING) Inherited, see L =item $obj-EB( [$value] ) Inherited, see L =item $obj-EB(STRING) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Error handling Extends L<"Error handling" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Error handling">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB($object) Inherited, see L =item $obj-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) =item Mail::Message::Field::URIs-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level, [$strings]] ) =item Mail::Message::Field::URIs-EB( [$level, [$strings]] ) Inherited, see L =item $obj-EB($level) =item Mail::Message::Field::URIs-EB($level) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Cleanup Extends L<"Cleanup" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Cleanup">. =over 4 =item $obj-EB() Inherited, see L =back =head1 DETAILS Extends L<"DETAILS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DETAILS">. =head1 DIAGNOSTICS =over 4 =item Warning: Field content is not numerical: $content The numeric value of a field is requested (for instance the C or C fields should be numerical), however the data contains weird characters. =item Error: Field name too long (max $length), in '$name' It is not specified in the RFCs how long a field name can be, but at least it should be a few characters shorter than the line wrap. =item Warning: Illegal character in charset '$charset' The field is created with an utf8 string which only contains data from the specified character set. However, that character set can never be a valid name because it contains characters which are not permitted. =item Warning: Illegal character in field name $name A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. =item Warning: Illegal character in language '$lang' The field is created with data which is specified to be in a certain language, however, the name of the language cannot be valid: it contains characters which are not permitted by the RFCs. =item Warning: Illegal encoding '$encoding', used 'q' The RFCs only permit base64 (C or C) or quoted-printable (C or C) encoding. Other than these four options are illegal. =item Error: No attributes for URI fields. Is is not possible to add attributes to URI fields: it is not permitted by the RFCs. =item 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. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/AddrGroup.pm0000644000175000001440000000325014721576345023007 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::AddrGroup;{ our $VERSION = '3.016'; } use base 'User::Identity::Collection::Emails'; use strict; use warnings; use overload '""' => 'string'; #------------------------------------------ sub string() { my $self = shift; my $name = $self->name; my @addr = sort map $_->string, $self->addresses; local $" = ', '; length $name ? "$name: @addr;" : @addr ? "@addr" : ''; } #------------------------------------------ sub coerce($@) { my ($class, $addr, %args) = @_; return () unless defined $addr; if(ref $addr) { return $addr if $addr->isa($class); return bless $addr, $class if $addr->isa('User::Identity::Collection::Emails'); } $class->log(ERROR => "Cannot coerce a ".(ref($addr)|'string'). " into a $class"); (); } #------------------------------------------ sub addAddress(@) { my $self = shift; my $addr = @_ > 1 ? Mail::Message::Field::Address->new(@_) : !$_[0] ? return () : Mail::Message::Field::Address->coerce(shift); $self->addRole($addr); $addr; } # roles are stored in a hash, so produce sub addresses() { shift->roles } #------------------------------------------ 1; Mail-Message-3.016/lib/Mail/Message/Field/Full.pm0000644000175000001440000002651414721576345022032 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::Full;{ our $VERSION = '3.016'; } use base 'Mail::Message::Field'; use strict; use warnings; use utf8; use Encode (); use MIME::QuotedPrint (); use Storable 'dclone'; use Mail::Message::Field::Addresses; use Mail::Message::Field::AuthResults; #use Mail::Message::Field::AuthRecChain; use Mail::Message::Field::Date; use Mail::Message::Field::DKIM; use Mail::Message::Field::Structured; use Mail::Message::Field::Unstructured; use Mail::Message::Field::URIs; my $atext = q[a-zA-Z0-9!#\$%&'*+\-\/=?^_`{|}~]; # from RFC5322 my $utf8_atext = q[\p{Alnum}!#\$%&'*+\-\/=?^_`{|}~]; # from RFC5335 my $atext_ill = q/\[\]/; # illegal, but still used (esp spam) use overload '""' => sub { shift->decodedBody }; #------------------------------------------ my %implementation; BEGIN { $implementation{$_} = 'Addresses' for qw/from to sender cc bcc reply-to envelope-to resent-from resent-to resent-cc resent-bcc resent-reply-to resent-sender x-beenthere errors-to mail-follow-up x-loop delivered-to original-sender x-original-sender/; $implementation{$_} = 'URIs' for qw/list-help list-post list-subscribe list-unsubscribe list-archive list-owner/; $implementation{$_} = 'Structured' for qw/content-disposition content-type content-id/; $implementation{$_} = 'Date' for qw/date resent-date/; $implementation{$_} = 'AuthResults' for qw/authentication-results/; $implementation{$_} = 'DKIM' for qw/dkim-signature/; # $implementation{$_} = 'AuthRecChain' # for qw/arc-authentication-results arc-message-signature arc-seal/; } sub new($;$$@) { my $class = shift; my $name = shift; my $body = @_ % 2 ? shift : undef; my %args = @_; $body = delete $args{body} if defined $args{body}; unless(defined $body) { (my $n, $body) = split /\s*\:\s*/s, $name, 2; $name = $n if defined $body; } return $class->SUPER::new(%args, name => $name, body => $body) if $class ne __PACKAGE__; # Look for best class to suit this field my $myclass = 'Mail::Message::Field::' . ($implementation{lc $name} || 'Unstructured'); $myclass->SUPER::new(%args, name => $name, body => $body); } sub init($) { my ($self, $args) = @_; $self->SUPER::init($args); $self->{MMFF_name} = $args->{name}; my $body = $args->{body}; if(!defined $body || !length $body || ref $body) { ; } # no body yet elsif(index($body, "\n") >= 0) { $self->foldedBody($body) } # body is already folded else { $self->unfoldedBody($body) } # body must be folded $self; } sub clone() { dclone(shift) } sub name() { lc shift->{MMFF_name}} sub Name() { shift->{MMFF_name}} sub folded() { my $self = shift; return $self->{MMFF_name}.':'.$self->foldedBody unless wantarray; my @lines = $self->foldedBody; my $first = $self->{MMFF_name}. ':'. shift @lines; ($first, @lines); } sub unfoldedBody($;$) { my ($self, $body) = (shift, shift); if(defined $body) { $self->foldedBody(scalar $self->fold($self->{MMFF_name}, $body)); return $body; } $body = $self->foldedBody; for($body) { s/\r?\n(\s)/$1/g; s/\r?\n/ /g; s/^\s+//; s/\s+$//; } $body; } sub foldedBody($) { my ($self, $body) = @_; if(@_==2) { $self->parse($body); $body =~ s/^\s*/ /m; $self->{MMFF_body} = $body; } elsif(defined($body = $self->{MMFF_body})) { ; } else { # Create a new folded body from the parts. $self->{MMFF_body} = $body = $self->fold($self->{MMFF_name}, $self->produceBody); } wantarray ? (split /^/, $body) : $body; } #------------------------------------------ sub from($@) { my ($class, $field) = (shift, shift); defined $field ? $class->new($field->Name, $field->foldedBody, @_) : (); } #------------------------------------------ sub decodedBody() { my $self = shift; $self->decode($self->unfoldedBody, @_); } #------------------------------------------ sub createComment($@) { my ($thing, $comment) = (shift, shift); $comment = $thing->encode($comment, @_) if @_; # encoding required... # Correct dangling parenthesis local $_ = $comment; # work with a copy s#\\[()]#xx#g; # remove escaped parens s#[^()]#x#g; # remove other chars while( s#\(([^()]*)\)#x$1x# ) {;} # remove pairs of parens substr($comment, CORE::length($_), 0, '\\') while s#[()][^()]*$##; # add escape before remaining parens $comment =~ s#\\+$##; # backslash at end confuses "($comment)"; } sub createPhrase($) { my $self = shift; local $_ = shift; # I do not case whether it gets a but sloppy in the header string, # as long as it is functionally correct: no folding inside phrase # quotes. return $_ = $self->encode($_, @_, force => 1) if length $_ > 50; $_ = $self->encode($_, @_) if @_; # encoding required... if( m/[^$atext]/ ) { s#\\#\\\\#g; s#"#\\"#g; $_ = qq["$_"]; } $_; } sub beautify() { shift } #------------------------------------------ sub _mime_word($$) { "$_[0]$_[1]?=" } sub _encode_b($) { MIME::Base64::encode_base64(shift, '') } sub _encode_q($) # RFC2047 sections 4.2 and 5 { my $chunk = shift; $chunk =~ s#([^a-zA-Z0-9!*+/=_ -])#sprintf "=%02X", ord $1#ge; $chunk =~ s#([_\?,"])#sprintf "=%02X", ord $1#ge; $chunk =~ s/ /_/g; # special case for =? ?= use $chunk; } sub encode($@) { my ($self, $utf8, %args) = @_; my ($charset, $lang, $encoding); if($charset = $args{charset}) { $self->log(WARNING => "Illegal character in charset '$charset'") if $charset =~ m/[\x00-\ ()<>@,;:"\/[\]?.=\\]/; } else { $charset = $utf8 =~ /\P{ASCII}/ ? 'utf8' : 'us-ascii'; } if($lang = $args{language}) { $self->log(WARNING => "Illegal character in language '$lang'") if $lang =~ m/[\x00-\ ()<>@,;:"\/[\]?.=\\]/; } if($encoding = $args{encoding}) { unless($encoding =~ m/^[bBqQ]$/ ) { $self->log(WARNING => "Illegal encoding '$encoding', used 'q'"); $encoding = 'q'; } } else { $encoding = 'q' } my $name = $args{name}; my $lname = defined $name ? length($name)+1 : 0; return $utf8 if lc($encoding) eq 'q' && length $utf8 < 70 && ($utf8 =~ m/\A[\p{IsASCII}]+\z/ms && !$args{force}); my $pre = '=?'. $charset. ($lang ? '*'.$lang : '') .'?'.$encoding.'?'; my @result; if(lc($encoding) eq 'q') { my $chunk = ''; my $llen = 73 - length($pre) - $lname; while(length(my $chr = substr($utf8, 0, 1, ''))) { $chr = _encode_q Encode::encode($charset, $chr, 0); if(bytes::length($chunk) + bytes::length($chr) > $llen) { push @result, _mime_word($pre, $chunk); $chunk = ''; $llen = 73 - length $pre; } $chunk .= $chr; } push @result, _mime_word($pre, $chunk) if length($chunk); } else { my $chunk = ''; my $llen = int((73 - length($pre) - $lname) / 4) * 3; while(length(my $chr = substr($utf8, 0, 1, ''))) { my $chr = Encode::encode($charset, $chr, 0); if(bytes::length($chunk) + bytes::length($chr) > $llen) { push @result, _mime_word($pre, _encode_b($chunk)); $chunk = ''; $llen = int((73 - length $pre) / 4) * 3; } $chunk .= $chr; } push @result, _mime_word($pre, _encode_b($chunk)) if length $chunk; } join ' ', @result; } sub _decoder($$$) { my ($charset, $encoding, $encoded) = @_; $charset =~ s/\*[^*]+$//; # language component not used my $to_utf8 = Encode::find_encoding($charset || 'us-ascii'); $to_utf8 or return $encoded; my $decoded; if($encoding !~ /\S/) { $decoded = $encoded; } elsif(lc($encoding) eq 'q') { # Quoted-printable encoded $encoded =~ s/_/ /g; # specific to mime-fields $decoded = MIME::QuotedPrint::decode_qp($encoded); } elsif(lc($encoding) eq 'b') { # Base64 encoded require MIME::Base64; $decoded = MIME::Base64::decode_base64($encoded); } else { # unknown encodings ignored return $encoded; } $to_utf8->decode($decoded, Encode::FB_DEFAULT); # error-chars -> '?' } sub decode($@) { my $thing = shift; my @encoded = split /(\=\?[^?\s]*\?[bqBQ]?\?[^?]*\?\=)/, shift; @encoded or return ''; my %args = @_; my $is_text = defined $args{is_text} ? $args{is_text} : 1; my @decoded = shift @encoded; while(@encoded) { shift(@encoded) =~ /\=\?([^?\s]*)\?([^?\s]*)\?([^?]*)\?\=/; push @decoded, _decoder $1, $2, $3; @encoded or last; # in text, blanks between encoding must be removed, but otherwise kept if($is_text && $encoded[0] !~ m/\S/) { shift @encoded } else { push @decoded, shift @encoded } } join '', @decoded; } #------------------------------------------ sub parse($) { shift } sub consumePhrase($) { my ($thing, $string) = @_; my $phrase; if($string =~ s/^\s*\" ((?:[^"\r\n\\]*|\\.)*) (?:\"|\s*$)//x ) { ($phrase = $1) =~ s/\\\"/"/g; } elsif($string =~ s/^\s*((?:\=\?.*?\?\=|[${utf8_atext}${atext_ill}\ \t.])+)//o ) { ($phrase = $1) =~ s/\s+$//; CORE::length($phrase) or undef $phrase; } defined $phrase ? ($thing->decode($phrase), $string) : (undef, $string); } sub consumeComment($) { my ($thing, $string) = @_; # Backslashes are officially not permitted in comments, but not everyone # knows that. Nested parens are supported. return (undef, $string) unless $string =~ s/^\s* \( ((?:\\.|[^)])*) (?:\)|$) //x; # allow unterminated comments my $comment = $1; # Continue consuming characters until we have balanced parens, for # nested comments which are permitted. while(1) { (my $count = $comment) =~ s/\\./xx/g; last if +( $count =~ tr/(// ) == ( $count =~ tr/)// ); last if $string !~ s/^((?:\\.|[^)])*) \)//x; # cannot satisfy $comment .= ')'.$1; } for($comment) { s/^\s+//; s/\s+$//; s/\\ ( [()] )/$1/gx; # Remove backslashes before nested comment. } ($comment, $string); } sub consumeDotAtom($) { my ($self, $string) = @_; my ($atom, $comment); while(1) { (my $c, $string) = $self->consumeComment($string); if(defined $c) { $comment .= $c; next } last unless $string =~ s/^\s*([$atext]+(?:\.[$atext]+)*)//o; $atom .= $1; } ($atom, $string, $comment); } sub produceBody() { $_[0]->{MMFF_body} } #------------------------------------------ 1; Mail-Message-3.016/lib/Mail/Message/Field/AddrGroup.pod0000644000175000001440000001714314721576347023165 0ustar00markovusers00000000000000=encoding utf8 =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 objects). Extends L<"DESCRIPTION" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"OVERLOADED">. =over 4 =item overload: B<@{}> Inherited, see L =item overload: B Returns the L value. =item overload: B Inherited, see L =back =head1 METHODS Extends L<"METHODS" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"METHODS">. =over 4 =item $obj-EB() 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 is returned. =back =head2 Constructors Extends L<"Constructors" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"Constructors">. =over 4 =item $obj-EB($object) Coerce an $object into a L. Currently, you can only coerce L (which is the base class for this one) into this one. =item Mail::Message::Field::AddrGroup-EB( [$name], %options ) Inherited, see L =back =head2 Attributes Extends L<"Attributes" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"Attributes">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$newname] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Collections Extends L<"Collections" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"Collections">. =over 4 =item $obj-EB($collection, $role) Inherited, see L =item $obj-EB( $object | <[$type], %options> ) Inherited, see L =item $obj-EB($name) Inherited, see L =item $obj-EB( [$parent] ) Inherited, see L =item $obj-EB($object|$name) Inherited, see L =item $obj-EB() =item Mail::Message::Field::AddrGroup-EB() Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Maintaining roles Extends L<"Maintaining roles" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"Maintaining roles">. =over 4 =item $obj-EB($role| <[$name],%options> | ARRAY) Inherited, see L =item $obj-EB($role|$name) Inherited, see L =item $obj-EB( <$role|$oldname>, $newname ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Searching Extends L<"Searching" in User::Identity::Collection::Emails|User::Identity::Collection::Emails/"Searching">. =over 4 =item $obj-EB($name|CODE|undef) Inherited, see L =back =head2 Addresses =over 4 =item $obj-EB(STRING|$address|%options) Add one e-mail address to the list which is maintained in the group. This is a wrapper around L adding flexibility on how addresses are specified. An $address can be anything which is acceptable for L 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-EB() 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 =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. =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-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/Attribute.pod0000644000175000001440000002061514721576347023237 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Attribute - one attribute of a full field =head1 INHERITANCE Mail::Message::Field::Attribute is a Mail::Reporter =head1 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 =head1 DESCRIPTION Attributes within MIME fields can be quite complex, and therefore be slow and consumes a lot of memory. The L and L 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 C can be found in any structured L header field. Extends L<"DESCRIPTION" in Mail::Reporter|Mail::Reporter/"DESCRIPTION">. =head1 OVERLOADED =over 4 =item overload: B 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. =item overload: B Returns the decoded content of the attribute. =back =head1 METHODS Extends L<"METHODS" in Mail::Reporter|Mail::Reporter/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Reporter|Mail::Reporter/"Constructors">. =over 4 =item Mail::Message::Field::Attribute-EB( <$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 C<'='>. 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 L base-class. -Option --Defined in --Default charset 'us-ascii' language undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' use_continuations =over 2 =item charset => STRING The $value is translated from utf-8 (Perl internal) to this character set, and the resulting string is encoded if required. C is the normal encoding for e-mail. Valid character sets can be found with Encode::encodings(':all'). =item 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. =item log => LEVEL =item trace => LEVEL =item 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. =back 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 =back =head2 Error handling Extends L<"Error handling" in Mail::Reporter|Mail::Reporter/"Error handling">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB($object) Inherited, see L =item $obj-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) =item Mail::Message::Field::Attribute-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level, [$strings]] ) =item Mail::Message::Field::Attribute-EB( [$level, [$strings]] ) Inherited, see L =item $obj-EB($level) =item Mail::Message::Field::Attribute-EB($level) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Cleanup Extends L<"Cleanup" in Mail::Reporter|Mail::Reporter/"Cleanup">. =over 4 =item $obj-EB() Inherited, see L =back =head2 The attribute =over 4 =item $obj-EB(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"); =item $obj-EB() 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. =item $obj-EB() Returns the language which is defined in the argument. If no language is defined C is returned, which should be interpreted as "ANY" =item $obj-EB() Returns the name of this attribute. =item $obj-EB() 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. =item $obj-EB( [STRING] ) Returns the value of this parameter, optionally after setting it first. =back =head2 Attribute encoding =over 4 =item $obj-EB() Translate all known continuations into a value. The produced value is returned and may be utf-8 encoded or a plain string. =item $obj-EB() =back =head2 Internals =over 4 =item $obj-EB($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. =back =head1 DIAGNOSTICS =over 4 =item 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. =item 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. =item Error: Too late to merge: value already changed. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/Address.pod0000644000175000001440000001534214721576347022662 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Address - One e-mail address =head1 INHERITANCE Mail::Message::Field::Address is a Mail::Identity is a User::Identity::Item =head1 SYNOPSIS my $addr = Mail::Message::Field::Address->new(...); my $ui = User::Identity->new(...); my $addr = Mail::Message::Field::Address->coerce($ui); my $mi = Mail::Identity->new(...); my $addr = Mail::Message::Field::Address->coerce($mi); print $addr->address; print $addr->fullName; # possibly unicode! print $addr->domain; =head1 DESCRIPTION Many header fields can contain e-mail addresses. Each e-mail address can be represented by an object of this class. These objects will handle interpretation and character set encoding and decoding for you. Extends L<"DESCRIPTION" in Mail::Identity|Mail::Identity/"DESCRIPTION">. =head1 OVERLOADED =over 4 =item overload: B The object used as boolean will always return C =item overload: B Two address objects are the same when their email addresses are the same. =item overload: B When the object is used in string context, it will return the encoded representation of the e-mail address, just like L does. =back =head1 METHODS Extends L<"METHODS" in Mail::Identity|Mail::Identity/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Identity|Mail::Identity/"Constructors">. =over 4 =item $obj-EB( , %options ) Try to coerce the $object into a C. In case of a STRING, it is interpreted as an email address. The %options are passed to the object creation, and overrule the values found in the $object. The result may be C or a newly created object. If the $object is already of the correct type, it is returned unmodified. The $object may currently be a L, a L, or a L. In case of the latter, one of the user's addresses is chosen at random. =item Mail::Message::Field::Address-EB( [$name], %options ) Inherited, see L =item $obj-EB(STRING) Parse the string for an address. You never know whether one or more addresses are specified on a line (often applications are wrong), therefore, the STRING is first parsed for as many addresses as possible and then the one is taken at random. =back =head2 Attributes Extends L<"Attributes" in Mail::Identity|Mail::Identity/"Attributes">. =over 4 =item $obj-EB
() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$newname] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Collections Extends L<"Collections" in Mail::Identity|Mail::Identity/"Collections">. =over 4 =item $obj-EB($collection, $role) Inherited, see L =item $obj-EB( $object | <[$type], %options> ) Inherited, see L =item $obj-EB($name) Inherited, see L =item $obj-EB( [$parent] ) Inherited, see L =item $obj-EB($object|$name) Inherited, see L =item $obj-EB() =item Mail::Message::Field::Address-EB() Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Searching Extends L<"Searching" in Mail::Identity|Mail::Identity/"Searching">. =over 4 =item $obj-EB($collection, $role) Inherited, see L =back =head2 Accessors =over 4 =item $obj-EB() Character-set encoding, like 'q' and 'b', to be used when non-ascii characters are to be transmitted. =back =head2 Access to the content =over 4 =item $obj-EB() Returns an RFC compliant e-mail address, which will have character set encoding if needed. The objects are also overloaded to call this method in string context. example: print $address->string; print $address; # via overloading =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. =item Error: Cannot coerce a $type into a Mail::Message::Field::Address When addresses are specified to be included in header fields, they may be coerced into L objects first. What you specify is not accepted as address specification. This may be an internal error. =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: 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. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/DKIM.pm0000644000175000001440000000400414721576345021642 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::DKIM;{ our $VERSION = '3.016'; } use base 'Mail::Message::Field::Structured'; use warnings; use strict; use URI; sub init($) { my ($self, $args) = @_; $self->{MMFD_tags} = { v => 1, a => 'rsa-sha256' }; $self->SUPER::init($args); } sub parse($) { my ($self, $string) = @_; my $tags = $self->{MMFD_tags}; foreach (split /\;/, $string) { m/^\s*([a-z][a-z0-9_]*)\s*\=\s*([\s\x21-\x7E]+?)\s*$/is or next; # tag-values stay unparsed (for now) $self->addTag($1, $2); } (undef, $string) = $self->consumeComment($string); $self; } sub produceBody() { my $self = shift; } #------------------------------------------ sub addAttribute($;@) { my $self = shift; $self->log(ERROR => 'No attributes for DKIM headers.'); $self; } sub addTag($$) { my ($self, $name) = (shift, lc shift); $self->{MMFD_tags}{$name} = join ' ', @_; $self; } sub tag($) { $_[0]->{MMFD_tags}{lc $_[1]} } #------------------------------------------ sub tagAlgorithm() { shift->tag('a') } sub tagSignData() { shift->tag('b') } sub tagSignature() { shift->tag('bh') } sub tagC14N() { shift->tag('c') } sub tagDomain() { shift->tag('d') } sub tagSignedHeaders() { shift->tag('h') } sub tagAgentID() { shift->tag('i') } sub tagBodyLength(){ shift->tag('l') } sub tagQueryMethods() { shift->tag('q') } sub tagSelector() { shift->tag('s') } sub tagTimestamp() { shift->tag('t') } sub tagExpires() { shift->tag('x') } sub tagVersion() { shift->tag('v') } sub tagExtract() { shift->tag('z') } #------------------------------------------ 1; Mail-Message-3.016/lib/Mail/Message/Field/Structured.pod0000644000175000001440000003635114721576347023444 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Structured - one line of a structured message header =head1 INHERITANCE Mail::Message::Field::Structured is a Mail::Message::Field::Full is a Mail::Message::Field is a Mail::Reporter Mail::Message::Field::Structured is extended by Mail::Message::Field::Addresses Mail::Message::Field::AuthResults Mail::Message::Field::DKIM Mail::Message::Field::Date Mail::Message::Field::URIs =head1 SYNOPSIS my $f = Mail::Message::Field::Full ->new('Content-Type' => 'text/html'); my @encode = (charset => 'jp', use_continuations => 1); $f->attribute('filename=passwd'); $f->attribute(filename => 'passwd', @encode); my $attr = Mail::Message::Field::Attribute->new(...); $f->attribute($attr); =head1 DESCRIPTION Extends L<"DESCRIPTION" in Mail::Message::Field::Full|Mail::Message::Field::Full/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in Mail::Message::Field::Full|Mail::Message::Field::Full/"OVERLOADED">. =over 4 =item overload: B<""> Inherited, see L =item overload: B<0+> Inherited, see L =item overload: B<<=>> Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =back =head1 METHODS Extends L<"METHODS" in Mail::Message::Field::Full|Mail::Message::Field::Full/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Constructors">. =over 4 =item $obj-EB() Inherited, see L =item Mail::Message::Field::Structured-EB($field, %options) Inherited, see L =item Mail::Message::Field::Structured-EB($data) =over 4 =item * B LINE Pass a LINE as it could be found in a file: a (possibly folded) line which is terminated by a new-line. =item * B NAME, BODY, OPTIONS A set of values which shape the line. =back The NAME is a wellformed header name (you may use wellformedName()) to be sure about the casing. The BODY is a string, one object, or an ref-array of objects. In case of objects, they must fit to the constructor of the field: the types which are accepted may differ. The optional ATTRIBUTE list contains L objects. Finally, there are some OPTIONS. -Option --Defined in --Default attributes [] charset Mail::Message::Field::Full undef datum undef encoding Mail::Message::Field::Full 'q' force Mail::Message::Field::Full false language Mail::Message::Field::Full undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' =over 2 =item attributes => ATTRS There are various ways to specify these attributes: pass a reference to an array which list of key-value pairs representing attributes, or reference to a hash containing these pairs, or an array with L objects. =item charset => STRING =item datum => STRING The method name I is very confusing, even in the RFC. In MailBox, for historical reasons, L returns the part of the field contents before the first semi-colon. L and L address the whole field. There is no common name for the piece of data before the parameters (attributes) in the field-content mentioned in the RFCs, so let's call it B. =item encoding => 'q'|'Q'|'b'|'B' =item force => BOOLEAN =item language => STRING =item log => LEVEL =item trace => LEVEL =back example: of a structured field my @attrs = (Mail::Message::Field::Attribute->new(...), ...); my @options = (extra => 'the color blue'); my $t = Mail::Message::Field::Full->new(To => \@addrs, @attrs, @options); =back =head2 The field Extends L<"The field" in Mail::Message::Field::Full|Mail::Message::Field::Full/"The field">. =over 4 =item $obj-EB() =item Mail::Message::Field::Structured-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$fh] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$wrap] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Access to the name Extends L<"Access to the name" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Access to the name">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =back =head2 Access to the body Extends L<"Access to the body" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Access to the body">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$body] ) Inherited, see L =item $obj-EB( [STRING] ) =item Mail::Message::Field::Structured-EB( [STRING] ) Inherited, see L =item $obj-EB( [$body, [$wrap]] ) Inherited, see L =back =head2 Access to the content Extends L<"Access to the content" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Access to the content">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Returns a list with attribute name and value pairs. =item $obj-EB( $object||<$name,$value,%options> ) Add an attribute to the field. The attributes are added left-to-right into the string representation of the field, although the order of the attributes is un-important, according to the RFCs. You may pass a fully prepared L $object, if you like to do all preparations for correct representation of the data yourself. You may also pass one STRING, which is a fully prepared attribute. This STRING will not be changed, so be careful about quoting and encodings. As third possibility, you can specify an attribute $name and its $value. An attribute object will be created for you implicitly in both cases where such object is not supplied, passing the %options. See L about the available %options. The attribute object is returned, however, when continuations are used this may be an object you already know about. C is returned when construction fails (when the attribute is incorrect). example: $f->attribute(filename => 'passwd'); $f->attribute(filename => 'passwd', use_continuations => 0); my $attr = Mail::Message::Field::Attribute->new(...); $f->attribute($attr); =item $obj-EB() Returns a list with all attributes, which are all L objects. The attributes are not ordered in any way. The list may be empty. Double attributes or continuations are folded into one. =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Structured-EB(STRING, %options) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Structured-EB(STRING, %options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$time] ) =item Mail::Message::Field::Structured-EB( [$time] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Other methods Extends L<"Other methods" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Other methods">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Structured-EB(STRING) Inherited, see L =back =head2 Internals Extends L<"Internals" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Internals">. =over 4 =item $obj-EB( $line | <$name,<$body|$objects>> ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Structured-EB(STRING, %options) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING, %options) Inherited, see L =item $obj-EB( $name, $body, [$maxchars] ) =item Mail::Message::Field::Structured-EB( $name, $body, [$maxchars] ) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING|ARRAY|$objects) Inherited, see L =item $obj-EB(STRING) Inherited, see L =back =head2 Parsing Extends L<"Parsing" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Parsing">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Structured-EB(STRING) Inherited, see L =item $obj-EB(STRING) Inherited, see L =item $obj-EB(STRING) =item Mail::Message::Field::Structured-EB(STRING) Inherited, see L =item $obj-EB( [$value] ) The part of the field before the semi-colon (C<;>). =item $obj-EB(STRING) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Error handling Extends L<"Error handling" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Error handling">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB($object) Inherited, see L =item $obj-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) =item Mail::Message::Field::Structured-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level, [$strings]] ) =item Mail::Message::Field::Structured-EB( [$level, [$strings]] ) Inherited, see L =item $obj-EB($level) =item Mail::Message::Field::Structured-EB($level) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Cleanup Extends L<"Cleanup" in Mail::Message::Field::Full|Mail::Message::Field::Full/"Cleanup">. =over 4 =item $obj-EB() Inherited, see L =back =head1 DETAILS Extends L<"DETAILS" in Mail::Message::Field::Full|Mail::Message::Field::Full/"DETAILS">. =head1 DIAGNOSTICS =over 4 =item Warning: Field content is not numerical: $content The numeric value of a field is requested (for instance the C or C fields should be numerical), however the data contains weird characters. =item Error: Field name too long (max $length), in '$name' It is not specified in the RFCs how long a field name can be, but at least it should be a few characters shorter than the line wrap. =item Warning: Illegal character in charset '$charset' The field is created with an utf8 string which only contains data from the specified character set. However, that character set can never be a valid name because it contains characters which are not permitted. =item Warning: Illegal character in field name $name A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. =item Warning: Illegal character in language '$lang' The field is created with data which is specified to be in a certain language, however, the name of the language cannot be valid: it contains characters which are not permitted by the RFCs. =item Warning: Illegal encoding '$encoding', used 'q' The RFCs only permit base64 (C or C) or quoted-printable (C or C) encoding. Other than these four options are illegal. =item 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. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/AuthResults.pm0000644000175000001440000001245214721576345023407 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::AuthResults;{ our $VERSION = '3.016'; } use base 'Mail::Message::Field::Structured'; use warnings; use strict; use URI; sub init($) { my ($self, $args) = @_; $self->{MMFA_server} = delete $args->{server}; $self->{MMFA_version} = delete $args->{version}; $self->{MMFA_results} = []; $self->addResult($_) for @{delete $args->{results} || []}; $self->SUPER::init($args); } sub parse($) { my ($self, $string) = @_; $string =~ s/\r?\n/ /g; (undef, $string) = $self->consumeComment($string); $self->{MMFA_server} = $string =~ s/^\s*([.\w-]*\w)// ? $1 : 'unknown'; (undef, $string) = $self->consumeComment($string); $self->{MMFA_version} = $string =~ s/^\s*([0-9]+)// ? $1 : 1; (undef, $string) = $self->consumeComment($string); $string =~ s/^.*?\;/;/; # remove accidents my @results; while( $string =~ s/^\s*\;// ) { (undef, $string) = $self->consumeComment($string); if($string =~ s/^\s*none//) { (undef, $string) = $self->consumeComment($string); next; } my %result; push @results, \%result; $string =~ s/^\s*([\w-]*\w)// or next; $result{method} = $1; (undef, $string) = $self->consumeComment($string); if($string =~ s!^\s*/!!) { (undef, $string) = $self->consumeComment($string); $result{method_version} = $1 if $string =~ s/^\s*([0-9]+)//; } (undef, $string) = $self->consumeComment($string); if($string =~ s/^\s*\=//) { (undef, $string) = $self->consumeComment($string); $result{result} = $1 if $string =~ s/^\s*(\w+)//; } (my $comment, $string) = $self->consumeComment($string); if($comment) { $result{comment} = $comment; (undef, $string) = $self->consumeComment($string); } if($string =~ s/\s*reason//) { (undef, $string) = $self->consumeComment($string); if($string =~ s/\s*\=//) { (undef, $string) = $self->consumeComment($string); $result{reason} = $1 if $string =~ s/^\"([^"]*)\"// || $string =~ s/^\'([^']*)\'// || $string =~ s/^(\w+)//; } } while($string =~ /\S/) { (undef, $string) = $self->consumeComment($string); last if $string =~ /^\s*\;/; my $ptype = $string =~ s/^\s*([\w-]+)// ? $1 : last; (undef, $string) = $self->consumeComment($string); my ($property, $value); if($string =~ s/^\s*\.//) { (undef, $string) = $self->consumeComment($string); $property = $string =~ s/^\s*([\w-]+)// ? $1 : last; (undef, $string) = $self->consumeComment($string); if($string =~ s/^\s*\=//) { (undef, $string) = $self->consumeComment($string); $string =~ s/^\s+//; $string =~ s/^\"([^"]*)\"// || $string =~ s/^\'([^']*)\'// || $string =~ s/^([\w@.-]+)// or last; $value = $1; } } if(defined $value) { $result{"$ptype.$property"} = $value; } else { $string =~ s/^.*?\;/;/g; # recover from parser problem } } } $self->addResult($_) for @results; $self; } sub produceBody() { my $self = shift; my $source = $self->server; my $version = $self->version; $source .= " $version" if $version!=1; my @results; foreach my $r ($self->results) { my $method = $r->{method}; $method .= "/$r->{method_version}" if $r->{method_version} != 1; my $result = "$method=$r->{result}"; $result .= ' ' . $self->createComment($r->{comment}) if defined $r->{comment}; if(my $reason = $r->{reason}) { $reason =~ s/"/\\"/g; $result .= qq{ reason="$reason"}; } foreach my $prop (sort keys %$r) { index($prop, '.') > -1 or next; my $value = $r->{$prop}; $value =~ s/"/\\"/g; $result .= qq{ $prop="$value"}; } push @results, $result; } push @results, 'none' unless @results; join '; ', $source, @results; } #------------------------------------------ sub addAttribute($;@) { my $self = shift; $self->log(ERROR => 'No attributes for Authentication-Results.'); $self; } sub server() { shift->{MMFA_server} } sub version() { shift->{MMFA_version} } sub results() { @{shift->{MMFA_results}} } sub addResult($) { my $self = shift; my $r = @_==1 ? shift : {@_}; $r->{method} && $r->{result} or return (); $r->{method_version} ||= 1; push @{$self->{MMFA_results}}, $r; delete $self->{MMFF_body}; $r; } #------------------------------------------ 1; Mail-Message-3.016/lib/Mail/Message/Field/Addresses.pod0000644000175000001440000003624114721576347023213 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Addresses - Fields with e-mail addresses =head1 INHERITANCE Mail::Message::Field::Addresses is a Mail::Message::Field::Structured is a Mail::Message::Field::Full is a Mail::Message::Field is a Mail::Reporter =head1 SYNOPSIS my $cc = Mail::Message::Field::Full->new('Cc'); my $me = Mail::Message::Field::Address->parse('"Test" ') or die; my $other = Mail::Message::Field::Address->new(phrase => 'Other' , address => 'other@example.com') or die; $cc->addAddress($me); $cc->addAddress($other, group => 'them'); $cc->addAddress(phrase => 'third', address => 'more@any.museum' , group => 'them'); my $group = $cc->addGroup(name => 'collegues'); $group->addAddress($me); $group->addAddress(phrase => "You", address => 'you@example.com'); my $msg = Mail::Message->build(Cc => $cc); print $msg->string; my $g = Mail::Message::Field::AddrGroup->new(...); $cc->addGroup($g); =head1 DESCRIPTION All header fields which contain e-mail addresses only. Not all address fields have the same possibilities, but they are all parsed the same: you never know how broken the applications are which produce those messages. When you try to create constructs which are not allowed for a certain kind of field, you will be warned. Extends L<"DESCRIPTION" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"OVERLOADED">. =over 4 =item overload: B<""> Inherited, see L =item overload: B<0+> Inherited, see L =item overload: B<<=>> Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =back =head1 METHODS Extends L<"METHODS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Constructors">. =over 4 =item $obj-EB() Inherited, see L =item Mail::Message::Field::Addresses-EB($field, %options) Inherited, see L =item Mail::Message::Field::Addresses-EB() -Option --Defined in --Default attributes Mail::Message::Field::Structured charset Mail::Message::Field::Full undef datum Mail::Message::Field::Structured undef encoding Mail::Message::Field::Full 'q' force Mail::Message::Field::Full false language Mail::Message::Field::Full undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' =over 2 =item attributes => ATTRS =item charset => STRING =item datum => STRING =item encoding => 'q'|'Q'|'b'|'B' =item force => BOOLEAN =item language => STRING =item log => LEVEL =item trace => LEVEL =back =back =head2 The field Extends L<"The field" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"The field">. =over 4 =item $obj-EB() =item Mail::Message::Field::Addresses-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$fh] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$wrap] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Access to the name Extends L<"Access to the name" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the name">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =back =head2 Access to the body Extends L<"Access to the body" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the body">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$body] ) Inherited, see L =item $obj-EB( [STRING] ) =item Mail::Message::Field::Addresses-EB( [STRING] ) Inherited, see L =item $obj-EB( [$body, [$wrap]] ) Inherited, see L =back =head2 Access to the content Extends L<"Access to the content" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the content">. =over 4 =item $obj-EB( [$address], %options ) Add an $address to the field. The addresses are organized in groups. If no group is specified, the default group is taken to store the address in. If no $address is specified, the option must be sufficient to create a L from. See the %options of L. -Option--Default group '' =over 2 =item group => STRING =back =item $obj-EB(...) Attributes are not supported for address fields. =item $obj-EB($group|%options) Add a group of addresses to this field. A $group can be specified, which is a L object, or one is created for you using the %options. The group is returned. -Option--Default name '' =over 2 =item name => STRING =back =item $obj-EB() Returns a list with all addresses defined in any group of addresses: all addresses which are specified on the line. The addresses are L objects. example: my @addr = $field->addresses; =item $obj-EB() Inherited, see L =item $obj-EB( $object||<$name,$value,%options> ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Addresses-EB(STRING, %options) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Addresses-EB(STRING, %options) Inherited, see L =item $obj-EB($name) Returns the group of addresses with the specified $name, or C if it does not exist. If $name is C, then the default groep is returned. =item $obj-EB() Returns a list with all group names which are defined. =item $obj-EB() Returns all address groups which are defined in this field. Each element is a L object. =item $obj-EB() Inherited, see L =item $obj-EB( [$time] ) =item Mail::Message::Field::Addresses-EB( [$time] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Other methods Extends L<"Other methods" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Other methods">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Addresses-EB(STRING) Inherited, see L =back =head2 Internals Extends L<"Internals" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Internals">. =over 4 =item $obj-EB( $line | <$name,<$body|$objects>> ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Addresses-EB(STRING, %options) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING, %options) Inherited, see L =item $obj-EB( $name, $body, [$maxchars] ) =item Mail::Message::Field::Addresses-EB( $name, $body, [$maxchars] ) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING|ARRAY|$objects) Inherited, see L =item $obj-EB(STRING) Inherited, see L =back =head2 Parsing Extends L<"Parsing" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Parsing">. =over 4 =item $obj-EB(STRING, %options) Try to destilate address information from the STRING. Returned are an address B and the left-over string. If no address was found, the first returned value is C. =item $obj-EB(STRING) =item Mail::Message::Field::Addresses-EB(STRING) Inherited, see L =item $obj-EB(STRING) Try to get a valid domain representation from STRING. Returned are the domain string as found (or C) and the rest of the string. =item $obj-EB(STRING) Inherited, see L =item $obj-EB(STRING) =item Mail::Message::Field::Addresses-EB(STRING) Inherited, see L =item $obj-EB( [$value] ) Inherited, see L =item $obj-EB(STRING) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Error handling Extends L<"Error handling" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Error handling">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB($object) Inherited, see L =item $obj-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) =item Mail::Message::Field::Addresses-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level, [$strings]] ) =item Mail::Message::Field::Addresses-EB( [$level, [$strings]] ) Inherited, see L =item $obj-EB($level) =item Mail::Message::Field::Addresses-EB($level) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Cleanup Extends L<"Cleanup" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Cleanup">. =over 4 =item $obj-EB() Inherited, see L =back =head1 DETAILS Extends L<"DETAILS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DETAILS">. =head1 DIAGNOSTICS =over 4 =item Warning: Field content is not numerical: $content The numeric value of a field is requested (for instance the C or C fields should be numerical), however the data contains weird characters. =item Error: Field name too long (max $length), in '$name' It is not specified in the RFCs how long a field name can be, but at least it should be a few characters shorter than the line wrap. =item Warning: Illegal character in charset '$charset' The field is created with an utf8 string which only contains data from the specified character set. However, that character set can never be a valid name because it contains characters which are not permitted. =item Warning: Illegal character in field name $name A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. =item Warning: Illegal character in language '$lang' The field is created with data which is specified to be in a certain language, however, the name of the language cannot be valid: it contains characters which are not permitted by the RFCs. =item Warning: Illegal encoding '$encoding', used 'q' The RFCs only permit base64 (C or C) or quoted-printable (C or C) encoding. Other than these four options are illegal. =item Error: No attributes for address fields. Is is not possible to add attributes to address fields: it is not permitted by the RFCs. =item 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. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/Unstructured.pm0000644000175000001440000000175414721576345023636 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::Unstructured;{ our $VERSION = '3.016'; } use base 'Mail::Message::Field::Full'; use strict; use warnings; sub init($) { my ($self, $args) = @_; if($args->{body} && ($args->{encoding} || $args->{charset})) { $args->{body} = $self->encode($args->{body}, %$args); } $self->SUPER::init($args) or return; $self->log(WARNING =>"Attributes are not supported for unstructured fields") if defined $args->{attributes}; $self->log(WARNING => "No extras for unstructured fields") if defined $args->{extra}; $self; } 1; Mail-Message-3.016/lib/Mail/Message/Field/Flex.pod0000644000175000001440000002345714721576347022201 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Flex - one line of a message header =head1 INHERITANCE Mail::Message::Field::Flex is a Mail::Message::Field is a Mail::Reporter =head1 SYNOPSIS =head1 DESCRIPTION This is the flexible implementation of a field: it can easily be extended because it stores its data in a hash and the constructor (C) and initializer (C) are split. However, you pay the price in performance. L is faster (as the name predicts). Extends L<"DESCRIPTION" in Mail::Message::Field|Mail::Message::Field/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in Mail::Message::Field|Mail::Message::Field/"OVERLOADED">. =over 4 =item overload: B<""> Inherited, see L =item overload: B<0+> Inherited, see L =item overload: B<<=>> Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =back =head1 METHODS Extends L<"METHODS" in Mail::Message::Field|Mail::Message::Field/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Message::Field|Mail::Message::Field/"Constructors">. =over 4 =item $obj-EB() Inherited, see L =item Mail::Message::Field::Flex-EB($data) If you stick to this flexible class of header fields, you have a bit more facilities than with L. Amongst it, you can specify options with the creation. Possible arguments: =over 4 =item * B LINE ass a LINE as it could be found in a file: a (possibly folded) line which is terminated by a new-line. =item * B NAME, (BODY|OBJECTS), [ATTRIBUTES], OPTIONS A set of values which shape the line. =back To be able to distinguish the different parameters, you will have to specify the OPTIONS as ARRAY of option pairs, or HASH of options. The ATTRIBUTES are a flat list of key-value pairs. The body is specified as one BODY string, one OBJECT, or a reference to an array of OBJECTS. See L: -Option --Defined in --Default attributes [] comment undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' =over 2 =item attributes => ATTRS Reference to array with list of key-value pairs representing attributes, or reference to a hash containing these pairs. This is an alternative notation for specifying ATTRIBUTES directly as method arguments. =item comment => STRING A pre-formatted list of attributes. =item log => LEVEL =item trace => LEVEL =back =back =head2 The field Extends L<"The field" in Mail::Message::Field|Mail::Message::Field/"The field">. =over 4 =item $obj-EB() =item Mail::Message::Field::Flex-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$fh] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$wrap] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Access to the name Extends L<"Access to the name" in Mail::Message::Field|Mail::Message::Field/"Access to the name">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =back =head2 Access to the body Extends L<"Access to the body" in Mail::Message::Field|Mail::Message::Field/"Access to the body">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$body] ) Inherited, see L =item $obj-EB( [STRING] ) =item Mail::Message::Field::Flex-EB( [STRING] ) Inherited, see L =item $obj-EB( [$body, [$wrap]] ) Inherited, see L =back =head2 Access to the content Extends L<"Access to the content" in Mail::Message::Field|Mail::Message::Field/"Access to the content">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB( $name, [$value] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$time] ) =item Mail::Message::Field::Flex-EB( [$time] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Other methods Extends L<"Other methods" in Mail::Message::Field|Mail::Message::Field/"Other methods">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Flex-EB(STRING) Inherited, see L =back =head2 Internals Extends L<"Internals" in Mail::Message::Field|Mail::Message::Field/"Internals">. =over 4 =item $obj-EB( $line | <$name,<$body|$objects>> ) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB( $name, $body, [$maxchars] ) =item Mail::Message::Field::Flex-EB( $name, $body, [$maxchars] ) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING|ARRAY|$objects) Inherited, see L =item $obj-EB(STRING) Inherited, see L =back =head2 Error handling Extends L<"Error handling" in Mail::Message::Field|Mail::Message::Field/"Error handling">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB($object) Inherited, see L =item $obj-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) =item Mail::Message::Field::Flex-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level, [$strings]] ) =item Mail::Message::Field::Flex-EB( [$level, [$strings]] ) Inherited, see L =item $obj-EB($level) =item Mail::Message::Field::Flex-EB($level) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Cleanup Extends L<"Cleanup" in Mail::Message::Field|Mail::Message::Field/"Cleanup">. =over 4 =item $obj-EB() Inherited, see L =back =head1 DETAILS Extends L<"DETAILS" in Mail::Message::Field|Mail::Message::Field/"DETAILS">. =head1 DIAGNOSTICS =over 4 =item Warning: Field content is not numerical: $content The numeric value of a field is requested (for instance the C or C fields should be numerical), however the data contains weird characters. =item Error: Field name too long (max $length), in '$name' It is not specified in the RFCs how long a field name can be, but at least it should be a few characters shorter than the line wrap. =item Warning: Illegal character in field name $name A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. =item 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. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/Full.pod0000644000175000001440000004772614721576347022212 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Full - construct one smart line in a message header =head1 INHERITANCE Mail::Message::Field::Full is a Mail::Message::Field is a Mail::Reporter Mail::Message::Field::Full is extended by Mail::Message::Field::Structured Mail::Message::Field::Unstructured =head1 SYNOPSIS # Getting to understand the complexity of a header field ... my $fast = $msg->head->get('subject'); my $full = Mail::Message::Field::Full->from($fast); my $full = $msg->head->get('subject')->study; # same my $full = $msg->head->study('subject'); # same my $full = $msg->study('subject'); # same # ... or build a complex header field yourself my $f = Mail::Message::Field::Full->new('To'); my $f = Mail::Message::Field::Full->new('Subject: hi!'); my $f = Mail::Message::Field::Full->new(Subject => 'hi!'); =head1 DESCRIPTION This is the I implementation of a header field: it has I understanding of all predefined header fields. These objects will be quite slow, because header fields can be very complex. Of course, this class delivers the optimal result, but for a quite large penalty in performance and memory consumption. Are you willing to accept? This class supports the common header description from RFC2822 (formerly RFC822), the extensions with respect to character set encodings as specified in RFC2047, and the extensions on language specification and long parameter wrapping from RFC2231. If you do not need the latter two, then the L and L are enough for your application. Extends L<"DESCRIPTION" in Mail::Message::Field|Mail::Message::Field/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in Mail::Message::Field|Mail::Message::Field/"OVERLOADED">. =over 4 =item overload: B<""> Inherited, see L =item overload: B<0+> Inherited, see L =item overload: B<<=>> Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =item overload: B In string context, the decoded body is returned, as if L would have been called. =back =head1 METHODS Extends L<"METHODS" in Mail::Message::Field|Mail::Message::Field/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Message::Field|Mail::Message::Field/"Constructors">. =over 4 =item $obj-EB() Inherited, see L =item Mail::Message::Field::Full-EB($field, %options) Convert any $field (a L object) into a new L object. This conversion is done the hard way: the string which is produced by the original object is parsed again. Usually, the string which is parsed is exactly the line (or lines) as found in the original input source, which is a good thing because Full fields are much more careful with the actual content. %options are passed to the constructor (see L). In any case, some extensions of this Full field class is returned. It depends on which field is created what kind of class we get. example: my $fast = $msg->head->get('subject'); my $full = Mail::Message::Field::Full->from($fast); my $full = $msg->head->get('subject')->study; # same my $full = $msg->head->study('subject'); # same my $full = $msg->get('subject'); # same =item Mail::Message::Field::Full-EB($data) Creating a new field object the correct way is a lot of work, because there is so much freedom in the RFCs, but at the same time so many restrictions. Most fields are implemented, but if you have your own field (and do no want to contribute it to MailBox), then simply call new on your own package. You have the choice to instantiate the object as string or in prepared parts: =over 4 =item * B LINE, OPTIONS Pass a LINE as it could be found in a file: a (possibly folded) line which is terminated by a new-line. =item * B NAME, [BODY], OPTIONS A set of values which shape the line. =back The NAME is a wellformed header name (you may use wellformedName()) to be sure about the casing. The BODY is a string, one object, or an ref-array of objects. In case of objects, they must fit to the constructor of the field: the types which are accepted may differ. The optional ATTRIBUTE list contains L objects. Finally, there are some OPTIONS. -Option --Defined in --Default charset undef encoding 'q' force false language undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' =over 2 =item charset => STRING The body is specified in utf8, and must become 7-bits ascii to be transmited. Specify a charset to which the multi-byte utf8 is converted before it gets encoded. See L, which does the job. =item encoding => 'q'|'Q'|'b'|'B' Non-ascii characters are encoded using Quoted-Printable ('q' or 'Q') or Base64 ('b' or 'B') encoding. =item force => BOOLEAN Enforce encoding in the specified charset, even when it is not needed because the body does not contain any non-ascii characters. =item language => STRING The language used can be specified, however is rarely used my mail clients. =item log => LEVEL =item trace => LEVEL =back example: my $s = Mail::Message::Field::Full->new('Subject: Hello World'); my $s = Mail::Message::Field::Full->new('Subject', 'Hello World'); my @attrs = (Mail::Message::Field::Attribute->new(...), ...); my @options = (extra => 'the color blue'); my $t = Mail::Message::Field::Full->new(To => \@addrs, @attrs, @options); =back =head2 The field Extends L<"The field" in Mail::Message::Field|Mail::Message::Field/"The field">. =over 4 =item $obj-EB() =item Mail::Message::Field::Full-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$fh] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$wrap] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Access to the name Extends L<"Access to the name" in Mail::Message::Field|Mail::Message::Field/"Access to the name">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =back =head2 Access to the body Extends L<"Access to the body" in Mail::Message::Field|Mail::Message::Field/"Access to the body">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB(%options) Returns the unfolded body of the field, where encodings are resolved. The returned line will still contain comments and such. The %options are passed to the decoder, see L. BE WARNED: if the field is a structured field, the content may change syntax, because of encapsulated special characters. By default, the body is decoded as text, which results in a small difference within comments as well (read the RFC). =item $obj-EB() Inherited, see L =item $obj-EB( [$body] ) Inherited, see L =item $obj-EB( [STRING] ) =item Mail::Message::Field::Full-EB( [STRING] ) Inherited, see L =item $obj-EB( [$body, [$wrap]] ) Inherited, see L =back =head2 Access to the content Extends L<"Access to the content" in Mail::Message::Field|Mail::Message::Field/"Access to the content">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB( $name, [$value] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() For structured header fields, this removes the original encoding of the field's body (the format as it was offered to L), therefore the next request for the field will have to re-produce the read data clean and nice. For unstructured bodies, this method doesn't do a thing. =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Full-EB(STRING, %options) Create a comment to become part in a field. Comments are automatically included within parenthesis. Matching pairs of parenthesis are permitted within the STRING. When a non-matching parenthesis are used, it is only permitted with an escape (a backslash) in front of them. These backslashes will be added automatically if needed (don't worry!). Backslashes will stay, except at the end, where it will be doubled. The %options are C, C, and C as always. The created comment is returned. =item $obj-EB(STRING, %options) =item Mail::Message::Field::Full-EB(STRING, %options) A phrase is a text which plays a well defined role. This is the main difference with comments, which have do specified meaning. Some special characters in the phrase will cause it to be surrounded with double quotes: do not specify them yourself. The %options are C, C, and C, as always. =item $obj-EB() Inherited, see L =item $obj-EB( [$time] ) =item Mail::Message::Field::Full-EB( [$time] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Other methods Extends L<"Other methods" in Mail::Message::Field|Mail::Message::Field/"Other methods">. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Full-EB(STRING) Inherited, see L =back =head2 Internals Extends L<"Internals" in Mail::Message::Field|Mail::Message::Field/"Internals">. =over 4 =item $obj-EB( $line | <$name,<$body|$objects>> ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Full-EB(STRING, %options) Decode field encoded STRING to an utf8 string. The input STRING is part of a header field, and as such, may contain encoded words in C<=?...?.?...?=> format defined by RFC2047. The STRING may contain multiple encoded parts, maybe using different character sets. Be warned: you MUST first interpret the field into parts, like phrases and comments, and then decode each part separately, otherwise the decoded text may interfere with your markup characters. Be warned: language information, which is defined in RFC2231, is ignored. Encodings with unknown charsets are left untouched [requires v2.085, otherwise croaked]. Unknown characters within an charset are replaced by a '?'. -Option --Default is_text 1 =over 2 =item is_text => BOOLEAN Encoding on text is slightly more complicated than encoding structured data, because it contains blanks. Visible blanks have to be ignored between two encoded words in the text, but not when an encoded word follows or precedes an unencoded word. Phrases and comments are texts. =back example: print Mail::Message::Field::Full->decode('=?iso-8859-1?Q?J=F8rgen?='); # prints JE<0slash>rgen =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING, %options) Encode the (possibly utf8 encoded) STRING to a string which is acceptable to the RFC2047 definition of a header: only containing us-ascii characters. -Option --Default charset 'us-ascii' encoding 'q' force language undef name undef =over 2 =item charset => STRING STRING is an utf8 string which has to be translated into any byte-wise character set for transport, because MIME-headers can only contain ascii characters. =item encoding => 'q'|'Q'|'b'|'B' The character encoding to be used. With C or C, quoted-printable encoding will be used. With C or C, base64 encoding will be taken. =item force => BOOLEAN Encode the string, even when it only contains us-ascii characters. By default, this is off because it decreases readibility of the produced header fields. =item language => STRING RFC2231 defines how to specify language encodings in encoded words. The STRING is a strandard iso language name. =item name => STRING [3.002] When the name of the field is given, the first encoded line will be shorter. =back =item $obj-EB( $name, $body, [$maxchars] ) =item Mail::Message::Field::Full-EB( $name, $body, [$maxchars] ) Inherited, see L =item $obj-EB( [$length] ) Inherited, see L =item $obj-EB(STRING|ARRAY|$objects) Inherited, see L =item $obj-EB(STRING) Inherited, see L =back =head2 Parsing You probably do not want to call these parsing methods yourself: use the standard constructors (L) and it will be done for you. =over 4 =item $obj-EB(STRING) =item Mail::Message::Field::Full-EB(STRING) Try to read a comment from the STRING. When successful, the comment without encapsulating parenthesis is returned, together with the rest of the string. =item $obj-EB(STRING) Returns three elemens: the atom-text, the rest string, and the concatenated comments. Both atom and comments can be undef. =item $obj-EB(STRING) =item Mail::Message::Field::Full-EB(STRING) Take the STRING, and try to strip-off a valid phrase. In the obsolete phrase syntax, any sequence of words is accepted as phrase (as long as certain special characters are not used). RFC2822 is stricter: only one word or a quoted string is allowed. As always, the obsolete syntax is accepted, and the new syntax is produced. This method returns two elements: the phrase (or undef) followed by the resulting string. The phrase will be removed from the optional quotes. Be warned that C<""> will return an empty, valid phrase. example: my ($phrase, $rest) = $field->consumePhrase( q["hi!" ] ); =item $obj-EB(STRING) Get the detailed information from the STRING, and store the data found in the field object. The accepted input is very field type dependent. Unstructured fields do no parsing whatsoever. =item $obj-EB() Produce the text for the field, based on the information stored within the field object. Usually, you wish the exact same line as was found in the input source of a message. But when you have created a field yourself, it should get formatted. You may call L on a preformatted field to enforce a call to this method when the field is needed later. =back =head2 Error handling Extends L<"Error handling" in Mail::Message::Field|Mail::Message::Field/"Error handling">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB($object) Inherited, see L =item $obj-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) =item Mail::Message::Field::Full-EB( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level, [$strings]] ) =item Mail::Message::Field::Full-EB( [$level, [$strings]] ) Inherited, see L =item $obj-EB($level) =item Mail::Message::Field::Full-EB($level) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB( [$level] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Cleanup Extends L<"Cleanup" in Mail::Message::Field|Mail::Message::Field/"Cleanup">. =over 4 =item $obj-EB() Inherited, see L =back =head1 DETAILS Extends L<"DETAILS" in Mail::Message::Field|Mail::Message::Field/"DETAILS">. =head1 DIAGNOSTICS =over 4 =item Warning: Field content is not numerical: $content The numeric value of a field is requested (for instance the C or C fields should be numerical), however the data contains weird characters. =item Error: Field name too long (max $length), in '$name' It is not specified in the RFCs how long a field name can be, but at least it should be a few characters shorter than the line wrap. =item Warning: Illegal character in charset '$charset' The field is created with an utf8 string which only contains data from the specified character set. However, that character set can never be a valid name because it contains characters which are not permitted. =item Warning: Illegal character in field name $name A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. =item Warning: Illegal character in language '$lang' The field is created with data which is specified to be in a certain language, however, the name of the language cannot be valid: it contains characters which are not permitted by the RFCs. =item Warning: Illegal encoding '$encoding', used 'q' The RFCs only permit base64 (C or C) or quoted-printable (C or C) encoding. Other than these four options are illegal. =item 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. =back =head1 SEE ALSO This module is part of Mail-Message distribution version 3.016, built on November 27, 2024. Website: F =head1 LICENSE Copyrights 2001-2024 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 Mail-Message-3.016/lib/Mail/Message/Field/Addresses.pm0000644000175000001440000001462514721576345023045 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::Addresses;{ our $VERSION = '3.016'; } use base 'Mail::Message::Field::Structured'; use strict; use warnings; use Mail::Message::Field::AddrGroup; use Mail::Message::Field::Address; use List::Util 'first'; #------------------------------------------ # what is permitted for each field. my $address_list = {groups => 1, multi => 1}; my $mailbox_list = {multi => 1}; my $mailbox = {}; my %accepted = # defaults to $address_list ( from => $mailbox_list , sender => $mailbox ); sub init($) { my ($self, $args) = @_; $self->{MMFF_groups} = []; ( my $def = lc $args->{name} ) =~ s/^resent\-//; $self->{MMFF_defaults} = $accepted{$def} || $address_list; my ($body, @body); if($body = $args->{body}) { @body = ref $body eq 'ARRAY' ? @$body : ($body); return () unless @body; } if(@body > 1 || ref $body[0]) { $self->addAddress($_) foreach @body; delete $args->{body}; } $self->SUPER::init($args) or return; $self; } #------------------------------------------ sub addAddress(@) { my $self = shift; my $email = @_ && ref $_[0] ? shift : undef; my %args = @_; my $group = delete $args{group} || ''; $email = Mail::Message::Field::Address->new(%args) unless defined $email; my $set = $self->group($group) || $self->addGroup(name => $group); $set->addAddress($email); $email; } sub addGroup(@) { my $self = shift; my $group = @_ == 1 ? shift : Mail::Message::Field::AddrGroup->new(@_); push @{$self->{MMFF_groups}}, $group; $group; } sub group($) { my ($self, $name) = @_; $name = '' unless defined $name; first { lc($_->name) eq lc($name) } $self->groups; } sub groups() { @{shift->{MMFF_groups}} } sub groupNames() { map {$_->name} shift->groups } sub addresses() { map {$_->addresses} shift->groups } sub addAttribute($;@) { my $self = shift; $self->log(ERROR => 'No attributes for address fields.'); $self; } #------------------------------------------ sub parse($) { my ($self, $string) = @_; my ($group, $email) = ('', undef); $string =~ s/\s+/ /gs; ADDRESS: while(1) { (my $comment, $string) = $self->consumeComment($string); my $start_length = length $string; if($string =~ s/^\s*\;//s ) { $group = ''; next ADDRESS } # end group if($string =~ s/^\s*\,//s ) { next ADDRESS} # end address (my $email, $string) = $self->consumeAddress($string); if(defined $email) { # Pattern starts with e-mail address ($comment, $string) = $self->consumeComment($string); $email->comment($comment) if defined $comment; } else { # Pattern not plain address my $real_phrase = $string =~ m/^\s*\"/; my @words; # In rfc2822 obs-phrase, we can have more than one word with # comments inbetween. WORD: while(1) { (my $word, $string) = $self->consumePhrase($string); defined $word or last; push @words, $word if length $word; ($comment, $string) = $self->consumeComment($string); if($string =~ s/^\s*\://s ) { $group = $word; # even empty groups must appear $self->addGroup(name => $group) unless $self->group($group); next ADDRESS; } } my $phrase = @words ? join ' ', @words : undef; my $angle; if($string =~ s/^\s*\<([^>]*)\>//s) { $angle = $1 } elsif($real_phrase) { $self->log(ERROR => "Ignore unrelated phrase `$1'") if $string =~ s/^\s*\"(.*?)\r?\n//; next ADDRESS; } elsif(defined $phrase) { ($angle = $phrase) =~ s/\s+/./g; undef $phrase; } ($comment, $string) = $self->consumeComment($string); # remove obsoleted route info. return 1 unless defined $angle; $angle =~ s/^\@.*?\://; ($email, $angle) = $self->consumeAddress($angle , phrase => $phrase, comment => $comment); } $self->addAddress($email, group => $group) if defined $email; return 1 if $string =~ m/^\s*$/s; # Do not get stuck on illegal characters last if $start_length == length $string; } $self->log(WARNING => 'Illegal part in address field '.$self->Name. ": $string\n"); 0; } sub produceBody() { my @groups = sort {$a->name cmp $b->name} shift->groups; @groups or return ''; @groups > 1 or return $groups[0]->string; my $plain = $groups[0]->name eq '' && $groups[0]->addresses ? (shift @groups)->string.',' : ''; join ' ', $plain, (map $_->string, @groups); } sub consumeAddress($@) { my ($self, $string, @options) = @_; my ($local, $shorter, $loccomment); if($string =~ s/^\s*"((?:\\.|[^"])*)"\s*\@/@/) { # local part is quoted-string rfc2822 ($local, $shorter) = ($1, $string); $local =~ s/\\"/"/g; } else { ($local, $shorter, $loccomment) = $self->consumeDotAtom($string); $local =~ s/\s//g if defined $local; } defined $local && $shorter =~ s/^\s*\@// or return (undef, $string); (my $domain, $shorter, my $domcomment) = $self->consumeDomain($shorter); defined $domain or return (undef, $string); # loccomment and domcomment ignored my $email = Mail::Message::Field::Address ->new(username => $local, domain => $domain, @options); ($email, $shorter); } sub consumeDomain($) { my ($self, $string) = @_; return ($self->stripCFWS($1), $string) if $string =~ s/\s*(\[(?:[^[]\\]*|\\.)*\])//; my ($atom, $rest, $comment) = $self->consumeDotAtom($string); $atom =~ s/\s//g if defined $atom; ($atom, $rest, $comment); } #------------------------------------------ 1; Mail-Message-3.016/lib/Mail/Message/Field/Structured.pm0000644000175000001440000000706414721576345023273 0ustar00markovusers00000000000000# Copyrights 2001-2024 by [Mark Overmeer ]. # For other contributors see ChangeLog. # See the manual pages for details on the licensing terms. # Pod stripped from pm file by OODoc 2.03. # This code is part of distribution Mail-Message. Meta-POD processed with # OODoc into POD and HTML manual-pages. See README.md # Copyright Mark Overmeer. Licensed under the same terms as Perl itself. package Mail::Message::Field::Structured;{ our $VERSION = '3.016'; } use base 'Mail::Message::Field::Full'; use strict; use warnings; use Mail::Message::Field::Attribute; use Storable 'dclone'; sub init($) { my ($self, $args) = @_; $self->{MMFS_attrs} = {}; $self->{MMFS_datum} = $args->{datum}; $self->SUPER::init($args); my $attr = $args->{attributes} || []; $attr = [ %$attr ] if ref $attr eq 'HASH'; while(@$attr) { my $name = shift @$attr; if(ref $name) { $self->attribute($name) } else { $self->attribute($name, shift @$attr) } } $self; } sub clone() { dclone(shift) } #------------------------------------------ sub attribute($;$) { my ($self, $attr) = (shift, shift); my $name; if(ref $attr) { $name = $attr->name } elsif( !@_ ) { return $self->{MMFS_attrs}{lc $attr} } else { $name = $attr; $attr = Mail::Message::Field::Attribute->new($name, @_); } delete $self->{MMFF_body}; $self->{MMFS_attrs}{lc $name} = $attr; } sub attributes() { values %{shift->{MMFS_attrs}} } sub beautify() { delete shift->{MMFF_body} } sub attrPairs() { map +($_->name, $_->value), shift->attributes } #------------------------- sub parse($) { my ($self, $string) = @_; for($string) { # remove FWS, even within quoted strings s/\r?\n(\s)/$1/gs; s/\r?\n/ /gs; s/\s+$//; } my $datum = ''; while(length $string && substr($string, 0, 1) ne ';') { (undef, $string) = $self->consumeComment($string); $datum .= $1 if $string =~ s/^([^;(]+)//; } $self->{MMFS_datum} = $datum; my $found = ''; while($string =~ m/\S/) { my $len = length $string; if($string =~ s/^\s*\;\s*// && length $found) { my ($name) = $found =~ m/^([^*]+)\*/; if($name && (my $cont = $self->attribute($name))) { $cont->addComponent($found); # continuation } else { my $attr = Mail::Message::Field::Attribute->new($found); $self->attribute($attr); } $found = ''; } (undef, $string) = $self->consumeComment($string); $string =~ s/^\n//; (my $text, $string) = $self->consumePhrase($string); $found .= $text if defined $text; if(length($string) == $len) { # nothing consumed, remove character to avoid endless loop $string =~ s/^\s*\S//; } } if(length $found) { my ($name) = $found =~ m/^([^*]+)\*/; if($name && (my $cont = $self->attribute($name))) { $cont->addComponent($found); # continuation } else { my $attr = Mail::Message::Field::Attribute->new($found); $self->attribute($attr); } } 1; } sub produceBody() { my $self = shift; my $attrs = $self->{MMFS_attrs}; my $datum = $self->{MMFS_datum}; join '; ' , (defined $datum ? $datum : '') , map {$_->string} @{$attrs}{sort keys %$attrs}; } sub datum(@) { my $self = shift; @_ or return $self->{MMFS_datum}; delete $self->{MMFF_body}; $self->{MMFS_datum} = shift; } 1; Mail-Message-3.016/lib/Mail/Message/Field/Date.pod0000644000175000001440000003130614721576347022150 0ustar00markovusers00000000000000=encoding utf8 =head1 NAME Mail::Message::Field::Date - message header field with uris =head1 INHERITANCE Mail::Message::Field::Date is a Mail::Message::Field::Structured is a Mail::Message::Field::Full is a Mail::Message::Field is a Mail::Reporter =head1 SYNOPSIS my $f = Mail::Message::Field->new(Date => time); =head1 DESCRIPTION Dates are a little more tricky than it should be: the formatting permits a few constructs more than other RFCs use for timestamps. For instance, a small subset of timezone abbreviations are permitted. The studied date field will reformat the content into a standard form. Extends L<"DESCRIPTION" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DESCRIPTION">. =head1 OVERLOADED Extends L<"OVERLOADED" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"OVERLOADED">. =over 4 =item overload: B<""> Inherited, see L =item overload: B<0+> Inherited, see L =item overload: B<<=>> Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =item overload: B Inherited, see L =back =head1 METHODS Extends L<"METHODS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Constructors">. =over 4 =item $obj-EB() Inherited, see L =item Mail::Message::Field::Date-EB($field, %options) Inherited, see L =item Mail::Message::Field::Date-EB($data) -Option --Defined in --Default attributes Mail::Message::Field::Structured charset Mail::Message::Field::Full undef datum Mail::Message::Field::Structured undef encoding Mail::Message::Field::Full 'q' force Mail::Message::Field::Full false language Mail::Message::Field::Full undef log Mail::Reporter 'WARNINGS' trace Mail::Reporter 'WARNINGS' =over 2 =item attributes => ATTRS =item charset => STRING =item datum => STRING =item encoding => 'q'|'Q'|'b'|'B' =item force => BOOLEAN =item language => STRING =item log => LEVEL =item trace => LEVEL =back example: my $mmfd = 'Mail::Message::Field::Date'; my $f = $mmfd->new(Date => time); =back =head2 The field Extends L<"The field" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"The field">. =over 4 =item $obj-EB() =item Mail::Message::Field::Date-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$fh] ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$wrap] ) Inherited, see L =item $obj-EB() Inherited, see L =back =head2 Access to the name Extends L<"Access to the name" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the name">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =back =head2 Access to the body Extends L<"Access to the body" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the body">. =over 4 =item $obj-EB() Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [$body] ) Inherited, see L =item $obj-EB( [STRING] ) =item Mail::Message::Field::Date-EB( [STRING] ) Inherited, see L =item $obj-EB( [$body, [$wrap]] ) Inherited, see L =back =head2 Access to the content Extends L<"Access to the content" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the content">. =over 4 =item $obj-EB(...) Attributes are not supported for date fields. =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( $object||<$name,$value,%options> ) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB( [STRING] ) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Date-EB(STRING, %options) Inherited, see L =item $obj-EB(STRING, %options) =item Mail::Message::Field::Date-EB(STRING, %options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB