[scpubgit/stemmatology.git] / lib / Text / Tradition / Directory.pm

package Text::Tradition::Directory;

use strict;
use warnings;
use Moose;
use DBI;
use KiokuDB::GC::Naive;
use KiokuDB::TypeMap;
use KiokuDB::TypeMap::Entry::Naive;
use Text::Tradition::Error;

extends 'KiokuX::Model';

=head1 NAME

Text::Tradition::Directory - a KiokuDB interface for storing and retrieving traditions

=head1 SYNOPSIS

  use Text::Tradition::Directory;
  my $d = Text::Tradition::Directory->new( 
    'dsn' => 'dbi:SQLite:mytraditions.db',
    'extra_args' => { 'create' => 1 },
  );
  
  my $tradition = Text::Tradition->new( @args );
  my $stemma = $tradition->add_stemma( dotfile => $dotfile ); 
  $d->save_tradition( $tradition );
  
  foreach my $id ( $d->traditions ) {
  	print $d->tradition( $id )->name;
  }
    
=head1 DESCRIPTION

Text::Tradition::Directory is an interface for storing and retrieving text traditions and all their data, including an associated stemma hypothesis.  It is an instantiation of a KiokuDB::Model, storing traditions and associated stemmas by UUID.

=head1 METHODS

=head2 new

Returns a Directory object. 

=head2 traditionlist

Returns a hashref mapping of ID => name for all traditions in the directory.

=head2 tradition( $id )

Returns the Text::Tradition object of the given ID.

=head2 save( $tradition )

Writes the given tradition to the database, returning its ID.

=head2 delete( $tradition )

Deletes the given tradition object from the database.
WARNING!! Garbage collection does not yet work. Use this sparingly.

=begin testing

use TryCatch;
use File::Temp;
use Text::Tradition;
use_ok 'Text::Tradition::Directory';

my $fh = File::Temp->new();
my $file = $fh->filename;
$fh->close;
my $dsn = "dbi:SQLite:dbname=$file";
my $uuid;
my $t = Text::Tradition->new( 
	'name'  => 'inline', 
	'input' => 'Tabular',
	'file'  => 't/data/simple.txt',
	);

{
	my $d = Text::Tradition::Directory->new( 'dsn' => $dsn,
		'extra_args' => { 'create' => 1 } );
	is( ref $d, 'Text::Tradition::Directory', "Got directory object" );
	
	my $scope = $d->new_scope;
	$uuid = $d->save( $t );
	ok( $uuid, "Saved test tradition" );
	
	my $s = $t->add_stemma( dotfile => 't/data/simple.dot' );
	ok( $d->save( $t ), "Updated tradition with stemma" );
	is( $d->tradition( $uuid ), $t, "Correct tradition returned for id" );
	is( $d->tradition( $uuid )->stemma(0), $s, "...and it has the correct stemma" );
	try {
		$d->save( $s );
	} catch( Text::Tradition::Error $e ) {
		is( $e->ident, 'database error', "Got exception trying to save stemma directly" );
		like( $e->message, qr/Cannot directly save non-Tradition object/, 
			"Exception has correct message" );
	}
}
my $nt = Text::Tradition->new(
	'name' => 'CX',
	'input' => 'CollateX',
	'file' => 't/data/Collatex-16.xml',
	);
is( ref( $nt ), 'Text::Tradition', "Made new tradition" );

{
	my $f = Text::Tradition::Directory->new( 'dsn' => $dsn );
	my $scope = $f->new_scope;
	is( scalar $f->traditionlist, 1, "Directory index has our tradition" );
	my $nuuid = $f->save( $nt );
	ok( $nuuid, "Stored second tradition" );
	my @tlist = $f->traditionlist;
	is( scalar @tlist, 2, "Directory index has both traditions" );
	my $tf = $f->tradition( $uuid );
	my( $tlobj ) = grep { $_->{'id'} eq $uuid } @tlist;
	is( $tlobj->{'name'}, $tf->name, "Directory index has correct tradition name" );
	is( $tf->name, $t->name, "Retrieved the tradition from a new directory" );
	my $sid = $f->object_to_id( $tf->stemma(0) );
	try {
		$f->tradition( $sid );
	} catch( Text::Tradition::Error $e ) {
		is( $e->ident, 'database error', "Got exception trying to fetch stemma directly" );
		like( $e->message, qr/not a Text::Tradition/, "Exception has correct message" );
	}
	try {
		$f->delete( $sid );
	} catch( Text::Tradition::Error $e ) {
		is( $e->ident, 'database error', "Got exception trying to delete stemma directly" );
		like( $e->message, qr/Cannot directly delete non-Tradition object/, 
			"Exception has correct message" );
	}
	$f->delete( $uuid );
	ok( !$f->exists( $uuid ), "Object is deleted from DB" );
	ok( !$f->exists( $sid ), "Object stemma also deleted from DB" );
	is( scalar $f->traditionlist, 1, "Object is deleted from index" );
}

