lib/Email/Archive.pm

   1 package Email::Archive;
   2 use Moo;
   3 use Email::Archive::Storage::DBI;
   4
   5 our $VERSION = '0.02';
   6
   7 has storage => (
   8   is    => 'rw',
   9   does  => 'Email::Archive::Storage',
  10   handles     => {
  11     store    => 'store',
  12     retrieve => 'retrieve',
  13     connect  => 'storage_connect',
  14   },
  15   lazy  => 1,
  16   default => sub { Email::Archive::Storage::DBI->new }
  17 );
  18
  19 1;
  20
  21
  22 __END__
  23
  24 =head1 NAME
  25
  26 Email::Archive - write emails to a database, fetch them
  27
  28 =head1 WARNING!
  29
  30 I only uploaded this to get it out there and kick myself into making it more
  31 useful. As you can see it's not documented or tested yet. I put this together
  32 mostly in one evening in a coffeeshop. It shows in some ways. caveat programmer.
  33
  34 =head1 SYNOPSIS
  35
  36 Email::Archive provides an interface to store emails.
  37
  38 The default storage is Email::Archive::Storage::DBI that uses DBI.
  39 All dokumented examples assume you use this default. For information
  40 on how to use different engines see those modules documentation.
  41
  42     my $email_archive = Email::Archive->new;
  43     $email_archive->connect($dsn);
  44     $email_archive->store($msg);
  45
  46     $email_archive->retrieve($msg_id);
  47     $email_archive->search({ from_addr => $from });
  48
  49 =head1 ATTRIBUTES
  50
  51 =head2 storage
  52
  53 Defaults to Email::Archive::Storage::DBI->new.
  54
  55     my $e = Email::Archive->new;
  56
  57 is equvalent to
  58
  59     my $storage = Email::Archive::Storage::DBI->new;
  60     my $e = Email::Archive->new(
  61         storage => $storage,
  62     );
  63
  64 This usage will be necessary if a storage different form
  65 Email::Archive::Storage::DBI is used.
  66
  67 =head1 METHODS
  68
  69 =head2 connect
  70
  71 Takes a DBI connection string as parameter.
  72
  73     $email_archive->connect('dbi:SQLite:dbname=emails');
  74
  75 For more information see DBI documentation.
  76
  77 If the database schema does not exist it will be deployed automatically by
  78 the connect method.
  79
  80 =head2 store
  81
  82     $email_archive->store($msg);
  83
  84 Where $msg could be anything feedable to Email::Abstract. That is a raw
  85 email, an Email::MIME object or even an Email::Abstract object.
  86
  87 The message will be stored in the messages table of the connected database.
  88
  89 =head2 search
  90
  91     $email_archive->search($attributes);
  92
  93 Search the database for emails where $attributes is a hashref containing
  94 the fields to search and the values filter.
  95
  96     $attributes = { from_addr => $addr };
  97
  98 Will return the first found result as Email::MIME object.
  99
 100     $email_archive->search({ message_id => $some_id });
 101
 102 Is exactly the same as retrieval by Message-ID.
 103
 104 =head2 retrieve
 105
 106     $email_archive->retrieve($msg_id);
 107
 108 Retrieve emails by Message-ID. Is a shortcut for
 109
 110     $email_archive->search({ message_id => $some_id });
 111
 112 =head1 LICENSE
 113
 114 This library may be used under the same terms as Perl itself.
 115
 116 =head1 AUTHOR AND COPYRIGHT
 117
 118 Copyright (c) 2010, 2011 Chris Nehren C<apeiron@cpan.org>.