NAME
DateTime::Format::Mail - Convert between DateTime and RFC2822/822 formats
SYNOPSIS
use DateTime::Format::Mail;
# From RFC2822 via class method:
my $datetime = DateTime::Format::Mail->parse_datetime(
"Sat, 29 Mar 2003 22:11:18 -0800"
);
print $datetime->ymd('.'); # "2003.03.29"
# or via an object
my $pf = DateTime::Format::Mail->new();
print $pf->parse_datetime(
"Fri, 23 Nov 2001 21:57:24 -0600"
)->ymd; # "2001-11-23"
# Back to RFC2822 date
use DateTime;
my $dt = DateTime->new(
year => 1979, month => 7, day => 16,
hour => 16, minute => 45, second => 20,
time_zone => "Australia/Sydney"
);
my $str = DateTime::Format::Mail->format_datetime( $dt );
print $str; # "Mon, 16 Jul 1979 16:45:20 +1000"
# or via an object
$str = $pf->format_datetime( $dt );
print $str; # "Mon, 16 Jul 1979 16:45:20 +1000"DESCRIPTION
RFC2822 introduces a slightly different format of date than that used by RFC822. The main correction is that the format is more limited, and thus easier to parse.
Despite the ease of generating and parsing perfectly valid RFC822 and RFC2822 people still get it wrong. So this module provides three things for those handling mail dates:
A strict parser, so you can see where you're right.
A strict formatter, so you can generate the right stuff to begin with.
A loose parser, so you can take the misbegotten output from other programs and turn it into something useful.
CONSTRUCTORS
new
Creates a new DateTime::Format::Mail instance. This is generally not required for simple operations. If you wish to use a different parsing style from the default then you'll need to create an object.
my $parser = DateTime::Format::Mail->new()
my $copy = $parser->new();If called on an existing object then it clones the object.
It has one, optional, parameter.
looseshould be a true value if you want a loose parser, else either don't specify it or give it a false value.
my $loose = DateTime::Format::Mail->new( loose => 1 );clone
For those who prefer to explicitly clone via a method called clone(). If called as a class method it will die.
my $clone = $original->clone();PARSING METHODS
These methods work on either our objects or as class methods.
loose, strict
These methods set the parsing strictness.
my $parser = DateTime::Format::Mail->new;
$parser->loose;
$parser->strict; # (the default)
my $p = DateTime::Format::Mail->new->loose;parse_datetime
Given an RFC2822 or 822 datetime string, return a DateTime object representing that date and time. Unparseable strings will cause the method to die.
See the synopsis for examples.
set_year_cutoff
Two digit years are treated as valid in the loose translation and are translated up to a 19xx or 20xx figure. By default, if the year is greater than '60', it's treated as being in the 20th century (19xx). If lower, or equal, then the 21st (20xx).
set_year_cutoff() allows you to modify this behaviour by specifying a different cutoff, where the default is 60.
The return value is the object itself.
year_cutoff
Returns the current cutoff. Can be used as either a class or object method.
fix_year
Takes a year and returns it normalized.
FORMATTING METHODS
format_datetime
Given a DateTime object, return it as an RFC2822 compliant string.
use DateTime;
use DateTime::Format::Mail;
my $dt = DateTime->new(
year => 1979, month => 7, day => 16, time_zone => 'UTC'
);
my $mail = DateTime::Format::Mail->format_datetime( $dt );
print $mail, "\n";
# or via an object
my $formatter = DateTime::Format::Mail->new();
my $rfcdate = $formatter->format_datetime( $dt );
print $rfcdate, "\n";THANKS
Dave Rolsky (DROLSKY) for kickstarting the DateTime project.
Roderick A. Anderson for noting where the documentation was incomplete in places.
SUPPORT
Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.
Alternatively, log them via the CPAN RT system via the web or email:
http://perl.dellah.org/rt/dtmail
bug-datetime-format-mail@rt.cpan.orgThis makes it much easier for me to track things and thus means your problem is less likely to be neglected.
LICENSE AND COPYRIGHT
Copyright © Iain Truskett, 2003. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the licenses can be found in the Artistic and COPYING files included with this module, or in perlartistic and perlgpl in Perl 5.8.1 or later.
AUTHOR
Iain Truskett <spoon@cpan.org>
SEE ALSO
datetime@perl.org mailing list.