{
	my $g = Text::Tradition::Directory->new( 'dsn' => $dsn );
	my $scope = $g->new_scope;
	is( scalar $g->traditionlist, 1, "Now one object in new directory index" );
}

=end testing

=cut

has +typemap => (
	is => 'rw',
	isa => 'KiokuDB::TypeMap',
	default => sub { 
		KiokuDB::TypeMap->new(
			isa_entries => {
				"Graph" => KiokuDB::TypeMap::Entry::Naive->new,
				"Graph::AdjacencyMap" => KiokuDB::TypeMap::Entry::Naive->new,
			}
		);
	},
);

# Push some columns into the extra_args
around BUILDARGS => sub {
	my $orig = shift;
	my $class = shift;
	my $args;
	if( @_ == 1 ) {
		$args = $_[0];
	} else {
		$args = { @_ };
	}
	if( $args->{'dsn'} =~ /^dbi/ ) { # We're using Backend::DBI
		my @column_args = ( 'columns',
			[ 'name' => { 'data_type' => 'varchar', 'is_nullable' => 1 } ] );
		my $ea = $args->{'extra_args'};
		if( ref( $ea ) eq 'ARRAY' ) {
			push( @$ea, @column_args );
		} elsif( ref( $ea ) eq 'HASH' ) {
			$ea = { %$ea, @column_args };
		} else {
			$ea = { @column_args };
		}
		$args->{'extra_args'} = $ea;
	}
	return $class->$orig( $args );
};

before [ qw/ store update insert delete / ] => sub {
	my $self = shift;
	my @nontrad;
	foreach my $obj ( @_ ) {
		if( ref( $obj ) && ref( $obj ) ne 'Text::Tradition' ) {
			# Is it an id => Tradition hash?
			if( ref( $obj ) eq 'HASH' && keys( %$obj ) == 1 ) {
				my( $k ) = keys %$obj;
				next if ref( $obj->{$k} ) eq 'Text::Tradition';
			}
			push( @nontrad, $obj );
		}
	}
	if( @nontrad ) {
		throw( "Cannot directly save non-Tradition object of type "
			. ref( $nontrad[0] ) );
	}
};

# TODO Garbage collection doesn't work. Suck it up and live with the 
# inflated DB.
# after delete => sub {
# 	my $self = shift;
# 	my $gc = KiokuDB::GC::Naive->new( backend => $self->directory->backend );
# 	$self->directory->backend->delete( $gc->garbage->members );
# };

sub save {
	my $self = shift;
	return $self->store( @_ );
}

sub tradition {
	my( $self, $id ) = @_;
	my $obj = $self->lookup( $id );
	unless( ref( $obj ) eq 'Text::Tradition' ) {
		throw( "Retrieved object is a " . ref( $obj ) . ", not a Text::Tradition" );
	}
	return $obj;
}

sub traditionlist {
	my $self = shift;
	# If we are using DBI, we can do it the easy way; if not, the hard way.
	# Easy way still involves making a separate DBI connection. Ew.
	my @tlist;
	if( $self->dsn =~ /^dbi/ ) {
		$DB::single = 1;
		my @connection = @{$self->directory->backend->connect_info};
		# Get rid of KiokuDB-specific arg
		pop @connection if scalar @connection > 4;
		$connection[3]->{'sqlite_unicode'} = 1 if $connection[0] =~ /^dbi:SQLite/;
		$connection[3]->{'mysql_enable_utf8'} = 1 if $connection[0] =~ /^dbi:mysql/;
		$connection[3]->{'pg_enable_utf8'} = 1 if $connection[0] =~ /^dbi:Pg/;
		my $dbh = DBI->connect( @connection );
		my $q = $dbh->prepare( 'SELECT id, name from entries WHERE class = "Text::Tradition"' );
		$q->execute();
		while( my @row = $q->fetchrow_array ) {
			push( @tlist, { 'id' => $row[0], 'name' => $row[1] } );
		}
	} else {
		$self->scan( sub { my $o = shift; 
						   push( @tlist, { 'id' => $self->object_to_id( $o ), 
										   'name' => $o->name } ) } );
	}
	return @tlist;
}

