search-xapian/Xapian/Database.pm

   1 package Search::Xapian::Database;
   2
   3 use 5.006;
   4 use strict;
   5 use warnings;
   6 use Carp;
   7
   8 use Search::Xapian::Enquire;
   9
  10 require DynaLoader;
  11
  12 our @ISA = qw(DynaLoader);
  13
  14 # In a new thread, copy objects of this class to unblessed, undef values.
  15 sub CLONE_SKIP { 1 }
  16
  17 # Preloaded methods go here.
  18
  19 use overload '='  => sub { $_[0]->clone() },
  20              'fallback' => 1;
  21
  22 sub enquire {
  23   my $self = shift;
  24   my $enquire = Search::Xapian::Enquire->new( $self );
  25   if( @_ ) {
  26     $enquire->set_query( @_ );
  27   }
  28   return $enquire;
  29 }
  30
  31
  32 sub clone() {
  33   my $self = shift;
  34   my $class = ref( $self );
  35   my $copy = new2( $self );
  36   bless $copy, $class;
  37   return $copy;
  38 }
  39
  40 sub new() {
  41   my $class = shift;
  42   my $database;
  43   my $invalid_args;
  44   if( scalar(@_) == 1 ) {
  45     my $arg = shift;
  46     my $arg_class = ref( $arg );
  47     if( !$arg_class ) {
  48       $database = new1( $arg );
  49     } elsif( $arg_class eq $class ) {
  50       $database = new2( $arg );
  51     } else {
  52       $invalid_args = 1;
  53     }
  54   } else {
  55     $invalid_args = 1;
  56   }
  57   if( $invalid_args ) {
  58     Carp::carp( "USAGE: $class->new(\$file), $class->new(\$database)" );
  59     exit;
  60   }
  61   bless $database, $class;
  62   return $database;
  63 }
  64
  65 1;
  66
  67 __END__
  68
  69 =head1 NAME
  70
  71 Search::Xapian::Database - Search database object
  72
  73 =head1 DESCRIPTION
  74
  75 This class represents a Xapian database for searching. See
  76 L<Search::Xapian::WritableDatabase> for an object suitable for indexing.
  77 To perform searches, this class works with the L<Search::Xapian::Query>
  78 object.
  79
  80 =head1 METHODS
  81
  82 =over 4
  83
  84 =item new <database>
  85
  86 Class constructor. Can either take a path to an existing database
  87 or another database class as the first parameter
  88
  89 =item clone
  90
  91 Return a clone of this class.
  92
  93 =item add_database
  94
  95 Add an existing database (or group of databases) to those accessed by this
  96 object.
  97
  98 =item reopen
  99
 100 This re-opens the database(s) to the latest available version(s). It can be
 101 used either to make sure the latest results are returned, or to recover from
 102 a Xapian::DatabaseModifiedError.
 103
 104 =item close
 105
 106 Close the database. This also implies a commit() unless a transaction is in
 107 progress.
 108
 109 =item enquire [<query>]
 110
 111 Returns a new L<Search::Xapian::Enquire> object. Any extra
 112 parameters are passed to set_query.
 113
 114 =item get_doccount
 115
 116 Returns the number of document indexed in this database.
 117
 118 =item get_lastdocid
 119
 120 Returns the id of the last used document.
 121
 122 =item get_doclength <doc_id>
 123
 124 Returns the length of a given document.
 125
 126 =item get_document <doc_id>
 127
 128 Returns a L<Search::Xapian::Document> object for the given document.
 129
 130 =item get_avlength
 131
 132 Get the average length of the documents in the database.
 133
 134 =item get_termfreq <term>
 135
 136 Get the number of documents in the database indexed by a given term.
 137
 138 =item term_exists <term>
 139
 140 returns true if this term exists in the database, or false otherwise.
 141
 142 =item get_description
 143
 144 return a description of this object.
 145
 146 =item get_spelling_suggestion
 147
 148 returns a suggested spelling correction.
 149
 150 =item allterms_begin [<prefix>]
 151
 152 Returns a L<Search::Xapian::TermIterator> iterating over the termlist for the
 153 the entire database.  If the optional prefix argument is non-empty, only
 154 terms starting with that string are returned.
 155
 156 =item allterms_end [<prefix>]
 157
 158 Returns a L<Search::Xapian::TermIterator> pointing to the end of the
 159 termlist corresponding to allterms_begin.
 160
 161 =item termlist_begin <docid>
 162
 163 Returns a L<Search::Xapian::TermIterator> pointing to the start of the
 164 termlist for a given document.
 165
 166 =item termlist_end <docid>
 167
 168 Returns a L<Search::Xapian::TermIterator> pointing to the end of the
 169 termlist for a given document.
 170
 171 =item positionlist_begin <docid> <term>
 172
 173 Returns a L<Search::Xapian::PositionIterator> pointing to the
 174 start of the position list for a given term in the given document.
 175
 176 =item positionlist_end <docid> <term>
 177
 178 Returns a L<Search::Xapian::PositionIterator> pointing to the end
 179 of the position list for a given term in the given document.
 180
 181 =item postlist_begin <term>
 182
 183 Returns a L<Search::Xapian::PostingIterator> pointing to the
 184 start of the posting list for a given term.
 185
 186 =item postlist_end <term>
 187
 188 Returns a L<Search::Xapian::PostingIterator> pointing to the
 189 end of the posting list for a given term.
 190
 191 =item keep_alive
 192
 193 Send a "keep-alive" to remote databases to stop them timing out.
 194
 195 =item get_collection_freq <term>
 196
 197 Get the number of elements indexed by a certain term.
 198
 199 =back
 200
 201 =head1 SEE ALSO
 202
 203 L<Search::Xapian>,
 204 L<Search::Xapian::Enquire>,
 205 L<Search::Xapian::WritableDatabase>
 206
 207 =cut