#!/usr/bin/perl -w
#
# Get a message on the STDIN and make vcards from the sender and
# recipient addresses, then feed the vcards to kaddressbook through
# dcop.
#
# This program is meant to be called as a KMail filter.  KAddressBook
# must be running.
#
# perldoc kbbdb for usage, or just read the source.
#
# Raj Mathur <raju@kandalaya.org>, Fri Sep 29 10:15:39 IST 2006
#
# This program is available under the terms of the GNU General Public
# License v2.  If you don't have a copy of the GPL you suck anyway.
#
use strict ;

=head1 NAME

kbbdb - automatically add e-mail addresses to KDE address book

=head1 SYNOPSIS

kbbdb [--sender] [--all] [--recipients]

=head1 DESCRIPTION

kbbdb does the following:

=over

=item * Parses an e-mail message on it's standard input and extracts the
I<From>, I<To>, I<CC>, I<Resent-To> and I<Resent-CC> headers.

=item * Converts the headers to a temporary VCARD file with addresses
and (if available) names.

=item * Invokes the KAddressBook dcop interface with the
I<importVCard> command to import the VCARD file into the address book.

=back

=head1 OPTIONS

B<kbbdb> accepts the following options:

=over

=item B<--sender>

Only snarf the sender address.  This is the default.

=item B<--recipients>

Snarf all recipient addresses in the message.  These include all
addresses found in the I<To>, I<CC>, I<Resent-To> and
I<Resent-CC> headers. [Is there a Resent-CC header?]

=item B<--all>

Snarf all addresses in the message.  This is equivalent to specifying
both B<--sender> and B<--recipients>.

=back

=head1 USAGE

You will have to create a KDE I<kmail> filter to use B<kbbdb>.  The
steps for creating the filter are:

=over

=item * Right-click on a message, select I<Create Filter>/I<Filter on
From>.

=item * In the Filter Rules window, click the I<Rename> button and change
the name to B<BBDB-From>.

=item * In the filter Criteria section, select I<Match all of the
following>.  Select I<From is not in address book>.

=item * in the Filter Actions section, select I<Execute Command>.  Put
the path to kbbdb in the text box, followed by an ampersand B<&>,
e.g. B<~/bin/kbbdb &>.

=item * Select the Advanced tab.  Uncheck the I<If this fiter matches,
stop processing here> option.

=item * Click the the I<Apply> and I<OK> buttons.

=back

You can create a similar filter on To addresses that aren't in the
address book.

=head1 NOTES

kaddressbook must be running for this command to work.  If
kaddressbook isn't running B<kbbdb> will probably just fail silently.

=head1 DEPENDENCIES

B<kbbdb> uses the I<Mail::Header> and I<Mail::Address> modules.  On
Debian, these are available in the I<libmailtools-perl> package.

=head1 AUTHOR & COPYRIGHT

B<kbbdb> is written by Raj Mathur <raju@kandalaya.org>.  B<kbbdb> is
copyright 2006, Raj Mathur.  B<kbbdb> is available under the terms of
the GNU General Public License.  If you don't have a copy of the GNU
General Public License, you suck.

=cut

use Mail::Header ;
use Mail::Address ;
#
# Process options
#
my
  @wanted_headers = () ;
my
  $option ;
while ( $option = shift ( @ARGV ) )
{
  push ( @wanted_headers , 'From' )
    if $option eq '--sender' ;
  push ( @wanted_headers , 'To' , 'CC' , 'Resent-To' , 'Resent-CC' )
    if $option eq '--recipients' ;
  push ( @wanted_headers , 'From' , 'To' , 'CC' , 'Resent-To' , 'Resent-CC' )
    if $option eq '--all' ;
}
push ( @wanted_headers , 'From' )
  unless @wanted_headers ;
#
# Read and parse message from STDIN
#
my
  $headers = new Mail::Header ( \*STDIN ) ;
my
  @raw_addresses ;
my
  @addresses ;
#
# Get the headers in raw format.
foreach my $i ( @wanted_headers )
{
  push ( @raw_addresses , $headers -> get ( $i ) ) ;
}
#
# Now parse each header to get name and address out.
foreach my $i ( @raw_addresses )
{
  push ( @addresses , Mail::Address -> parse ( $i ) ) ;
}
my
  $tempfile ;
if ( @addresses )
{
  $tempfile = "/tmp/vcard$$" ;
  open ( TEMP , ">$tempfile" )
    or die "Unable to create $tempfile: $!\n" ;
}
foreach my $i ( @addresses )
{
  my
    $name = $i -> name ;
  my
    $address = $i -> address ;
  if ( defined ( $address ) )
  {
    print TEMP <<ENDPRINT ;
BEGIN:VCARD
VERSION:2.1
EMAIL;WORK:$address
ENDPRINT
    print TEMP "N:$name\n"
      if defined ( $name ) ;
    print TEMP <<ENDPRINT ;
END:VCARD
ENDPRINT
  }
}
#
# Send the file to KAddressBook
if ( @addresses )
{
  close ( TEMP ) ;
  system ( "dcop kaddressbook KAddressBookIface importVCard file://$tempfile" ) ;
  unlink ( $tempfile ) ;
}
exit ( 0 ) ;