sub throw {
	Text::Tradition::Error->throw( 
		'ident' => 'database error',
		'message' => $_[0],
		);
}

1;
	
=head1 LICENSE

This package is free software and is provided "as is" without express
or implied warranty.  You can redistribute it and/or modify it under
the same terms as Perl itself.

=head1 AUTHOR

Tara L Andrews E<lt>aurum@cpan.orgE<gt>
Commit	Line	Data
8d9a1cd8	1	package Text::Tradition::Directory;
	2
	3	use strict;
	4	use warnings;
	5	use Moose;
98a6cab2	6	use DBI;
ad1291ee	7	use KiokuDB::GC::Naive;
8d9a1cd8	8	use KiokuDB::TypeMap;
8d9a1cd8	9	use KiokuDB::TypeMap::Entry::Naive;
861c3e27	10	use Text::Tradition::Error;
8d9a1cd8	11
	12	extends 'KiokuX::Model';
	13
12523041	14	=head1 NAME
	15
	16	Text::Tradition::Directory - a KiokuDB interface for storing and retrieving traditions
	17
	18	=head1 SYNOPSIS
	19
	20	use Text::Tradition::Directory;
	21	my $d = Text::Tradition::Directory->new(
	22	'dsn' => 'dbi:SQLite:mytraditions.db',
	23	'extra_args' => { 'create' => 1 },
	24	);
	25
	26	my $tradition = Text::Tradition->new( @args );
9ba651b9	27	my $stemma = $tradition->add_stemma( dotfile => $dotfile );
12523041	28	$d->save_tradition( $tradition );
12523041	29
	30	foreach my $id ( $d->traditions ) {
	31	print $d->tradition( $id )->name;
12523041	32	}
	33
	34	=head1 DESCRIPTION
	35
	36	Text::Tradition::Directory is an interface for storing and retrieving text traditions and all their data, including an associated stemma hypothesis. It is an instantiation of a KiokuDB::Model, storing traditions and associated stemmas by UUID.
	37
	38	=head1 METHODS
	39
	40	=head2 new
	41
56cf65bd	42	Returns a Directory object.
12523041	43
98a6cab2	44	=head2 traditionlist
12523041	45
98a6cab2	46	Returns a hashref mapping of ID => name for all traditions in the directory.
12523041	47
	48	=head2 tradition( $id )
	49
	50	Returns the Text::Tradition object of the given ID.
	51
56cf65bd	52	=head2 save( $tradition )
12523041	53
56cf65bd	54	Writes the given tradition to the database, returning its ID.
12523041	55
d7ba60b4	56	=head2 delete( $tradition )
	57
	58	Deletes the given tradition object from the database.
	59	WARNING!! Garbage collection does not yet work. Use this sparingly.
	60
12523041	61	=begin testing
12523041	62
861c3e27	63	use TryCatch;
12523041	64	use File::Temp;
12523041	65	use Text::Tradition;
12523041	66	use_ok 'Text::Tradition::Directory';
	67
	68	my $fh = File::Temp->new();
	69	my $file = $fh->filename;
	70	$fh->close;
	71	my $dsn = "dbi:SQLite:dbname=$file";
861c3e27	72	my $uuid;
12523041	73	my $t = Text::Tradition->new(
56cf65bd	74	'name' => 'inline',
	75	'input' => 'Tabular',
	76	'file' => 't/data/simple.txt',
	77	);
