[p5sagit/Email-Archive.git] / lib / Email / Archive.pm

package Email::Archive;
use Moo;
use Email::Archive::Storage::DBI;

our $VERSION = '0.02';

has storage => (
  is    => 'rw',
  does  => 'Email::Archive::Storage',
  handles     => {
    store    => 'store',
    retrieve => 'retrieve',
    connect  => 'storage_connect',
  },
  lazy  => 1,
  default => sub { Email::Archive::Storage::DBI->new }
);

1;


__END__

=head1 NAME

Email::Archive - write emails to a database, fetch them

=head1 WARNING!

I only uploaded this to get it out there and kick myself into making it more
useful. As you can see it's not documented or tested yet. I put this together
mostly in one evening in a coffeeshop. It shows in some ways. caveat programmer.

=head1 SYNOPSIS

Email::Archive provides an interface to store emails.

The default storage is Email::Archive::Storage::DBI that uses DBI.
All dokumented examples assume you use this default. For information
on how to use different engines see those modules documentation.

    my $email_archive = Email::Archive->new;
    $email_archive->connect($dsn);
    $email_archive->store($msg);

    $email_archive->retrieve($msg_id);
    $email_archive->search({ from_addr => $from });

=head1 ATTRIBUTES

=head2 storage

Defaults to Email::Archive::Storage::DBI->new.

    my $e = Email::Archive->new;

is equvalent to

    my $storage = Email::Archive::Storage::DBI->new;
    my $e = Email::Archive->new(
        storage => $storage,
    );

This usage will be necessary if a storage different form 
Email::Archive::Storage::DBI is used.

=head1 METHODS

=head2 connect

Takes a DBI connection string as parameter.

    $email_archive->connect('dbi:SQLite:dbname=emails');

For more information see DBI documentation.

If the database schema does not exist it will be deployed automatically by
the connect method.

=head2 store

    $email_archive->store($msg);

Where $msg could be anything feedable to Email::Abstract. That is a raw
email, an Email::MIME object or even an Email::Abstract object.

The message will be stored in the messages table of the connected database.

=head2 search

    $email_archive->search($attributes);

Search the database for emails where $attributes is a hashref containing
the fields to search and the values filter.

    $attributes = { from_addr => $addr };

Will return the first found result as Email::MIME object.

    $email_archive->search({ message_id => $some_id });

Is exactly the same as retrieval by Message-ID.

=head2 retrieve

    $email_archive->retrieve($msg_id);

Retrieve emails by Message-ID. Is a shortcut for

    $email_archive->search({ message_id => $some_id });

=head1 LICENSE

This library may be used under the same terms as Perl itself.

=head1 AUTHOR AND COPYRIGHT

Copyright (c) 2010, 2011 Chris Nehren C<apeiron@cpan.org>.
Commit	Line	Data
8581da38	1	package Email::Archive;
8a5453ad	2	use Moo;
c5f5125c	3	use Email::Archive::Storage::DBI;
8581da38	4
5e15a8a0	5	our $VERSION = '0.02';
5e15a8a0	6
8581da38	7	has storage => (
	8	is => 'rw',
	9	does => 'Email::Archive::Storage',
58854002	10	handles => {
	11	store => 'store',
	12	retrieve => 'retrieve',
	13	connect => 'storage_connect',
	14	},
c5f5125c	15	lazy => 1,
c5f5125c	16	default => sub { Email::Archive::Storage::DBI->new }
8581da38	17	);
8581da38	18
8581da38	19	1;
5e15a8a0	20
5e15a8a0	21
d5161b4d	22	__END__
5e15a8a0	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
20b4be81	34	=head1 SYNOPSIS
20b4be81	35
8e812f39	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 });
20b4be81	111
5e15a8a0	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>.