Mailing List Archive

Author: creamyg
Date: 2008-07-29 17:58:24 -0700 (Tue, 29 Jul 2008)
New Revision: 3668

Modified:
trunk/c_src/KinoSearch/Search/Searchable.bp
trunk/c_src/KinoSearch/Searcher.bp
trunk/c_src/KinoSearch/Searcher.c
trunk/perl/lib/KinoSearch/Search/Searchable.pm
trunk/perl/lib/KinoSearch/Searcher.pm
Log:
Expose Searchable as a public class, including Collect(). Migrate Searcher's
docs to its .bp file. Port Searcher_Get_Reader() to C. Correct a couple
flaws in Searchable's docs.


Modified: trunk/c_src/KinoSearch/Search/Searchable.bp
===================================================================
--- trunk/c_src/KinoSearch/Search/Searchable.bp 2008-07-30 00:57:24 UTC (rev 3667)
+++ trunk/c_src/KinoSearch/Search/Searchable.bp 2008-07-30 00:58:24 UTC (rev 3668)
@@ -2,15 +2,18 @@

/** Base class for searchers.
*
- * Abstract base class for objects which search. Subclasses include
- * L<KinoSearch::Searcher>, L<KinoSearch::Search::MultiSearcher>, and
- * L<KinoSearch::Search::SearchClient>.
+ * Abstract base class for objects which search. Core subclasses include
+ * L<KinoSearch::Searcher> and L<KinoSearch::Search::MultiSearcher>.
*/

