#!/usr/local/bin/perl
##--------------------------------------------------------------------------##
##  File:
##      $Id: extract-mesg-date,v 1.4 2002/09/15 03:33:08 ehood Exp $
##  Description:
##      See POD below or run program with -man option.
##--------------------------------------------------------------------------##
##  Copyright (C) 2002	    Earl Hood <earl@earlhood.com>
##
##  This program is free software; you can redistribute it and/or modify
##  it under the terms of the GNU General Public License as published by
##  the Free Software Foundation; either version 2 of the License, or
##  (at your option) any later version.
##
##  This program is distributed in the hope that it will be useful,
##  but WITHOUT ANY WARRANTY; without even the implied warranty of
##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
##  GNU General Public License for more details.
##
##  You should have received a copy of the GNU General Public License
##  along with this program; if not, write to the Free Software
##  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
##  02111-1307, USA
##--------------------------------------------------------------------------##

package MHArc::extract_mesg_date;

##--------------------------------------------------------------------------##
# <x-boot-strap>
BEGIN { die qq/CGI use FORBIDDEN!\n/ if (defined($ENV{'GATEWAY_INTERFACE'})); }
my $Dir; BEGIN { $Dir = `dirname $0`; chomp $Dir; }
use lib "$Dir/../lib";  # Add relative lib to search path
# </x-boot-strap>
##--------------------------------------------------------------------------##
# <x-config>
use MHArc::Config;
my $config = MHArc::Config->load("$Dir/../lib/config.sh");
# </x-config>
##--------------------------------------------------------------------------##


use Getopt::Long;
use MHArc::Util qw( usage );
use MHArc::MailUtil qw( extract_date );

require 'mhamain.pl';

my $debug = 0;
my $verbose = 0;
my $time_fmt = '%Y-%m';

MAIN: {
  # Load mhonarc code
  mhonarc::initialize();
  mhonarc::open_archive(
      '-noarg',
      '-quiet',
      '-posixstrftime'
  ) || die qq/ERROR: Unable to load MHonArc library\n/;
  mhonarc::close_archive();

  # Grap command-line options
  my($opt_dfs);
  my $clstatus = GetOptions(
    "debug!"	   => \$debug,
    "datefields=s" => \$opt_dfs,
    "fmt=s"        => \$time_fmt,

    "help"         => \$help,
    "man"          => \$man
  );
  usage(0) unless $clstatus;
  usage(1) if $help;
  usage(2) if $man;

  if ($debug) {
    $MHArc::MailUtil::Debug = 1;
  }

  my @date_fields = ();
  if (defined($opt_dfs)) {
    @date_fields = split(/:/, $opt_dfs);
  } elsif (defined($config->{'MSG_DATE_FIELDS'})) {
    @date_fields = split(/:/, $config->{'MSG_DATE_FIELDS'});
  }
  print "date_fields=@date_fields\n"  if $debug;
  my($fields, $header) = readmail::MAILread_file_header(\*STDIN);
  print mhonarc::time2str(
      $time_fmt, extract_date($fields, @date_fields), 1);

} # End: MAIN

##--------------------------------------------------------------------------##
__END__

=head1 NAME

extract-mesg-date - Retrieve date of a mail message

=head1 SYNOPSIS

  extract-mesg-date [options]

=head1 DESCRIPTION

This program extracts the date of a mail message read in from
standard input.  The date of the message is determined by
examining the following mail header fields in order:
C<Received>, C<Delivery-Date>, C<Date>.  The fields checked
can be changed with the C<-datefields> option.  If no date
is found, than current local time is used.

The date of the message will be echoed to standard output.
The format of the date is controled by the C<-fmt> option.

This program is provided as part of mharc to provide the ability to
to determine the dates of messages during filtering.
Example shell command usage:

  mesg_date=`cat message | extract-mesg-date`

Example useage within a procmail recipe:

  :0 Wi
  MESGDATE_=| extract-mesg-date -fmt '%Y-%m'

  :0:
  $MBOXROOT/.listsadmin/$MESGDATE_

=head1 OPTIONS

=over

=item C<-datefields> I<date-fields-list>

Specifies the message header fields to examine in determining the
date of the message.  Field names are separated by a colon.
For example,

  -datefields x-archive-date:received:date

tells that C<X-Archive-Date>, C<Received>, and C<Date> should
be examined.

=item C<-debug>

Print out debugging information.

B<WARNING: DO NOT USE THIS OPTION WITHIN PROCMAILRC RULES.>

=item C<-fmt> I<time-fmt-string>

The time format to use.  The format string syntax is the same as
defined by C<strftime>.

If C<-fmt> is not specified, than "C<%Y-%m>" is used.

=item C<-help>

Print out help message.

=item C<-man>

Print out the manpage.

=back

=head1 DEPENDENCIES

This program uses functions within MHonArc's library.  Therefore,
MHonArc must be installed on your system and the MHonArc libraries
located within Perl's include path.

=head1 VERSION

$Id: extract-mesg-date,v 1.4 2002/09/15 03:33:08 ehood Exp $

=head1 AUTHOR

Earl Hood, earl@earlhood.com

This program is part of the mharc archiving system and comes with
ABSOLUTELY NO WARRANTY and may be copied only under the terms of
the GNU General Public License, which may be found in the mharc
distribution.

=cut