#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

######################################################################
#
#  This file is part of GNU EPrints 2.
#  
#  Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ.
#  
#  EPrints 2 is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  (at your option) any later version.
#  
#  EPrints 2 is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#  
#  You should have received a copy of the GNU General Public License
#  along with EPrints 2; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
######################################################################

=pod

=head1 NAME

B<explain_sql_tables> - explain what the tables in the SQL database mean

=head1 SYNOPSIS

B<explain_sql_tables> I<repository_id> [B<options>] 

=head1 DESCRIPTION

This script describes what the tables in the SQL database are used for.

=head1 ARGUMENTS

=over 8

=item I<repository_id> 

The ID of the EPrint repository to use.

=back

=head1 OPTIONS

=over 8

=item B<--help>

Print a brief help message and exit.

=item B<--man>

Print the full manual page and then exit.

=item B<--quiet>

Be vewwy vewwy quiet. This option will supress all output unless an error occurs.

=item B<--verbose>

Explain in detail what is going on.
May be repeated for greater effect.

=item B<--version>

Output version information and exit.

=back   

=head1 AUTHOR

This is part of this EPrints 3 system. EPrints 3 is developed by Christopher Gutteridge.

=head1 VERSION

EPrints Version: 3.0

=head1 CONTACT

For more information goto B<http://www.eprints.org/> which give information on mailing lists and the like.

Chris Gutteridge may be contacted at B<support@eprints.org>

Should you need a real world address for some reason, EPrints can be contacted in the real world at

 EPrints c/o Christopher Gutteridge
 Department of Electronics and Computer Science
 University of Southampton
 SO17 1BJ
 United Kingdom

=head1 COPYRIGHT

This file is part of GNU EPrints 2.

Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ.

EPrints 2 is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

EPrints 2 is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with EPrints 2; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


=cut


use Getopt::Long;
use Pod::Usage;
use strict;

use EPrints;

my $xml = 0;
my $version = 0;
my $verbose = 0;
my $quiet = 0;
my $purge = 1;
my $help = 0;
my $man = 0;

GetOptions( 
	'help|?' => \$help,
	'man' => \$man,
	'version' => \$version,
	'verbose+' => \$verbose,
	'silent' => \$quiet,
	'quiet' => \$quiet
) || pod2usage( 2 );
EPrints::Utils::cmd_version( "explain_sql_tables" ) if $version;
pod2usage( 1 ) if $help;
pod2usage( -exitstatus => 0, -verbose => 2 ) if $man;
pod2usage( 2 ) if( scalar @ARGV != 2 && @ARGV != 1 );

my $noise = 1;
$noise = 0 if( $quiet );
$noise = 1+$verbose if( $verbose );

# Set STDOUT to auto flush (without needing a \n)
$|=1;

my $session = new EPrints::Session( 1, $ARGV[0], $noise );
exit( 1 ) unless defined $session;

my $info = {
	user=>"Users table, used to store info on eprints users",
	subject=>"Subject table, used to store the heirarchical subject tree(s)",
	document=>"Document table, used to store documents metadata, for ALL of archive,inbox,etc.",
	saved_search=>"Stored search table, used to store what seaches users have and the frequency of alert emails",
	archive=>"Archive table, used to store eprints in the main archive",
	inbox=>"Inbox table, used to store eprints which have not yet been submitted",
	deletion=>"Deletion table, used to store eprints which have been deleted",
	buffer=>"Buffer table, used to store eprints awaiting approval by editor",
	eprint=>"EPrint table, used to store eprints records",
 };

foreach my $datasetid ( &EPrints::DataSet::get_sql_dataset_ids )
{
	my $dataset = $session->get_repository->get_dataset( $datasetid);
	my $tn = $dataset->get_sql_table_name;
	print row( $tn, $info->{ $dataset->get_sql_table_name} );
	my @fields = $dataset->get_fields( 1 );
	foreach my  $field (@fields)
	{
		if( $field->get_property( "multiple" ) )
		{ 	
		 	my $tid= $dataset->get_sql_sub_table_name( $field );
			my $fid = $tid;
			my $idmsg = '';
			if( $fid =~ s/_id$// ) { $idmsg = 'the "id" part of ';}
			$fid =~ s/^([a-z]*)_//;
			print row( $tid, "Stores ".$idmsg."the multiple field '$fid' of $1" );
			

		}
	}
	foreach my $langid ( @{$session->get_repository->get_conf( "languages" )} )
	{
		print row( $dataset->get_ordervalues_table_name( $langid ), "Used to sort results from the $tn dataset (generated by indexer from other tables)" );
	}
	print row( $tn."__index","used to store index codes (freetext search) for $tn (generated by indexer from other tables)" );
	print row( $tn."__rindex","used to store the reverse index codes (freetext search) for $tn. This is needed for removing indexed items. (generated by indexer from other tables)" );
	print row( $tn."__index_grep", "used to store filter codes (some name searches) for $tn (generated by indexer from other tables)" );
	print "\n";
}
print row( "counters", "used to store highest identifier for eprints and users etc." );
print row( "version", "used to store compatability number for tables (to check they work with current eprints install)" );
print row( "index_queue", "used to queue all the fields which currently need reindexing" );
print row( "cachemap", "used to store ids of temporary search results table ids so they can be erased later" );
print row( "cache****", "(where * are digits) used to store cached searches for a little while" );

$session->terminate();

sub row
{
	my( $table, $desc ) = @_;

	my $r = $table."\n";
	my $wrap = 70;
	while( length( $desc )>$wrap )
	{
		$desc =~ s/^(.{1,$wrap})\s//;
		$r .= "      ".$1."\n";
	}
	$r .= "      ".$desc."\n";

	return $r;
}