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

PARSING METHODS

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

FORMATTING METHODS

159   format_datetime
160       Given a "DateTime" object, return it as an RFC2822 compliant string.
161
162           use DateTime;
163           use DateTime::Format::Mail;
164           my $dt = DateTime->new(
165               year => 1979, month => 7, day => 16, time_zone => 'UTC'
166           );
167           my $mail = DateTime::Format::Mail->format_datetime( $dt );
168           print $mail, "\n";
169
170           # or via an object
171           my $formatter = DateTime::Format::Mail->new();
172           my $rfcdate = $formatter->format_datetime( $dt );
173           print $rfcdate, "\n";
174

THANKS FROM SPOON

176       Dave Rolsky (DROLSKY) for kickstarting the DateTime project.
177
178       Roderick A. Anderson for noting where the documentation was incomplete
179       in places.
180
181       Joshua Hoblitt (JHOBLITT) for inspiring me to check what the standard
182       said about interpreting two digit years.
183

SUPPORT

185       Support for this module is provided via the datetime@perl.org email
186       list. See <http://datetime.perl.org/mailing_list.html> for more
187       details.
188
189       Alternatively, log them via the CPAN RT system via the web or email:
190
191           http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime-Format-Mail
192           bug-datetime-format-mail@rt.cpan.org
193
194       This makes it much easier for me to track things and thus means your
195       problem is less likely to be neglected.
196

LICENCE AND COPYRIGHT

198       Copyright © Iain Truskett, 2003. All rights reserved.
199
200       This library is free software; you can redistribute it and/or modify it
201       under the same terms as Perl itself.
202
203       The full text of the licences can be found in the LICENSE file included
204       with this module, or in perlartistic and perlgpl in Perl 5.8.1 or
205       later.
206

AUTHORS

208       Originally written by Iain Truskett <spoon@cpan.org>, who died on
209       December 29, 2003.
210
211       Maintained by Dave Rolsky <autarch@urth.org> from 2003 to 2013.
212
213       Maintained by Philippe Bruhat (BooK) <book@cpan.org> since 2014.
214