DateTime::Format::Mail - phpMan

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 AT 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 AT rt.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 AT cpan.org>, who died on
    December 29, 2003.

    Maintained by Dave Rolsky <autarch AT urth.org> from 2003 to 2013.

    Maintained by Philippe Bruhat (BooK) <book AT cpan.org> since 2014.

SEE ALSO
    "datetime AT perl.org" mailing list.

    <http://datetime.perl.org/>

    perl, DateTime

    RFCs 2822 and 822.