56cf65bd	78
861c3e27	79	{
	80	my $d = Text::Tradition::Directory->new( 'dsn' => $dsn,
	81	'extra_args' => { 'create' => 1 } );
	82	is( ref $d, 'Text::Tradition::Directory', "Got directory object" );
	83
	84	my $scope = $d->new_scope;
	85	$uuid = $d->save( $t );
	86	ok( $uuid, "Saved test tradition" );
	87
9ba651b9	88	my $s = $t->add_stemma( dotfile => 't/data/simple.dot' );
861c3e27	89	ok( $d->save( $t ), "Updated tradition with stemma" );
861c3e27	90	is( $d->tradition( $uuid ), $t, "Correct tradition returned for id" );
e0d617e6	91	is( $d->tradition( $uuid )->stemma(0), $s, "...and it has the correct stemma" );
861c3e27	92	try {
	93	$d->save( $s );
	94	} catch( Text::Tradition::Error $e ) {
	95	is( $e->ident, 'database error', "Got exception trying to save stemma directly" );
	96	like( $e->message, qr/Cannot directly save non-Tradition object/,
	97	"Exception has correct message" );
	98	}
	99	}
	100	my $nt = Text::Tradition->new(
	101	'name' => 'CX',
	102	'input' => 'CollateX',
	103	'file' => 't/data/Collatex-16.xml',
	104	);
	105	is( ref( $nt ), 'Text::Tradition', "Made new tradition" );
	106
	107	{
	108	my $f = Text::Tradition::Directory->new( 'dsn' => $dsn );
	109	my $scope = $f->new_scope;
98a6cab2	110	is( scalar $f->traditionlist, 1, "Directory index has our tradition" );
861c3e27	111	my $nuuid = $f->save( $nt );
861c3e27	112	ok( $nuuid, "Stored second tradition" );
98a6cab2	113	my @tlist = $f->traditionlist;
98a6cab2	114	is( scalar @tlist, 2, "Directory index has both traditions" );
861c3e27	115	my $tf = $f->tradition( $uuid );
98a6cab2	116	my( $tlobj ) = grep { $_->{'id'} eq $uuid } @tlist;
98a6cab2	117	is( $tlobj->{'name'}, $tf->name, "Directory index has correct tradition name" );
861c3e27	118	is( $tf->name, $t->name, "Retrieved the tradition from a new directory" );
e0d617e6	119	my $sid = $f->object_to_id( $tf->stemma(0) );
861c3e27	120	try {
	121	$f->tradition( $sid );
	122	} catch( Text::Tradition::Error $e ) {
	123	is( $e->ident, 'database error', "Got exception trying to fetch stemma directly" );
	124	like( $e->message, qr/not a Text::Tradition/, "Exception has correct message" );
	125	}
	126	try {
	127	$f->delete( $sid );
	128	} catch( Text::Tradition::Error $e ) {
	129	is( $e->ident, 'database error', "Got exception trying to delete stemma directly" );
	130	like( $e->message, qr/Cannot directly delete non-Tradition object/,
	131	"Exception has correct message" );
	132	}
	133	$f->delete( $uuid );
	134	ok( !$f->exists( $uuid ), "Object is deleted from DB" );
	135	ok( !$f->exists( $sid ), "Object stemma also deleted from DB" );
98a6cab2	136	is( scalar $f->traditionlist, 1, "Object is deleted from index" );
861c3e27	137	}
861c3e27	138
d7ba60b4	139	{
861c3e27	140	my $g = Text::Tradition::Directory->new( 'dsn' => $dsn );
861c3e27	141	my $scope = $g->new_scope;
98a6cab2	142	is( scalar $g->traditionlist, 1, "Now one object in new directory index" );
861c3e27	143	}
12523041	144
	145	=end testing
	146
	147	=cut
	148
12523041	149	has +typemap => (
8d9a1cd8	150	is => 'rw',
	151	isa => 'KiokuDB::TypeMap',
	152	default => sub {
	153	KiokuDB::TypeMap->new(
	154	isa_entries => {
8d9a1cd8	155	"Graph" => KiokuDB::TypeMap::Entry::Naive->new,
	156	"Graph::AdjacencyMap" => KiokuDB::TypeMap::Entry::Naive->new,
	157	}
	158	);
	159	},
	160	);
	161
98a6cab2	162	# Push some columns into the extra_args
	163	around BUILDARGS => sub {
	164	my $orig = shift;
	165	my $class = shift;
	166	my $args;
	167	if( @_ == 1 ) {
	168	$args = $_[0];
	169	} else {
	170	$args = { @_ };
	171	}
	172	if( $args->{'dsn'} =~ /^dbi/ ) { # We're using Backend::DBI
	173	my @column_args = ( 'columns',
	174	[ 'name' => { 'data_type' => 'varchar', 'is_nullable' => 1 } ] );
	175	my $ea = $args->{'extra_args'};
	176	if( ref( $ea ) eq 'ARRAY' ) {
	177	push( @$ea, @column_args );
	178	} elsif( ref( $ea ) eq 'HASH' ) {
	179	$ea = { %$ea, @column_args };
	180	} else {
	181	$ea = { @column_args };
	182	}
	183	$args->{'extra_args'} = $ea;
	184	}
	185	return $class->$orig( $args );
	186	};
	187
