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