DateTime::Format::Mail
Section: User Contributed Perl Documentation (3pm)
Updated: 2022-11-27
Index
Return to Main Contents
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
RFCs 2822 and 822 specify date formats to be used by email. This
module parses and emits such dates.
RFC2822 (April 2001) introduces a slightly different format of
date than that used by RFC822 (August 1982). The main correction
is that the preferred format is more limited, and thus easier to
parse programmatically.
Despite the ease of generating and parsing perfectly valid RFC822 and
RFC2822 people still get it wrong. So this module provides four things
for those handling mail dates:
- 1.
-
A strict parser that will only accept RFC2822 dates, so you can
see where you're right.
- 2.
-
A strict formatter, so you can generate the right stuff
to begin with.
- 3.
-
A loose parser, so you can take the misbegotten output
from other programs and turn it into something useful.
This includes various minor errors as well as some somewhat more
bizarre mistakes. The file t/sample_dates in this module's
distribution should give you an idea of what's valid, while
t/invalid.t should do the same for what's not. Those regarded
as invalid are just a bit too strange to allow.
- 4.
-
Interoperation with the rest of the DateTime suite. These are
a collection of modules to handle dates in a modern and accurate
fashion. In particular, they make it trivial to parse, manipulate
and then format dates. Shifting timezones is a doddle, and
converting between formats is a cinch.
As a future direction, I'm contemplating an even stricter
parser that will only accept dates with no obsolete elements.
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, strict, parser 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 two optional named parameters.
- •
-
"loose" should be a true value if you want a loose parser,
else either don't specify it or give it a false value.
- •
-
"year_cutoff" should be an integer greater than or equal to zero
specifying the cutoff year. See ``set_year_cutoff'' for details.
my $loose = DateTime::Format::Mail->new( loose => 1 );
my $post_2049 = DateTime::Format::Mail->new(
year_cutoff => 60
);
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, following the
specification of RFC2822, if the year is
greater than '49', it's treated as being in the 20th century (19xx).
If lower, or equal, then the 21st (20xx). That is, 50 becomes
1950 while 49 is 2049.
"set_year_cutoff()" allows you to modify this behaviour by specifying
a different cutoff.
The return value is the object itself.
$parser->set_year_cutoff( 60 );
year_cutoff
Returns the current cutoff. Can be used as either a class or object method.
my $cutoff = $parser->set_year_cutoff;
default_cutoff
Returns the default cutoff. A useful method to override for
subclasses.
my $default = $parser->default_cutoff;
fix_year
Takes a year and returns it normalized.
my $fixed = $parser->fix_year( 3 );
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 FROM SPOON
Dave Rolsky (DROLSKY) for kickstarting the DateTime project.
Roderick A. Anderson for noting where the documentation was incomplete
in places.
Joshua Hoblitt (JHOBLITT) for inspiring me to check what the
standard said about interpreting two digit years.
SUPPORT
Support for this module is provided via the datetime@perl.org email
list. See <http://datetime.perl.org/mailing_list.html> for more details.
Alternatively, log them via the CPAN RT system via the web or email:
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime-Format-Mail
bug-datetime-format-mail@rt.cpan.org
This makes it much easier for me to track things and thus means
your problem is less likely to be neglected.
LICENCE 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 licences can be found in the LICENSE file
included with this module, or in perlartistic and
perlgpl in Perl 5.8.1 or later.
AUTHORS
Originally written by Iain Truskett <spoon@cpan.org>, who died on
December 29, 2003.
Maintained by Dave Rolsky <autarch@urth.org> from 2003 to 2013.
Maintained by Philippe Bruhat (BooK) <book@cpan.org> since 2014.
SEE ALSO
"datetime@perl.org" mailing list.
<http://datetime.perl.org/>
perl, DateTime
RFCs 2822 and 822.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- CONSTRUCTORS
-
- new
-
- clone
-
- PARSING METHODS
-
- loose, strict
-
- parse_datetime
-
- set_year_cutoff
-
- year_cutoff
-
- default_cutoff
-
- fix_year
-
- FORMATTING METHODS
-
- format_datetime
-
- THANKS FROM SPOON
-
- SUPPORT
-
- LICENCE AND COPYRIGHT
-
- AUTHORS
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 14:54:45 GMT, April 20, 2024