861c3e27	188	before [ qw/ store update insert delete / ] => sub {
8d9a1cd8	189	my $self = shift;
861c3e27	190	my @nontrad;
	191	foreach my $obj ( @_ ) {
	192	if( ref( $obj ) && ref( $obj ) ne 'Text::Tradition' ) {
	193	# Is it an id => Tradition hash?
	194	if( ref( $obj ) eq 'HASH' && keys( %$obj ) == 1 ) {
	195	my( $k ) = keys %$obj;
	196	next if ref( $obj->{$k} ) eq 'Text::Tradition';
8d9a1cd8	197	}
861c3e27	198	push( @nontrad, $obj );
8d9a1cd8	199	}
12523041	200	}
861c3e27	201	if( @nontrad ) {
	202	throw( "Cannot directly save non-Tradition object of type "
	203	. ref( $nontrad[0] ) );
	204	}
	205	};
12523041	206
d7ba60b4	207	# TODO Garbage collection doesn't work. Suck it up and live with the
	208	# inflated DB.
	209	# after delete => sub {
	210	# my $self = shift;
	211	# my $gc = KiokuDB::GC::Naive->new( backend => $self->directory->backend );
	212	# $self->directory->backend->delete( $gc->garbage->members );
	213	# };
56cf65bd	214
56cf65bd	215	sub save {
861c3e27	216	my $self = shift;
861c3e27	217	return $self->store( @_ );
12523041	218	}
12523041	219
56cf65bd	220	sub tradition {
	221	my( $self, $id ) = @_;
	222	my $obj = $self->lookup( $id );
	223	unless( ref( $obj ) eq 'Text::Tradition' ) {
861c3e27	224	throw( "Retrieved object is a " . ref( $obj ) . ", not a Text::Tradition" );
12523041	225	}
56cf65bd	226	return $obj;
12523041	227	}
8d9a1cd8	228
98a6cab2	229	sub traditionlist {
861c3e27	230	my $self = shift;
98a6cab2	231	# If we are using DBI, we can do it the easy way; if not, the hard way.
	232	# Easy way still involves making a separate DBI connection. Ew.
	233	my @tlist;
	234	if( $self->dsn =~ /^dbi/ ) {
	235	$DB::single = 1;
	236	my @connection = @{$self->directory->backend->connect_info};
	237	# Get rid of KiokuDB-specific arg
	238	pop @connection if scalar @connection > 4;
	239	$connection[3]->{'sqlite_unicode'} = 1 if $connection[0] =~ /^dbi:SQLite/;
	240	$connection[3]->{'mysql_enable_utf8'} = 1 if $connection[0] =~ /^dbi:mysql/;
	241	$connection[3]->{'pg_enable_utf8'} = 1 if $connection[0] =~ /^dbi:Pg/;
	242	my $dbh = DBI->connect( @connection );
	243	my $q = $dbh->prepare( 'SELECT id, name from entries WHERE class = "Text::Tradition"' );
	244	$q->execute();
	245	while( my @row = $q->fetchrow_array ) {
	246	push( @tlist, { 'id' => $row[0], 'name' => $row[1] } );
	247	}
	248	} else {
	249	$self->scan( sub { my $o = shift;
	250	push( @tlist, { 'id' => $self->object_to_id( $o ),
	251	'name' => $o->name } ) } );
	252	}
	253	return @tlist;
861c3e27	254	}
	255
	256	sub throw {
	257	Text::Tradition::Error->throw(
	258	'ident' => 'database error',
	259	'message' => $_[0],
	260	);
	261	}
	262
8d9a1cd8	263	1;
12523041	264
027d819c	265	=head1 LICENSE
	266
	267	This package is free software and is provided "as is" without express
	268	or implied warranty. You can redistribute it and/or modify it under
	269	the same terms as Perl itself.
	270
	271	=head1 AUTHOR
	272
	273	Tara L Andrews E<lt>aurum@cpan.orgE<gt>