Ubuntu Manpage: DateTime::Format::Mail - Convert between DateTime and RFC2822/822 formats

Provided by: libdatetime-format-mail-perl_0.4030-3_all

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.