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

package Text::Tradition::Directory;

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