DateTime::Format::Mail(3pm)

1DateTime::Format::Mail(U3s)er Contributed Perl DocumentatDiaotneTime::Format::Mail(3)
2
3
4

NAME

6       DateTime::Format::Mail - Convert between DateTime and RFC2822/822 for‐
7       mats
8

SYNOPSIS

10           use DateTime::Format::Mail;
11
12           # From RFC2822 via class method:
13
14           my $datetime = DateTime::Format::Mail->parse_datetime(
15               "Sat, 29 Mar 2003 22:11:18 -0800"
16           );
17           print $datetime->ymd('.'); # "2003.03.29"
18
19           #  or via an object
20
21           my $pf = DateTime::Format::Mail->new();
22           print $pf->parse_datetime(
23               "Fri, 23 Nov 2001 21:57:24 -0600"
24           )->ymd; # "2001-11-23"
25
26           # Back to RFC2822 date
27
28           use DateTime;
29           my $dt = DateTime->new(
30               year => 1979, month => 7, day => 16,
31               hour => 16, minute => 45, second => 20,
32               time_zone => "Australia/Sydney"
33           );
34           my $str = DateTime::Format::Mail->format_datetime( $dt );
35           print $str; # "Mon, 16 Jul 1979 16:45:20 +1000"
36
37           # or via an object
38           $str = $pf->format_datetime( $dt );
39           print $str; # "Mon, 16 Jul 1979 16:45:20 +1000"
40

DESCRIPTION

42       RFCs 2822 and 822 specify date formats to be used by email. This module
43       parses and emits such dates.
44
45       RFC2822 (April 2001) introduces a slightly different format of date
46       than that used by RFC822 (August 1982). The main correction is that the
47       preferred format is more limited, and thus easier to parse programmati‐
48       cally.
49
50       Despite the ease of generating and parsing perfectly valid RFC822 and
51       RFC2822 people still get it wrong. So this module provides four things
52       for those handling mail dates:
53
54       1   A strict parser that will only accept RFC2822 dates, so you can see
55           where you're right.
56
57       2   A strict formatter, so you can generate the right stuff to begin
58           with.
59
60       3   A loose parser, so you can take the misbegotten output from other
61           programs and turn it into something useful.  This includes various
62           minor errors as well as some somewhat more bizarre mistakes. The
63           file t/sample_dates in this module's distribution should give you
64           an idea of what's valid, while t/invalid.t should do the same for
65           what's not. Those regarded as invalid are just a bit too strange to
66           allow.
67
68       4   Interoperation with the rest of the DateTime suite. These are a
69           collection of modules to handle dates in a modern and accurate
70           fashion. In particular, they make it trivial to parse, manipulate
71           and then format dates. Shifting timezones is a doddle, and convert‐
72           ing between formats is a cinch.
73
74       As a future direction, I'm contemplating an even stricter parser that
75       will only accept dates with no obsolete elements.
76

CONSTRUCTORS

78       new
79
80       Creates a new "DateTime::Format::Mail" instance. This is generally not
81       required for simple operations. If you wish to use a different parsing
82       style from the default, strict, parser then you'll need to create an
83       object.
84
85          my $parser = DateTime::Format::Mail->new()
86          my $copy = $parser->new();
87
88       If called on an existing object then it clones the object.
89
90       It has two optional named parameters.
91
92       ·   "loose" should be a true value if you want a loose parser, else
93           either don't specify it or give it a false value.
94
95       ·   "year_cutoff" should be an integer greater than or equal to zero
96           specifying the cutoff year. See "set_year_cutoff" for details.
97
98           my $loose = DateTime::Format::Mail->new( loose => 1 );
99
100           my $post_2049 = DateTime::Format::Mail->new(
101               year_cutoff => 60
102           );
103
104       clone
105
106       For those who prefer to explicitly clone via a method called "clone()".
107       If called as a class method it will die.
108
109          my $clone = $original->clone();
110

PARSING METHODS

112       These methods work on either our objects or as class methods.
113
114       loose, strict
115
116       These methods set the parsing strictness.
117
118           my $parser = DateTime::Format::Mail->new;
119           $parser->loose;
120           $parser->strict; # (the default)
121
122           my $p = DateTime::Format::Mail->new->loose;
123
124       parse_datetime
125
126       Given an RFC2822 or 822 datetime string, return a "DateTime" object
127       representing that date and time. Unparseable strings will cause the
128       method to die.
129
130       See the synopsis for examples.
131
132       set_year_cutoff
133
134       Two digit years are treated as valid in the loose translation and are
135       translated up to a 19xx or 20xx figure. By default, following the spec‐
136       ification of RFC2822, if the year is greater than '49', it's treated as
137       being in the 20th century (19xx).  If lower, or equal, then the 21st
138       (20xx). That is, 50 becomes 1950 while 49 is 2049.
139
140       "set_year_cutoff()" allows you to modify this behaviour by specifying a
141       different cutoff.
142
143       The return value is the object itself.
144
145           $parser->set_year_cutoff( 60 );
146
147       year_cutoff
148
149       Returns the current cutoff. Can be used as either a class or object
150       method.
151
152           my $cutoff = $parser->set_year_cutoff;
153
154       default_cutoff
155
156       Returns the default cutoff. A useful method to override for subclasses.
157
158           my $default = $parser->default_cutoff;
159
160       fix_year
161
162       Takes a year and returns it normalized.
163
164          my $fixed = $parser->fix_year( 3 );
165

FORMATTING METHODS

167       format_datetime
168
169       Given a "DateTime" object, return it as an RFC2822 compliant string.
170
171           use DateTime;
172           use DateTime::Format::Mail;
173           my $dt = DateTime->new(
174               year => 1979, month => 7, day => 16, time_zone => 'UTC'
175           );
176           my $mail = DateTime::Format::Mail->format_datetime( $dt );
177           print $mail, "\n";
178
179           # or via an object
180           my $formatter = DateTime::Format::Mail->new();
181           my $rfcdate = $formatter->format_datetime( $dt );
182           print $rfcdate, "\n";
183

THANKS

185       Dave Rolsky (DROLSKY) for kickstarting the DateTime project.
186
187       Roderick A. Anderson for noting where the documentation was incomplete
188       in places.
189
190       Joshua Hoblitt (JHOBLITT) for inspiring me to check what the standard
191       said about interpreting two digit years.
192

SUPPORT

194       Support for this module is provided via the datetime@perl.org email
195       list. See <http://datetime.perl.org/mailing_list.html> for more
196       details.
197
198       Alternatively, log them via the CPAN RT system via the web or email:
199
200           http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime%3A%3AFormat%3A%3AMail
201           bug-datetime-format-mail@rt.cpan.org
202
203       This makes it much easier for me to track things and thus means your
204       problem is less likely to be neglected.
205

LICENCE AND COPYRIGHT

207       Copyright (C) Iain Truskett, 2003. All rights reserved.
208
209       This library is free software; you can redistribute it and/or modify it
210       under the same terms as Perl itself.
211
212       The full text of the licences can be found in the Artistic and COPYING
213       files included with this module, or in perlartistic and perlgpl in Perl
214       5.8.1 or later.
215

AUTHOR

217       Originally written by Iain Truskett <spoon@cpan.org>, who died on
218       December 29, 2003.
219
220       Maintained by Dave Rolsky <autarch@urth.org>.
221