Email::Date - Find and Format Date Headers

Email-Date documentation Contained in the Email-Date distribution.

Index

Code Index:

NAME

Top

Email::Date - Find and Format Date Headers

SYNOPSIS

Top

  use Email::Date;

  my $email = join '', <>;
  my $date  = find_date($email);
  print $date->ymd;

  my $header = format_date($date->epoch);

  Email::Simple->create(
      header => [
          Date => $header,
      ],
      body => '...',
  );

DESCRIPTION

Top

RFC 2822 defines the Date: header. It declares the header a required part of an email message. The syntax for date headers is clearly laid out. Stil, even a perfectly planned world has storms. The truth is, many programs get it wrong. Very wrong. Or, they don't include a Date: header at all. This often forces you to look elsewhere for the date, and hoping to find something.

For this reason, the tedious process of looking for a valid date has been encapsulated in this software. Further, the process of creating RFC compliant date strings is also found in this software.

FUNCTIONS

find_date
  my $time_piece = find_date $email;

find_date accepts an email message in any format Email::Abstract can understand. It looks through the email message and finds a date, converting it to a Time::Piece object.

If it can't find a date, it returns false.

find_date is exported by default.

format_date
  my $date = format_date; # now
  my $date = format_date( time - 60*60 ); # one hour ago

format_date accepts an epoch value, such as the one returned by time. It returns a string representing the date and time of the input, as specified in RFC 2822. If no input value is provided, the current value of time is used.

format_date is exported by default.

format_gmdate
  my $date = format_gmdate;

format_gmdate is identical to format_date, but it will return a string indicating the time in Greenwich Mean Time, rather than local time.

format_gmdate is exported on demand, but not by default.

PERL EMAIL PROJECT

Top

This module is maintained by the Perl Email Project

http://emailproject.perl.org/wiki/Email::Date

SEE ALSO

Top

Email::Abstract, Time::Piece, Date::Parse, perl.

AUTHOR

Top

Casey West, <casey@geeknest.com>.

Ricardo SIGNES, <rjbs@cpan.org>.

COPYRIGHT

Top

  Copyright (c) 2004 Casey West.  All rights reserved.
  This module is free software; you can redistribute it and/or modify it
  under the same terms as Perl itself.
Email-Date documentation Contained in the Email-Date distribution. 
package Email::Date;
use strict;

use vars qw[$VERSION @EXPORT @EXPORT_OK];
$VERSION = '1.103';
@EXPORT    = qw[find_date format_date];
@EXPORT_OK = qw[format_gmdate];

use base qw[Exporter];
use Date::Parse ();
use Email::Date::Format;
use Time::Piece ();


sub find_date {
    require Email::Abstract;
    my $email = Email::Abstract->new($_[0]);

    my $date = $email->get_header('Date')
            || _find_date_received($email->get_header('Received'))
            || $email->get_header('Resent-Date');

    return unless $date and length $date;

    Time::Piece->new(Date::Parse::str2time $date);
}

sub _find_date_received {
    return unless defined $_[0] and length $_[0];
    my $date = pop;
    $date =~ s/.+;//;
    $date;
}


BEGIN {
  *format_date   = \&Email::Date::Format::email_date;
  *format_gmdate = \&Email::Date::Format::email_gmdate;
};

1;

__END__