class KinoSearch::Search::Searchable extends KinoSearch::Obj {

Schema *schema;

+ /** Abstract constructor.
+ *
+ * @param schema A KinoSearch::Schema.
+ */
static Searchable*
init(Searchable *self, Schema *schema);

@@ -26,6 +29,9 @@

/** Return the number of documents which contain the term in the given
* field.
+ *
+ * @param field Field name.
+ * @param term The term to look up.
*/
abstract u32_t
Doc_Freq(Searchable *self, const CharBuf *field, Obj *term);
@@ -56,7 +62,11 @@
Search(Searchable *self, Obj *query, u32_t offset = 0,
u32_t num_wanted = 10, SortSpec *sort_spec = NULL);

- /** Iterate over hits, feeding them into a HitCollector.
+ /** Iterate over hits, feeding them into a
+ * L<HitCollector|KinoSearch::Search::HitCollector>.
+ *
+ * @param query A Query.
+ * @param collector A HitCollector.
*/
abstract void
Collect(Searchable *self, Query *query, HitCollector *collector,
@@ -80,7 +90,7 @@
abstract incremented DocVector*
Fetch_Doc_Vec(Searchable *self, u32_t doc_num);

- /** Accessor for objects <code>schema</code> member.
+ /** Accessor for the object's <code>schema</code> member.
*/
Schema*
Get_Schema(Searchable *self);

Modified: trunk/c_src/KinoSearch/Searcher.bp
===================================================================
--- trunk/c_src/KinoSearch/Searcher.bp 2008-07-30 00:57:24 UTC (rev 3667)
+++ trunk/c_src/KinoSearch/Searcher.bp 2008-07-30 00:58:24 UTC (rev 3668)
@@ -1,5 +1,11 @@
parcel KinoSearch cnick Kino;

+/** Execute searches against a single invindex.
+ *
+ * Use the Searcher class to perform search queries against an invindex.
+ * (For searching multiple indexes at once, see
+ * L<MultiSearcher|KinoSearch::Search::MultiSearcher>).
+ */
class KinoSearch::Searcher extends KinoSearch::Search::Searchable {

InvIndex *invindex;
@@ -9,6 +15,11 @@
new(Searcher *self, InvIndex *invindex = NULL,
IndexReader *reader = NULL);

+ /** Either <code>invindex</code> or <code>reader</code> is required.
+ *
+ * @param invindex A KinoSearch::InvIndex.
+ * @param reader A KinoSearch::Index::IndexReader.
+ */
static Searcher*
init(Searcher *self, InvIndex *invindex = NULL,
IndexReader *reader = NULL);
@@ -36,6 +47,11 @@
incremented DocVector*
Fetch_Doc_Vec(Searcher *self, u32_t doc_num);

+ /** Accessor for the object's <code>reader</code> member.
+ */
+ IndexReader*
+ Get_Reader(Searcher *self);
+
void
Close(Searcher *self);
}

Modified: trunk/c_src/KinoSearch/Searcher.c
===================================================================
--- trunk/c_src/KinoSearch/Searcher.c 2008-07-30 00:57:24 UTC (rev 3667)
+++ trunk/c_src/KinoSearch/Searcher.c 2008-07-30 00:58:24 UTC (rev 3668)
@@ -129,6 +129,9 @@
REFCOUNT_DEC(seg_starts);
}

+IndexReader*
+Searcher_get_reader(Searcher *self) { return self->reader; }
+
void
Searcher_close(Searcher *self)
{

Modified: trunk/perl/lib/KinoSearch/Search/Searchable.pm
===================================================================
--- trunk/perl/lib/KinoSearch/Search/Searchable.pm 2008-07-30 00:57:24 UTC (rev 3667)
+++ trunk/perl/lib/KinoSearch/Search/Searchable.pm 2008-07-30 00:58:24 UTC (rev 3668)
@@ -6,6 +6,16 @@

__AUTO_XS__

+my $constructor = <<'END_CONSTRUCTOR';
+ package MySearchable;
+ use base qw( KinoSearch::Search::Searchable );
+ sub new {
+ my $self = shift->SUPER::new;
+ ...
+ return $self;
+ }
+END_CONSTRUCTOR
+
{ "KinoSearch::Search::Searchable" => {
bind_methods => [
qw( max_docs
@@ -20,6 +30,17 @@
close )
],
make_constructors => ["new"],
+ make_pod => {
+ synopsis => " # Abstract base class.\n",
+ constructor => { sample => $constructor },
+ methods => [.qw(
+ search
+ collect
+ max_docs
+ doc_freq
+ get_schema
+ )],
+ },
}
}


Modified: trunk/perl/lib/KinoSearch/Searcher.pm
===================================================================
--- trunk/perl/lib/KinoSearch/Searcher.pm 2008-07-30 00:57:24 UTC (rev 3667)
+++ trunk/perl/lib/KinoSearch/Searcher.pm 2008-07-30 00:58:24 UTC (rev 3668)
@@ -6,20 +6,7 @@

__AUTO_XS__

-{ "KinoSearch::Searcher" => {
- make_getters => [qw( reader )],
- make_constructors => ["_new"],
- }
-}
-
-__POD__
-
-=head1 NAME
-
-KinoSearch::Searcher - Execute searches.
-
-=head1 SYNOPSIS
-
+my $synopsis = <<'END_SYNOPSIS';
my $searcher = KinoSearch::Searcher->new(
invindex => MySchema->read('/path/to/invindex'),
);
@@ -28,106 +15,38 @@
offset => 0,
num_wanted => 100,
);
+END_SYNOPSIS

-=head1 DESCRIPTION
-
-Use the Searcher class to perform search queries against an invindex.
-
-Searcher's behavior is closely tied to that of
-L<KinoSearch::Index::IndexReader>. If any of these criteria apply to your
-application, please consult IndexReader's documentation:
-
-=over
-
-=item *
-
-Persistent environment (e.g. mod_perl, FastCGI).
-
-=item *
-
-Index located on shared filesystem, such as NFS.
-
-=item *
-
-Incremental updates.
-
-=back
-
-=head1 METHODS
-
-=head2 new
-
+my $constructor = <<'END_CONSTRUCTOR';
my $searcher = KinoSearch::Searcher->new(
invindex => MySchema->read('/path/to/invindex'),
);
# or...
my $searcher = KinoSearch::Searcher->new( reader => $reader );
+END_CONSTRUCTOR

-Constructor. Takes labeled parameters. Either C<invindex> or C<reader> is
-required.
+{ "KinoSearch::Searcher" => {
+ bind_methods => [qw( get_reader )],
+ make_constructors => ["_new"],
+ make_pod => {
+ synopsis => $synopsis,
+ constructor => { sample => $constructor },
+ methods => [.
+ qw( search
+ collect
+ max_docs
+ doc_freq
+ get_schema
+ get_reader )
+ ],
+ },
+ }
+}

-=over
+__COPYRIGHT__

-=item *
-
-B<invindex> - an object which isa L<KinoSearch::InvIndex>.
-
-=item *
-
-B<reader> - an object which isa L<KinoSearch::Index::IndexReader>.
-
-=back
-
-=head2 search
-
- my $hits = $searcher->search(
- query => $query, # required
- offset => 20, # default: 0
- num_wanted => 10, # default: 10
- sort_spec => $sort_spec, # default: undef (sort by relevance)
- );
-
-Process a search and return a L<Hits|KinoSearch::Search::Hits> object.
-search() expects labeled hash-style parameters.
-
-=over
-
-=item *
-
-B<query> - Can be either an object which subclasses
-L<KinoSearch::Search::Query> or a query string. If it's a query string, it
-will be parsed using a QueryParser and a search will be performed against all
-indexed fields in the InvIndex. For more sophisticated searching, supply Query
-objects, such as TermQuery, PhraseQuery, ANDQuery, etc.
-
-=item *
-
-B<offset> - The number of most-relevant hits to discard, typically used when
-"paging" through hits N at a time. Setting offset to 20 and num_wanted to 10
-retrieves hits 21-30, assuming that 30 hits can be found.
-
-=item *
-
-B<num_wanted> - The number of hits you would like to see after C<offset> is
-taken into account.
-
-=item *
-
-B<sort_spec> - Must be a L<KinoSearch::Search::SortSpec>, which will affect
-how results are ranked and returned.
-
-=back
-
-=head2 get_reader
-
- my $reader = $searcher->get_reader;
-
-Return the Searcher's inner L<IndexReader|KinoSearch::Index::IndexReader>.
-
-=head1 COPYRIGHT
-
Copyright 2005-2008 Marvin Humphrey

-=head1 LICENSE, DISCLAIMER, BUGS, etc.
+This program is free software; you can redistribute it and/or modify
+under the same terms as Perl itself.

-See L<KinoSearch> version 0.20.


_______________________________________________
kinosearch-commits mailing list
kinosearch-commits@rectangular.com
http://www.rectangular.com/mailman/listinfo/kinosearch-commits