DateTime::Format::Mail man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

DateTime::Format::MailUser Contributed Perl DocumentaDateTime::Format::Mail(3)

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
       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%3A%3AFormat%3A%3AMail
	   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 (C) 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 Artistic and COPYING
       files included with this module, or in perlartistic and perlgpl in Perl
       5.8.1 or later.

AUTHOR
       Originally written by Iain Truskett <spoon@cpan.org>, who died on
       December 29, 2003.

       Maintained by Dave Rolsky <autarch@urth.org>.

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

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

       perl, DateTime

       RFCs 2822 and 822.

perl v5.14.2			  2012-01-14	     DateTime::Format::Mail(3)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net