Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.

       o   "loose" should be a true value if you want a	loose parser, else
	   either don't	specify	it or give it a	false value.

       o   "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 A(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 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.

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

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

       perl, DateTime

       RFCs 2822 and 822.

perl v5.32.1			  2016-06-27	     DateTime::Format::Mail(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTORS | PARSING METHODS | FORMATTING METHODS | THANKS FROM SPOON | SUPPORT | LICENCE AND COPYRIGHT | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Format::Mail&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help