.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DateTime::Format::Mail 3pm" .TH DateTime::Format::Mail 3pm "2016-07-01" "perl v5.22.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" DateTime::Format::Mail \- Convert between DateTime and RFC2822/822 formats .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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(\*(Aq.\*(Aq); # "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" .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" RFCs 2822 and 822 specify date formats to be used by email. This module parses and emits such dates. .PP \&\s-1RFC2822 \s0(April 2001) introduces a slightly different format of date than that used by \s-1RFC822 \s0(August 1982). The main correction is that the preferred format is more limited, and thus easier to parse programmatically. .PP Despite the ease of generating and parsing perfectly valid \s-1RFC822\s0 and \&\s-1RFC2822\s0 people still get it wrong. So this module provides four things for those handling mail dates: .IP "1." 4 A strict parser that will only accept \s-1RFC2822\s0 dates, so you can see where you're right. .IP "2." 4 A strict formatter, so you can generate the right stuff to begin with. .IP "3." 4 A \fIloose\fR 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 \fIt/sample_dates\fR in this module's distribution should give you an idea of what's valid, while \&\fIt/invalid.t\fR should do the same for what's not. Those regarded as invalid are just a bit \fBtoo\fR strange to allow. .IP "4." 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. .PP As a future direction, I'm contemplating an even stricter parser that will only accept dates with no obsolete elements. .SH "CONSTRUCTORS" .IX Header "CONSTRUCTORS" .SS "new" .IX Subsection "new" Creates a new \f(CW\*(C`DateTime::Format::Mail\*(C'\fR 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. .PP .Vb 2 \& my $parser = DateTime::Format::Mail\->new() \& my $copy = $parser\->new(); .Ve .PP If called on an existing object then it clones the object. .PP It has two optional named parameters. .IP "\(bu" 4 \&\f(CW\*(C`loose\*(C'\fR should be a true value if you want a loose parser, else either don't specify it or give it a false value. .IP "\(bu" 4 \&\f(CW\*(C`year_cutoff\*(C'\fR should be an integer greater than or equal to zero specifying the cutoff year. See \*(L"set_year_cutoff\*(R" for details. .PP .Vb 1 \& my $loose = DateTime::Format::Mail\->new( loose => 1 ); \& \& my $post_2049 = DateTime::Format::Mail\->new( \& year_cutoff => 60 \& ); .Ve .SS "clone" .IX Subsection "clone" For those who prefer to explicitly clone via a method called \f(CW\*(C`clone()\*(C'\fR. If called as a class method it will die. .PP .Vb 1 \& my $clone = $original\->clone(); .Ve .SH "PARSING METHODS" .IX Header "PARSING METHODS" These methods work on either our objects or as class methods. .SS "loose, strict" .IX Subsection "loose, strict" These methods set the parsing strictness. .PP .Vb 3 \& my $parser = DateTime::Format::Mail\->new; \& $parser\->loose; \& $parser\->strict; # (the default) \& \& my $p = DateTime::Format::Mail\->new\->loose; .Ve .SS "parse_datetime" .IX Subsection "parse_datetime" Given an \s-1RFC2822\s0 or 822 datetime string, return a \f(CW\*(C`DateTime\*(C'\fR object representing that date and time. Unparseable strings will cause the method to die. .PP See the synopsis for examples. .SS "set_year_cutoff" .IX Subsection "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 \s-1RFC2822,\s0 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. .PP \&\f(CW\*(C`set_year_cutoff()\*(C'\fR allows you to modify this behaviour by specifying a different cutoff. .PP The return value is the object itself. .PP .Vb 1 \& $parser\->set_year_cutoff( 60 ); .Ve .SS "year_cutoff" .IX Subsection "year_cutoff" Returns the current cutoff. Can be used as either a class or object method. .PP .Vb 1 \& my $cutoff = $parser\->set_year_cutoff; .Ve .SS "default_cutoff" .IX Subsection "default_cutoff" Returns the default cutoff. A useful method to override for subclasses. .PP .Vb 1 \& my $default = $parser\->default_cutoff; .Ve .SS "fix_year" .IX Subsection "fix_year" Takes a year and returns it normalized. .PP .Vb 1 \& my $fixed = $parser\->fix_year( 3 ); .Ve .SH "FORMATTING METHODS" .IX Header "FORMATTING METHODS" .SS "format_datetime" .IX Subsection "format_datetime" Given a \f(CW\*(C`DateTime\*(C'\fR object, return it as an \s-1RFC2822\s0 compliant string. .PP .Vb 7 \& use DateTime; \& use DateTime::Format::Mail; \& my $dt = DateTime\->new( \& year => 1979, month => 7, day => 16, time_zone => \*(AqUTC\*(Aq \& ); \& my $mail = DateTime::Format::Mail\->format_datetime( $dt ); \& print $mail, "\en"; \& \& # or via an object \& my $formatter = DateTime::Format::Mail\->new(); \& my $rfcdate = $formatter\->format_datetime( $dt ); \& print $rfcdate, "\en"; .Ve .SH "THANKS FROM SPOON" .IX Header "THANKS FROM SPOON" Dave Rolsky (\s-1DROLSKY\s0) for kickstarting the DateTime project. .PP Roderick A. Anderson for noting where the documentation was incomplete in places. .PP Joshua Hoblitt (\s-1JHOBLITT\s0) for inspiring me to check what the standard said about interpreting two digit years. .SH "SUPPORT" .IX Header "SUPPORT" Support for this module is provided via the datetime@perl.org email list. See for more details. .PP Alternatively, log them via the \s-1CPAN RT\s0 system via the web or email: .PP .Vb 2 \& http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime\-Format\-Mail \& bug\-datetime\-format\-mail@rt.cpan.org .Ve .PP This makes it much easier for me to track things and thus means your problem is less likely to be neglected. .SH "LICENCE AND COPYRIGHT" .IX Header "LICENCE AND COPYRIGHT" Copyright © Iain Truskett, 2003. All rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The full text of the licences can be found in the \fI\s-1LICENSE\s0\fR file included with this module, or in perlartistic and perlgpl in Perl 5.8.1 or later. .SH "AUTHORS" .IX Header "AUTHORS" Originally written by Iain Truskett , who died on December 29, 2003. .PP Maintained by Dave Rolsky from 2003 to 2013. .PP Maintained by Philippe Bruhat (BooK) since 2014. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\f(CW\*(C`datetime@perl.org\*(C'\fR mailing list. .PP .PP perl, DateTime .PP RFCs 2822 and 822.