Added: lucy/site/trunk/content/docs/perl/Lucy/Search/LeafQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/LeafQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/LeafQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/LeafQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,106 @@ +Title: Lucy::Search::LeafQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::LeafQuery - Leaf node in a tree created by QueryParser.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>package MyQueryParser; +use base qw( Lucy::Search::QueryParser ); + +sub expand_leaf { + my ( $self, $leaf_query ) = @_; + if ( $leaf_query->get_text =~ /.\*\s*$/ ) { + return PrefixQuery->new( + query_string => $leaf_query->get_text, + field => $leaf_query->get_field, + ); + } + else { + return $self->SUPER::expand_leaf($leaf_query); + } +}</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>LeafQuery objects serve as leaf nodes in the tree structure generated by <a href="../../Lucy/Search/QueryParser.html" class="podlinkpod" +>QueryParser</a>’s <a href="../../Lucy/Search/QueryParser.html#tree" class="podlinkpod" +>tree()</a> method. +Ultimately, +they must be transformed, +typically into either <a href="../../Lucy/Search/TermQuery.html" class="podlinkpod" +>TermQuery</a> or <a href="../../Lucy/Search/PhraseQuery.html" class="podlinkpod" +>PhraseQuery</a> objects, +as attempting to search a LeafQuery causes an error.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $leaf_query = Lucy::Search::LeafQuery->new( + text => '"three blind mice"', # required + field => 'content', # default: undef +);</pre> + +<p>Create a new LeafQuery.</p> + +<ul> +<li><b>field</b> - Optional field name.</li> + +<li><b>text</b> - Raw query text.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="get_field" +>get_field</a></h3> + +<pre>my $string = $leaf_query->get_field();</pre> + +<p>Accessor for object’s <code>field</code> attribute.</p> + +<h3><a class='u' +name="get_text" +>get_text</a></h3> + +<pre>my $string = $leaf_query->get_text();</pre> + +<p>Accessor for object’s <code>text</code> attribute.</p> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $leaf_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Throws an error.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::LeafQuery isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div>
Added: lucy/site/trunk/content/docs/perl/Lucy/Search/MatchAllQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/MatchAllQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/MatchAllQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/MatchAllQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,68 @@ +Title: Lucy::Search::MatchAllQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::MatchAllQuery - Query which matches all documents.</p> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>MatchAllQuery is a utility class which matches all documents. +Each match is assigned a score of 0.0, +so that in composite queries, +any document which matches against another part of the query will be ranked higher than a document which matches only via the MatchAllQuery.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $match_all_query = Lucy::Search::MatchAllQuery->new;</pre> + +<p>Constructor. +Takes no arguments.</p> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $match_all_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::MatchAllQuery isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/Matcher.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/Matcher.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/Matcher.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/Matcher.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,105 @@ +Title: Lucy::Search::Matcher â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::Matcher - Match a set of document ids.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre># abstract base class</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>A Matcher iterates over a set of ascending document ids. +Some Matchers implement <a href="#score" class="podlinkpod" +>score()</a> and can assign relevance scores to the docs that they match. +Other implementations may be match-only.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $matcher = MyMatcher->SUPER::new;</pre> + +<p>Abstract constructor.</p> + +<h2><a class='u' +name="ABSTRACT_METHODS" +>ABSTRACT METHODS</a></h2> + +<h3><a class='u' +name="next" +>next</a></h3> + +<pre>my $int = $matcher->next();</pre> + +<p>Proceed to the next doc id.</p> + +<p>Returns: A positive doc id, +or 0 once the iterator is exhausted.</p> + +<h3><a class='u' +name="get_doc_id" +>get_doc_id</a></h3> + +<pre>my $int = $matcher->get_doc_id();</pre> + +<p>Return the current doc id. +Valid only after a successful call to <a href="#next" class="podlinkpod" +>next()</a> or <a href="#advance" class="podlinkpod" +>advance()</a> and must not be called otherwise.</p> + +<h3><a class='u' +name="score" +>score</a></h3> + +<pre>my $float = $matcher->score();</pre> + +<p>Return the score of the current document.</p> + +<p>Only Matchers which are used for scored search need implement <a href="#score" class="podlinkpod" +>score()</a>.</p> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="advance" +>advance</a></h3> + +<pre>my $int = $matcher->advance($target);</pre> + +<p>Advance the iterator to the first doc id greater than or equal to <code>target</code>. +The default implementation simply calls <a href="#next" class="podlinkpod" +>next()</a> over and over, +but subclasses have the option of doing something more efficient.</p> + +<ul> +<li><b>target</b> - A positive doc id, +which must be greater than the current doc id once the iterator has been initialized.</li> +</ul> + +<p>Returns: A positive doc id, +or 0 once the iterator is exhausted.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::Matcher isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/NOTQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/NOTQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/NOTQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/NOTQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,105 @@ +Title: Lucy::Search::NOTQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::NOTQuery - Invert the result set of another Query.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $not_bar_query = Lucy::Search::NOTQuery->new( + negated_query => $bar_query, +); +my $foo_and_not_bar_query = Lucy::Search::ANDQuery->new( + children => [ $foo_query, $not_bar_query ]. +); +my $hits = $searcher->hits( query => $foo_and_not_bar_query ); +...</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>A NOTQuery wraps another <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Query</a> and matches against its inverse document set. +All matching docs recieve a score of 0.0.</p> + +<p>NOTQuery is often used in conjunction with <a href="../../Lucy/Search/ANDQuery.html" class="podlinkpod" +>ANDQuery</a> to provide “a AND NOT b” semantics.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $not_query = Lucy::Search::NOTQuery->new( + negated_query => $query, +);</pre> + +<p>Create a new NOTQuery.</p> + +<ul> +<li><b>negated_query</b> - The Query whose result set should be inverted.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="get_negated_query" +>get_negated_query</a></h3> + +<pre>my $query = $not_query->get_negated_query();</pre> + +<p>Accessor for the object’s negated query.</p> + +<h3><a class='u' +name="set_negated_query" +>set_negated_query</a></h3> + +<pre>$not_query->set_negated_query($negated_query);</pre> + +<p>Setter for the object’s negated query.</p> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $not_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::NOTQuery isa <a href="../../Lucy/Search/PolyQuery.html" class="podlinkpod" +>Lucy::Search::PolyQuery</a> isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/NoMatchQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/NoMatchQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/NoMatchQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/NoMatchQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,68 @@ +Title: Lucy::Search::NoMatchQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::NoMatchQuery - Query which matches no documents.</p> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>NoMatchQuery is a utility class representing a query which matches nothing. +Typical usage might include e.g. +returning a NoMatchQuery when a <a href="../../Lucy/Search/QueryParser.html" class="podlinkpod" +>QueryParser</a> is asked to parse an empty string.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $no_match_query = Lucy::Search::NoMatchQuery->new;</pre> + +<p>Constructor. +Takes no arguments.</p> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $no_match_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::NoMatchQuery isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/ORQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/ORQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/ORQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/ORQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,84 @@ +Title: Lucy::Search::ORQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::ORQuery - Union multiple result sets.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $foo_or_bar_query = Lucy::Search::ORQuery->new( + children => [ $foo_query, $bar_query ], +); +my $hits = $searcher->hits( query => $foo_or_bar_query ); +...</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>ORQuery is a composite <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Query</a> which matches when any of its children match, +so its result set is the union of their result sets. +Matching documents recieve a summed score from all matching child Queries.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $foo_or_bar_query = Lucy::Search::ORQuery->new( + children => [ $foo_query, $bar_query ], +);</pre> + +<p>Create a new ORQuery.</p> + +<ul> +<li><b>children</b> - An array of child Queries.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $or_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::ORQuery isa <a href="../../Lucy/Search/PolyQuery.html" class="podlinkpod" +>Lucy::Search::PolyQuery</a> isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/PhraseQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/PhraseQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/PhraseQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/PhraseQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,100 @@ +Title: Lucy::Search::PhraseQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::PhraseQuery - Query matching an ordered list of terms.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $phrase_query = Lucy::Search::PhraseQuery->new( + field => 'content', + terms => [qw( the who )], +); +my $hits = $searcher->hits( query => $phrase_query );</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>PhraseQuery is a subclass of <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Query</a> for matching against an ordered sequence of terms.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $phrase_query = Lucy::Search::PhraseQuery->new( + field => $field # required + terms => $terms # required +);</pre> + +<p>Create a new PhraseQuery.</p> + +<ul> +<li><b>field</b> - The field that the phrase must occur in.</li> + +<li><b>terms</b> - The ordered array of terms that must match.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="get_field" +>get_field</a></h3> + +<pre>my $string = $phrase_query->get_field();</pre> + +<p>Accessor for object’s field attribute.</p> + +<h3><a class='u' +name="get_terms" +>get_terms</a></h3> + +<pre>my $arrayref = $phrase_query->get_terms();</pre> + +<p>Accessor for object’s array of terms.</p> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $phrase_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::PhraseQuery isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/PolyQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/PolyQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/PolyQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/PolyQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,62 @@ +Title: Lucy::Search::PolyQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::PolyQuery - Base class for composite Query objects.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>sub walk { + my $query = shift; + if ( $query->isa("Lucy::Search::PolyQuery") ) { + if ( $query->isa("Lucy::Search::ORQuery") ) { ... } + elsif ( $query->isa("Lucy::Search::ANDQuery") ) { ... } + elsif ( $query->isa("Lucy::Search::RequiredOptionalQuery") ) { + ... + } + elsif ( $query->isa("Lucy::Search::NOTQuery") ) { ... } + } + else { ... } +}</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>PolyQuery serves as a shared base class for <a href="../../Lucy/Search/ANDQuery.html" class="podlinkpod" +>ANDQuery</a>, +<a href="../../Lucy/Search/ORQuery.html" class="podlinkpod" +>ORQuery</a>, +<a href="../../Lucy/Search/NOTQuery.html" class="podlinkpod" +>NOTQuery</a>, +and <a href="../../Lucy/Search/RequiredOptionalQuery.html" class="podlinkpod" +>RequiredOptionalQuery</a>. +All of these classes may serve as nodes in composite Query with a tree structure which may be walked.</p> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="add_child" +>add_child</a></h3> + +<pre>$poly_query->add_child($query);</pre> + +<p>Add a child Query node.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::PolyQuery isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/PolySearcher.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/PolySearcher.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/PolySearcher.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/PolySearcher.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,123 @@ +Title: Lucy::Search::PolySearcher â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::PolySearcher - Aggregate results from multiple Searchers.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $schema = MySchema->new; +for my $index (@index_paths) { + push @searchers, Lucy::Search::IndexSearcher->new( index => $index ); +} +my $poly_searcher = Lucy::Search::PolySearcher->new( + schema => $schema, + searchers => \@searchers, +); +my $hits = $poly_searcher->hits( query => $query );</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>The primary use for PolySearcher is to aggregate results from several indexes on a single machine.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $poly_searcher = Lucy::Search::PolySearcher->new( + schema => $schema, + searchers => \@searchers, +);</pre> + +<p>Create a new PolySearcher.</p> + +<ul> +<li><b>schema</b> - A Schema.</li> + +<li><b>searchers</b> - An array of Searchers.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="doc_max" +>doc_max</a></h3> + +<pre>my $int = $poly_searcher->doc_max();</pre> + +<p>Return the maximum number of docs in the collection represented by the Searcher, +which is also the highest possible internal doc id. +Documents which have been marked as deleted but not yet purged are included in this count.</p> + +<h3><a class='u' +name="doc_freq" +>doc_freq</a></h3> + +<pre>my $int = $poly_searcher->doc_freq( + field => $field # required + term => $term # required +);</pre> + +<p>Return the number of documents which contain the term in the given field.</p> + +<ul> +<li><b>field</b> - Field name.</li> + +<li><b>term</b> - The term to look up.</li> +</ul> + +<h3><a class='u' +name="collect" +>collect</a></h3> + +<pre>$poly_searcher->collect( + query => $query # required + collector => $collector # required +);</pre> + +<p>Iterate over hits, +feeding them into a <a href="../../Lucy/Search/Collector.html" class="podlinkpod" +>Collector</a>.</p> + +<ul> +<li><b>query</b> - A Query.</li> + +<li><b>collector</b> - A Collector.</li> +</ul> + +<h3><a class='u' +name="fetch_doc" +>fetch_doc</a></h3> + +<pre>my $hit_doc = $poly_searcher->fetch_doc($doc_id);</pre> + +<p>Retrieve a document. +Throws an error if the doc id is out of range.</p> + +<ul> +<li><b>doc_id</b> - A document id.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::PolySearcher isa <a href="../../Lucy/Search/Searcher.html" class="podlinkpod" +>Lucy::Search::Searcher</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/Query.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/Query.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/Query.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/Query.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,138 @@ +Title: Lucy::Search::Query â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::Query - A specification for a search query.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre># Query is an abstract base class. +package MyQuery; +use base qw( Lucy::Search::Query ); + +sub make_compiler { + my ( $self, %args ) = @_; + my $subordinate = delete $args{subordinate}; + my $compiler = MyCompiler->new( %args, parent => $self ); + $compiler->normalize unless $subordinate; + return $compiler; +} + +package MyCompiler; +use base ( Lucy::Search::Compiler ); +...</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>Query objects are simple containers which contain the minimum information necessary to define a search query.</p> + +<p>The most common way to generate Query objects is to feed a search string such as ‘foo AND bar’ to a <a href="../../Lucy/Search/QueryParser.html" class="podlinkpod" +>QueryParser’s</a> <a href="../../Lucy/Search/QueryParser.html#parse" class="podlinkpod" +>parse()</a> method, +which outputs an abstract syntax tree built up from various Query subclasses such as <a href="../../Lucy/Search/ANDQuery.html" class="podlinkpod" +>ANDQuery</a> and <a href="../../Lucy/Search/TermQuery.html" class="podlinkpod" +>TermQuery</a>. +However, +it is also possible to use custom Query objects to build a search specification which cannot be easily represented using a search string.</p> + +<p>Subclasses of Query must implement <a href="#make_compiler" class="podlinkpod" +>make_compiler()</a>, +which is the first step in compiling a Query down to a <a href="../../Lucy/Search/Matcher.html" class="podlinkpod" +>Matcher</a> which can actually match and score documents.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $query = MyQuery->SUPER::new( + boost => 2.5, +);</pre> + +<p>Abstract constructor.</p> + +<ul> +<li><b>boost</b> - A scoring multiplier, +affecting the Query's relative contribution to each document's score. +Typically defaults to 1.0, +but subclasses which do not contribute to document scores such as NOTQuery and MatchAllQuery default to 0.0 instead.</li> +</ul> + +<h2><a class='u' +name="ABSTRACT_METHODS" +>ABSTRACT METHODS</a></h2> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="set_boost" +>set_boost</a></h3> + +<pre>$query->set_boost($boost);</pre> + +<p>Set the Query’s boost.</p> + +<h3><a class='u' +name="get_boost" +>get_boost</a></h3> + +<pre>my $float = $query->get_boost();</pre> + +<p>Get the Query’s boost.</p> + +<h3><a class='u' +name="dump" +>dump</a></h3> + +<pre>my $obj = $query->dump();</pre> + +<h3><a class='u' +name="load" +>load</a></h3> + +<pre>my $obj = $query->load($dump);</pre> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::Query isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/QueryParser.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/QueryParser.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/QueryParser.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/QueryParser.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,344 @@ +Title: Lucy::Search::QueryParser â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::QueryParser - Transform a string into a Query object.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $query_parser = Lucy::Search::QueryParser->new( + schema => $searcher->get_schema, + fields => ['body'], +); +my $query = $query_parser->parse( $query_string ); +my $hits = $searcher->hits( query => $query );</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>QueryParser accepts search strings as input and produces <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Query</a> objects, +suitable for feeding into <a href="../../Lucy/Search/IndexSearcher.html" class="podlinkpod" +>IndexSearcher</a> and other <a href="../../Lucy/Search/Searcher.html" class="podlinkpod" +>Searcher</a> subclasses.</p> + +<p>The following syntactical constructs are recognized by QueryParser:</p> + +<ul> +<li>Boolean operators ‘AND’, +‘OR’, +and ‘AND NOT’.</li> + +<li>Prepented +plus and -minus, +indicating that the labeled entity should be either required or forbidden – be it a single word, +a phrase, +or a parenthetical group.</li> + +<li>Logical groups, +delimited by parentheses.</li> + +<li>Phrases, +delimited by double quotes.</li> +</ul> + +<p>Additionally, +the following syntax can be enabled via <a href="#set_heed_colons" class="podlinkpod" +>set_heed_colons()</a>:</p> + +<ul> +<li>Field-specific constructs, +in the form of ‘fieldname:termtext’ or ‘fieldname:(foo bar)’. +(The field specified by ‘fieldname:’ will be used instead of the QueryParser’s default fields).</li> +</ul> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $query_parser = Lucy::Search::QueryParser->new( + schema => $searcher->get_schema, # required + analyzer => $analyzer, # overrides schema + fields => ['bodytext'], # default: indexed fields + default_boolop => 'AND', # default: 'OR' +);</pre> + +<p>Constructor.</p> + +<ul> +<li><b>schema</b> - A <a href="../../Lucy/Plan/Schema.html" class="podlinkpod" +>Schema</a>.</li> + +<li><b>analyzer</b> - An <a href="../../Lucy/Analysis/Analyzer.html" class="podlinkpod" +>Analyzer</a>. +Ordinarily, +the analyzers specified by each field’s definition will be used, +but if <code>analyzer</code> is supplied, +it will override and be used for all fields. +This can lead to mismatches between what is in the index and what is being searched for, +so use caution.</li> + +<li><b>fields</b> - The names of the fields which will be searched against. +Defaults to those fields which are defined as indexed in the supplied Schema.</li> + +<li><b>default_boolop</b> - Two possible values: ‘AND’ and ‘OR’. +The default is ‘OR’, +which means: return documents which match any of the query terms. +If you want only documents which match all of the query terms, +set this to ‘AND’.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="parse" +>parse</a></h3> + +<pre>my $query = $query_parser->parse($query_string); +my $query = $query_parser->parse(); # default: undef</pre> + +<p>Build a Query object from the contents of a query string. +At present, +implemented internally by calling <a href="#tree" class="podlinkpod" +>tree()</a>, +<a href="#expand" class="podlinkpod" +>expand()</a>, +and <a href="#prune" class="podlinkpod" +>prune()</a>.</p> + +<ul> +<li><b>query_string</b> - The string to be parsed. +May be undef.</li> +</ul> + +<p>Returns: a Query.</p> + +<h3><a class='u' +name="tree" +>tree</a></h3> + +<pre>my $query = $query_parser->tree($query_string);</pre> + +<p>Parse the logical structure of a query string, +building a tree comprised of Query objects. +Leaf nodes in the tree will most often be LeafQuery objects but might be MatchAllQuery or NoMatchQuery objects as well. +Internal nodes will be objects which subclass PolyQuery: ANDQuery, +ORQuery, +NOTQuery, +and RequiredOptionalQuery.</p> + +<p>The output of <a href="#tree" class="podlinkpod" +>tree()</a> is an intermediate form which must be passed through <a href="#expand" class="podlinkpod" +>expand()</a> before being used to feed a search.</p> + +<ul> +<li><b>query_string</b> - The string to be parsed.</li> +</ul> + +<p>Returns: a Query.</p> + +<h3><a class='u' +name="expand" +>expand</a></h3> + +<pre>my $query = $query_parser->expand($query);</pre> + +<p>Walk the hierarchy of a Query tree, +descending through all PolyQuery nodes and calling <a href="#expand_leaf" class="podlinkpod" +>expand_leaf()</a> on any LeafQuery nodes encountered.</p> + +<ul> +<li><b>query</b> - A Query object.</li> +</ul> + +<p>Returns: A Query – usually the same one that was supplied after in-place modification, +but possibly another.</p> + +<h3><a class='u' +name="expand_leaf" +>expand_leaf</a></h3> + +<pre>my $query = $query_parser->expand_leaf($query);</pre> + +<p>Convert a LeafQuery into either a TermQuery, +a PhraseQuery, +or an ORQuery joining multiple TermQueries/PhraseQueries to accommodate multiple fields. +LeafQuery text will be passed through the relevant Analyzer for each field. +Quoted text will be transformed into PhraseQuery objects. +Unquoted text will be converted to either a TermQuery or a PhraseQuery depending on how many tokens are generated.</p> + +<ul> +<li><b>query</b> - A Query. +Only LeafQuery objects will be processed; others will be passed through.</li> +</ul> + +<p>Returns: A Query.</p> + +<h3><a class='u' +name="prune" +>prune</a></h3> + +<pre>my $query = $query_parser->prune($query); +my $query = $query_parser->prune(); # default: undef</pre> + +<p>Prevent certain Query structures from returning too many results. +Query objects built via <a href="#tree" class="podlinkpod" +>tree()</a> and <a href="#expand" class="podlinkpod" +>expand()</a> can generate “return the world” result sets, +such as in the case of <code>NOT a_term_not_in_the_index</code>; <a href="#prune" class="podlinkpod" +>prune()</a> walks the hierarchy and eliminates such branches.</p> + +<pre> 'NOT foo' => [NOMATCH] + 'foo OR NOT bar' => 'foo' + 'foo OR (-bar AND -baz) => 'foo'</pre> + +<p><a href="#prune" class="podlinkpod" +>prune()</a> also eliminates some double-negative constructs – even though such constructs may not actually return the world:</p> + +<pre> 'foo AND -(-bar)' => 'foo'</pre> + +<p>In this example, +safety is taking precedence over logical consistency. +If you want logical consistency instead, +call <a href="#tree" class="podlinkpod" +>tree()</a> then <a href="#expand" class="podlinkpod" +>expand()</a>, +skipping <a href="#prune" class="podlinkpod" +>prune()</a>.</p> + +<ul> +<li><b>query</b> - A Query.</li> +</ul> + +<p>Returns: a Query; in most cases, +the supplied Query after in-place modification.</p> + +<h3><a class='u' +name="make_term_query" +>make_term_query</a></h3> + +<pre>my $query = $query_parser->make_term_query( + field => $field # required + term => $term # required +);</pre> + +<p>Factory method creating a TermQuery.</p> + +<ul> +<li><b>field</b> - Field name.</li> + +<li><b>term</b> - Term text.</li> +</ul> + +<p>Returns: A Query.</p> + +<h3><a class='u' +name="make_phrase_query" +>make_phrase_query</a></h3> + +<pre>my $query = $query_parser->make_phrase_query( + field => $field # required + terms => $terms # required +);</pre> + +<p>Factory method creating a PhraseQuery.</p> + +<ul> +<li><b>field</b> - Field that the phrase must occur in.</li> + +<li><b>terms</b> - Ordered array of terms that must match.</li> +</ul> + +<p>Returns: A Query.</p> + +<h3><a class='u' +name="make_or_query" +>make_or_query</a></h3> + +<pre>my $query = $query_parser->make_or_query($children); +my $query = $query_parser->make_or_query(); # default: undef</pre> + +<p>Factory method creating an ORQuery.</p> + +<ul> +<li><b>children</b> - Array of child Queries.</li> +</ul> + +<p>Returns: A Query.</p> + +<h3><a class='u' +name="make_and_query" +>make_and_query</a></h3> + +<pre>my $query = $query_parser->make_and_query($children); +my $query = $query_parser->make_and_query(); # default: undef</pre> + +<p>Factory method creating an ANDQuery.</p> + +<ul> +<li><b>children</b> - Array of child Queries.</li> +</ul> + +<p>Returns: A Query.</p> + +<h3><a class='u' +name="make_not_query" +>make_not_query</a></h3> + +<pre>my $query = $query_parser->make_not_query($negated_query);</pre> + +<p>Factory method creating a NOTQuery.</p> + +<ul> +<li><b>negated_query</b> - Query to be inverted.</li> +</ul> + +<p>Returns: A Query.</p> + +<h3><a class='u' +name="make_req_opt_query" +>make_req_opt_query</a></h3> + +<pre>my $query = $query_parser->make_req_opt_query( + required_query => $required_query # required + optional_query => $optional_query # required +);</pre> + +<p>Factory method creating a RequiredOptionalQuery.</p> + +<ul> +<li><b>required_query</b> - Query must must match.</li> + +<li><b>optional_query</b> - Query which should match.</li> +</ul> + +<p>Returns: A Query.</p> + +<h3><a class='u' +name="set_heed_colons" +>set_heed_colons</a></h3> + +<pre>$query_parser->set_heed_colons($heed_colons);</pre> + +<p>Enable/disable parsing of <code>fieldname:foo</code> constructs.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::QueryParser isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/RangeQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/RangeQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/RangeQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/RangeQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,109 @@ +Title: Lucy::Search::RangeQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::RangeQuery - Match a range of values.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre># Match all articles by "Foo" published since the year 2000. +my $range_query = Lucy::Search::RangeQuery->new( + field => 'publication_date', + lower_term => '2000-01-01', + include_lower => 1, +); +my $author_query = Lucy::Search::TermQuery->new( + field => 'author_last_name', + text => 'Foo', +); +my $and_query = Lucy::Search::ANDQuery->new( + children => [ $range_query, $author_query ], +); +my $hits = $searcher->hits( query => $and_query ); +...</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>RangeQuery matches documents where the value for a particular field falls within a given range.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $range_query = Lucy::Search::RangeQuery->new( + field => 'product_number', # required + lower_term => '003', # see below + upper_term => '060', # see below + include_lower => 0, # default true + include_upper => 0, # default true +);</pre> + +<p>Create a new RangeQuery.</p> + +<p>Takes 5 parameters; <code>field</code> is required, +as is at least one of either <code>lower_term</code> or <code>upper_term</code>.</p> + +<ul> +<li><b>field</b> - The name of a <code>sortable</code> field.</li> + +<li><b>lower_term</b> - Lower delimiter. +If not supplied, +all values less than <code>upper_term</code> will pass.</li> + +<li><b>upper_term</b> - Upper delimiter. +If not supplied, +all values greater than <code>lower_term</code> will pass.</li> + +<li><b>include_lower</b> - Indicates whether docs which match <code>lower_term</code> should be included in the results.</li> + +<li><b>include_upper</b> - Indicates whether docs which match <code>upper_term</code> should be included in the results.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $range_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::RangeQuery isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/RequiredOptionalQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/RequiredOptionalQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/RequiredOptionalQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/RequiredOptionalQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,123 @@ +Title: Lucy::Search::RequiredOptionalQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::RequiredOptionalQuery - Join results for two Queries, +one required, +one optional.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $foo_and_maybe_bar = Lucy::Search::RequiredOptionalQuery->new( + required_query => $foo_query, + optional_query => $bar_query, +); +my $hits = $searcher->hits( query => $foo_and_maybe_bar ); +...</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>RequiredOptionalQuery joins the result sets of one Query which MUST match, +and one Query which SHOULD match. +When only the required Query matches, +its score is passed along; when both match, +the scores are summed.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $reqopt_query = Lucy::Search::RequiredOptionalQuery->new( + required_query => $foo_query, # required + optional_query => $bar_query, # required +);</pre> + +<p>Create a new RequiredOptionalQuery.</p> + +<ul> +<li><b>required_query</b> - Query must must match.</li> + +<li><b>optional_query</b> - Query which should match.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="get_required_query" +>get_required_query</a></h3> + +<pre>my $query = $required_optional_query->get_required_query();</pre> + +<p>Getter for the required Query.</p> + +<h3><a class='u' +name="set_required_query" +>set_required_query</a></h3> + +<pre>$required_optional_query->set_required_query($required_query);</pre> + +<p>Setter for the required Query.</p> + +<h3><a class='u' +name="get_optional_query" +>get_optional_query</a></h3> + +<pre>my $query = $required_optional_query->get_optional_query();</pre> + +<p>Getter for the optional Query.</p> + +<h3><a class='u' +name="set_optional_query" +>set_optional_query</a></h3> + +<pre>$required_optional_query->set_optional_query($optional_query);</pre> + +<p>Setter for the optional Query.</p> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $required_optional_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::RequiredOptionalQuery isa <a href="../../Lucy/Search/PolyQuery.html" class="podlinkpod" +>Lucy::Search::PolyQuery</a> isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/Searcher.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/Searcher.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/Searcher.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/Searcher.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,169 @@ +Title: Lucy::Search::Searcher â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::Searcher - Base class for searching collections of documents.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre># Abstract base class.</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>Abstract base class for objects which search. +Core subclasses include <a href="../../Lucy/Search/IndexSearcher.html" class="podlinkpod" +>IndexSearcher</a> and <a href="../../Lucy/Search/PolySearcher.html" class="podlinkpod" +>PolySearcher</a>.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>package MySearcher; +use base qw( Lucy::Search::Searcher ); +sub new { + my $self = shift->SUPER::new; + ... + return $self; +}</pre> + +<p>Abstract constructor.</p> + +<ul> +<li><b>schema</b> - A Schema.</li> +</ul> + +<h2><a class='u' +name="ABSTRACT_METHODS" +>ABSTRACT METHODS</a></h2> + +<h3><a class='u' +name="doc_max" +>doc_max</a></h3> + +<pre>my $int = $searcher->doc_max();</pre> + +<p>Return the maximum number of docs in the collection represented by the Searcher, +which is also the highest possible internal doc id. +Documents which have been marked as deleted but not yet purged are included in this count.</p> + +<h3><a class='u' +name="doc_freq" +>doc_freq</a></h3> + +<pre>my $int = $searcher->doc_freq( + field => $field # required + term => $term # required +);</pre> + +<p>Return the number of documents which contain the term in the given field.</p> + +<ul> +<li><b>field</b> - Field name.</li> + +<li><b>term</b> - The term to look up.</li> +</ul> + +<h3><a class='u' +name="collect" +>collect</a></h3> + +<pre>$searcher->collect( + query => $query # required + collector => $collector # required +);</pre> + +<p>Iterate over hits, +feeding them into a <a href="../../Lucy/Search/Collector.html" class="podlinkpod" +>Collector</a>.</p> + +<ul> +<li><b>query</b> - A Query.</li> + +<li><b>collector</b> - A Collector.</li> +</ul> + +<h3><a class='u' +name="fetch_doc" +>fetch_doc</a></h3> + +<pre>my $hit_doc = $searcher->fetch_doc($doc_id);</pre> + +<p>Retrieve a document. +Throws an error if the doc id is out of range.</p> + +<ul> +<li><b>doc_id</b> - A document id.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="glean_query" +>glean_query</a></h3> + +<pre>my $query = $searcher->glean_query($query); +my $query = $searcher->glean_query(); # default: undef</pre> + +<p>If the supplied object is a Query, +return it; if it’s a query string, +create a QueryParser and parse it to produce a query against all indexed fields.</p> + +<h3><a class='u' +name="hits" +>hits</a></h3> + +<pre>my $hits = $searcher->hits( + query => $query # required + offset => $offset # default: 0 + num_wanted => $num_wanted # default: 10 + sort_spec => $sort_spec # default: undef +);</pre> + +<p>Return a Hits object containing the top results.</p> + +<ul> +<li><b>query</b> - Either a Query object or a query string.</li> + +<li><b>offset</b> - The number of most-relevant hits to discard, +typically used when “paging” through hits N at a time. +Setting <code>offset</code> to 20 and <code>num_wanted</code> to 10 retrieves hits 21-30, +assuming that 30 hits can be found.</li> + +<li><b>num_wanted</b> - The number of hits you would like to see after <code>offset</code> is taken into account.</li> + +<li><b>sort_spec</b> - A <a href="../../Lucy/Search/SortSpec.html" class="podlinkpod" +>SortSpec</a>, +which will affect how results are ranked and returned.</li> +</ul> + +<h3><a class='u' +name="get_schema" +>get_schema</a></h3> + +<pre>my $schema = $searcher->get_schema();</pre> + +<p>Accessor for the object’s <code>schema</code> member.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::Searcher isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/SortRule.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/SortRule.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/SortRule.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/SortRule.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,96 @@ +Title: Lucy::Search::SortRule â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::SortRule - Element of a SortSpec.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $sort_spec = Lucy::Search::SortSpec->new( + rules => [ + Lucy::Search::SortRule->new( field => 'date' ), + Lucy::Search::SortRule->new( type => 'doc_id' ), + ], +);</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>SortRules are the building blocks used to assemble <a href="../../Lucy/Search/SortSpec.html" class="podlinkpod" +>SortSpecs</a>; each SortRule defines a single level of sorting. +For example, +sorting first by “category” then by score requires a SortSpec with two SortRule elements.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $by_title = Lucy::Search::SortRule->new( field => 'title' ); +my $by_score = Lucy::Search::SortRule->new( type => 'score' ); +my $by_doc_id = Lucy::Search::SortRule->new( type => 'doc_id' ); +my $reverse_date = Lucy::Search::SortRule->new( + field => 'date', + reverse => 1, +);</pre> + +<p>Create a new SortRule.</p> + +<ul> +<li><b>type</b> - Indicate whether to sort by score, +field, +etc. +(The default is to sort by a field.)</li> + +<li><b>field</b> - The name of a <code>sortable</code> field.</li> + +<li><b>reverse</b> - If true, +reverse the order of the sort for this rule.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="get_field" +>get_field</a></h3> + +<pre>my $string = $sort_rule->get_field();</pre> + +<p>Accessor for “field” member.</p> + +<h3><a class='u' +name="get_type" +>get_type</a></h3> + +<pre>my $int = $sort_rule->get_type();</pre> + +<p>Accessor for “type” member.</p> + +<h3><a class='u' +name="get_reverse" +>get_reverse</a></h3> + +<pre>my $bool = $sort_rule->get_reverse();</pre> + +<p>Accessor for “reverse” member.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::SortRule isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/SortSpec.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/SortSpec.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/SortSpec.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/SortSpec.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,62 @@ +Title: Lucy::Search::SortSpec â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::SortSpec - Specify a custom sort order for search results.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $sort_spec = Lucy::Search::SortSpec->new( + rules => [ + Lucy::Search::SortRule->new( field => 'date' ), + Lucy::Search::SortRule->new( type => 'doc_id' ), + ], +); +my $hits = $searcher->hits( + query => $query, + sort_spec => $sort_spec, +);</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>By default, +searches return results in order of relevance; SortSpec allows you to indicate an alternate order via an array of <a href="../../Lucy/Search/SortRule.html" class="podlinkpod" +>SortRules</a>.</p> + +<p>Fields you wish to sort against must be <code>sortable</code>.</p> + +<p>For a stable sort (important when paging through results), +add a sort-by-doc rule as the last SortRule.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $sort_spec = Lucy::Search::SortSpec->new( rules => \@rules );</pre> + +<p>Create a new SortSpec.</p> + +<ul> +<li><b>rules</b> - An array of SortRules.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::SortSpec isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/Span.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/Span.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/Span.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/Span.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,141 @@ +Title: Lucy::Search::Span â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::Span - An offset, +a length, +and a weight.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $combined_length = $upper_span->get_length + + ( $upper_span->get_offset - $lower_span->get_offset ); +my $combined_span = Lucy::Search::Span->new( + offset => $lower_span->get_offset, + length => $combined_length, +); +...</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>Span objects store information about a span across an array of… something. +The unit is context-dependent.</p> + +<p>Text is one possibility, +in which case offset and length might be measured in Unicode code points. +However, +the Span could also refer to a span within an array of tokens, +for example – in which case the start and offset might be measured in token positions.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $span = Lucy::Search::Span->new( + offset => 75, # required + length => 7, # required + weight => 1.0, # default 0.0 +);</pre> + +<p>Create a new Span.</p> + +<ul> +<li><b>offset</b> - Integer offset, +unit is context-dependent.</li> + +<li><b>length</b> - Integer length, +unit is context-dependent.</li> + +<li><b>weight</b> - A floating point weight.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="get_offset" +>get_offset</a></h3> + +<pre>my $int = $span->get_offset();</pre> + +<p>Accessor for <code>offset</code> attribute.</p> + +<h3><a class='u' +name="set_offset" +>set_offset</a></h3> + +<pre>$span->set_offset($offset);</pre> + +<p>Setter for <code>offset</code> attribute.</p> + +<h3><a class='u' +name="get_length" +>get_length</a></h3> + +<pre>my $int = $span->get_length();</pre> + +<p>Accessor for <code>length</code> attribute.</p> + +<h3><a class='u' +name="set_length" +>set_length</a></h3> + +<pre>$span->set_length($length);</pre> + +<p>Setter for <code>length</code> attribute.</p> + +<h3><a class='u' +name="get_weight" +>get_weight</a></h3> + +<pre>my $float = $span->get_weight();</pre> + +<p>Accessor for <code>weight</code> attribute.</p> + +<h3><a class='u' +name="set_weight" +>set_weight</a></h3> + +<pre>$span->set_weight($weight);</pre> + +<p>Setter for <code>weight</code> attribute.</p> + +<h3><a class='u' +name="compare_to" +>compare_to</a></h3> + +<pre>my $int = $span->compare_to($other);</pre> + +<p>Indicate whether one object is less than, +equal to, +or greater than another.</p> + +<ul> +<li><b>other</b> - Another Obj.</li> +</ul> + +<p>Returns: 0 if the objects are equal, +a negative number if <code>self</code> is less than <code>other</code>, +and a positive number if <code>self</code> is greater than <code>other</code>.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::Span isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Search/TermQuery.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Search/TermQuery.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Search/TermQuery.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Search/TermQuery.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,100 @@ +Title: Lucy::Search::TermQuery â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Search::TermQuery - Query which matches individual terms.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $term_query = Lucy::Search::TermQuery->new( + field => 'content', + term => 'foo', +); +my $hits = $searcher->hits( query => $term_query );</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>TermQuery is a subclass of <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Query</a> for matching individual terms in a specific field.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $term_query = Lucy::Search::TermQuery->new( + field => 'content', # required + term => 'foo', # required +);</pre> + +<p>Create a new TermQuery.</p> + +<ul> +<li><b>field</b> - Field name.</li> + +<li><b>term</b> - Term text.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="get_field" +>get_field</a></h3> + +<pre>my $string = $term_query->get_field();</pre> + +<p>Accessor for object’s <code>field</code> member.</p> + +<h3><a class='u' +name="get_term" +>get_term</a></h3> + +<pre>my $obj = $term_query->get_term();</pre> + +<p>Accessor for object’s <code>term</code> member.</p> + +<h3><a class='u' +name="make_compiler" +>make_compiler</a></h3> + +<pre>my $compiler = $term_query->make_compiler( + searcher => $searcher # required + boost => $boost # required + subordinate => $subordinate # default: false +);</pre> + +<p>Abstract factory method returning a Compiler derived from this Query.</p> + +<ul> +<li><b>searcher</b> - A Searcher.</li> + +<li><b>boost</b> - A scoring multiplier.</li> + +<li><b>subordinate</b> - Indicates whether the Query is a subquery (as opposed to a top-level query). +If false, +the implementation must invoke <a href="../../Lucy/Search/Compiler.html#normalize" class="podlinkpod" +>normalize()</a> on the newly minted Compiler object before returning it.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Search::TermQuery isa <a href="../../Lucy/Search/Query.html" class="podlinkpod" +>Lucy::Search::Query</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Simple.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Simple.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Simple.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Simple.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,153 @@ +Title: Lucy::Simple â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Simple - Basic search engine.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<p>First, +build an index of your documents.</p> + +<pre>my $index = Lucy::Simple->new( + path => '/path/to/index/' + language => 'en', +); + +while ( my ( $title, $content ) = each %source_docs ) { + $index->add_doc({ + title => $title, + content => $content, + }); +}</pre> + +<p>Later, +search the index.</p> + +<pre>my $total_hits = $index->search( + query => $query_string, + offset => 0, + num_wanted => 10, +); + +print "Total hits: $total_hits\n"; +while ( my $hit = $index->next ) { + print "$hit->{title}\n", +}</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>Lucy::Simple is a stripped-down interface for the Apache Lucy search engine library.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $lucy = Lucy::Simple->new( + path => '/path/to/index/', + language => 'en', +);</pre> + +<p>Create a Lucy::Simple object, +which can be used for both indexing and searching. +Both parameters <code>path</code> and <code>language</code> are required.</p> + +<ul> +<li><b>path</b> - Where the index directory should be located. +If no index is found at the specified location, +one will be created.</li> + +<li><b>language</b> - The language of the documents in your collection, +indicated by a two-letter ISO code. +12 languages are supported: +<pre>|-----------------------| +| Language | ISO code | +|-----------------------| +| Danish | da | +| Dutch | nl | +| English | en | +| Finnish | fi | +| French | fr | +| German | de | +| Italian | it | +| Norwegian | no | +| Portuguese | pt | +| Spanish | es | +| Swedish | sv | +| Russian | ru | +|-----------------------|</pre> +</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="add_doc" +>add_doc</a></h3> + +<pre>$lucy->add_doc({ + location => $url, + title => $title, + content => $content, +});</pre> + +<p>Add a document to the index. +The document must be supplied as a hashref, +with field names as keys and content as values.</p> + +<h3><a class='u' +name="search" +>search</a></h3> + +<pre>my $int = $simple->search( + query => $query # required + offset => $offset # default: 0 + num_wanted => $num_wanted # default: 10 +);</pre> + +<p>Search the index. +Returns the total number of documents which match the query. +(This number is unlikely to match <code>num_wanted</code>.)</p> + +<ul> +<li><b>query</b> - A search query string.</li> + +<li><b>offset</b> - 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.</li> + +<li><b>num_wanted</b> - The number of hits you would like to see after <code>offset</code> is taken into account.</li> +</ul> + +<h3><a class='u' +name="next" +>next</a></h3> + +<pre>my $hit_doc = $simple->next();</pre> + +<p>Return the next hit, +or undef when the iterator is exhausted.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Simple isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Store/FSFolder.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Store/FSFolder.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Store/FSFolder.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Store/FSFolder.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,55 @@ +Title: Lucy::Store::FSFolder â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Store::FSFolder - File System implementation of Folder.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $folder = Lucy::Store::FSFolder->new( + path => '/path/to/folder', +);</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>Implementation of <a href="../../Lucy/Store/Folder.html" class="podlinkpod" +>Folder</a> using a single file system directory and multiple files.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $folder = Lucy::Store::FSFolder->new( + path => '/path/to/folder', +);</pre> + +<p>Create a new Folder.</p> + +<ul> +<li><b>path</b> - Location of the index. +If the specified directory does not exist already, +it will NOT be created, +in order to prevent misconfigured read applications from spawning bogus files – so it may be necessary to create the directory yourself.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Store::FSFolder isa <a href="../../Lucy/Store/Folder.html" class="podlinkpod" +>Lucy::Store::Folder</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Store/Folder.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Store/Folder.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Store/Folder.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Store/Folder.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,39 @@ +Title: Lucy::Store::Folder â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Store::Folder - Abstract class representing a directory.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre># Abstract base class.</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>A “file” within a Folder might be a real file on disk – or it might be a RAM buffer. +Similarly, +Delete() might delete a file from the file system, +or a key-value pair from a hash, +or something else.</p> + +<p>The archetypal implementation of Folder, +<a href="../../Lucy/Store/FSFolder.html" class="podlinkpod" +>FSFolder</a>, +represents a directory on the file system holding a collection of files.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Store::Folder isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Store/Lock.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Store/Lock.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Store/Lock.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Store/Lock.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,155 @@ +Title: Lucy::Store::Lock â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Store::Lock - Abstract class representing an interprocess mutex lock.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $lock = $lock_factory->make_lock( + name => 'write', + timeout => 5000, +); +$lock->obtain or die "can't get lock for " . $lock->get_name; +do_stuff(); +$lock->release;</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>The Lock class produces an interprocess mutex lock. +The default subclass uses dot-lock files, +but alternative implementations are possible.</p> + +<p>Each lock must have a name which is unique per resource to be locked. +Each lock also has a “host” id which should be unique per machine; it is used to help clear away stale locks.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $lock = Lucy::Store::Lock->new( + name => 'commit', # required + folder => $folder, # required + host => $hostname, # required + timeout => 5000, # default: 0 + interval => 1000, # default: 100 +);</pre> + +<p>Abstract constructor.</p> + +<ul> +<li><b>folder</b> - A Folder.</li> + +<li><b>name</b> - String identifying the resource to be locked, +which must consist solely of characters matching [-_.A-Za-z0-9].</li> + +<li><b>host</b> - A unique per-machine identifier.</li> + +<li><b>timeout</b> - Time in milliseconds to keep retrying before abandoning the attempt to <a href="#obtain" class="podlinkpod" +>obtain()</a> a lock.</li> + +<li><b>interval</b> - Time in milliseconds between retries.</li> +</ul> + +<h2><a class='u' +name="ABSTRACT_METHODS" +>ABSTRACT METHODS</a></h2> + +<h3><a class='u' +name="shared" +>shared</a></h3> + +<pre>my $bool = $lock->shared();</pre> + +<p>Returns true if the Lock is shared, +false if the Lock is exclusive.</p> + +<h3><a class='u' +name="request" +>request</a></h3> + +<pre>my $bool = $lock->request();</pre> + +<p>Make one attempt to acquire the lock.</p> + +<p>The semantics of <a href="#request" class="podlinkpod" +>request()</a> differ depending on whether <a href="#shared" class="podlinkpod" +>shared()</a> returns true. +If the Lock is <a href="#shared" class="podlinkpod" +>shared()</a>, +then <a href="#request" class="podlinkpod" +>request()</a> should not fail if another lock is held against the resource identified by <code>name</code> (though it might fail for other reasons). +If it is not <a href="#shared" class="podlinkpod" +>shared()</a> – i.e. +it’s an exclusive (write) lock – then other locks should cause <a href="#request" class="podlinkpod" +>request()</a> to fail.</p> + +<p>Returns: true on success, +false on failure (sets the global error object returned by Clownfish->error).</p> + +<h3><a class='u' +name="release" +>release</a></h3> + +<pre>$lock->release();</pre> + +<p>Release the lock.</p> + +<h3><a class='u' +name="is_locked" +>is_locked</a></h3> + +<pre>my $bool = $lock->is_locked();</pre> + +<p>Indicate whether the resource identified by this lock’s name is currently locked.</p> + +<p>Returns: true if the resource is locked, +false otherwise.</p> + +<h3><a class='u' +name="clear_stale" +>clear_stale</a></h3> + +<pre>$lock->clear_stale();</pre> + +<p>Release all locks that meet the following three conditions: the lock name matches, +the host id matches, +and the process id that the lock was created under no longer identifies an active process.</p> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="obtain" +>obtain</a></h3> + +<pre>my $bool = $lock->obtain();</pre> + +<p>Call <a href="#request" class="podlinkpod" +>request()</a> once per <code>interval</code> until <a href="#request" class="podlinkpod" +>request()</a> returns success or the <code>timeout</code> has been reached.</p> + +<p>Returns: true on success, +false on failure (sets the global error object returned by Clownfish->error).</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Store::Lock isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Store/LockErr.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Store/LockErr.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Store/LockErr.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Store/LockErr.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,43 @@ +Title: Lucy::Store::LockErr â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Store::LockErr - Lock exception.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>while (1) { + my $bg_merger = eval { + Lucy::Index::BackgroundMerger->new( index => $index ); + }; + if ( blessed($@) and $@->isa("Lucy::Store::LockErr") ) { + warn "Retrying...\n"; + } + elsif (!$bg_merger) { + # Re-throw. + die "Failed to open BackgroundMerger: $@"; + } + ... +}</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>LockErr is a subclass of <a href="../../Clownfish/Err.html" class="podlinkpod" +>Err</a> which indicates that a file locking problem occurred.</p> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Store::LockErr isa Clownfish::Err isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Store/LockFactory.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Store/LockFactory.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Store/LockFactory.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Store/LockFactory.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,120 @@ +Title: Lucy::Store::LockFactory â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Store::LockFactory - Create Locks.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>use Sys::Hostname qw( hostname ); +my $hostname = hostname() or die "Can't get unique hostname"; +my $folder = Lucy::Store::FSFolder->new( + path => '/path/to/index', +); +my $lock_factory = Lucy::Store::LockFactory->new( + folder => $folder, + host => $hostname, +); +my $write_lock = $lock_factory->make_lock( + name => 'write', + timeout => 5000, + interval => 100, +);</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>LockFactory is used to spin off interprocess mutex locks used by various index reading and writing components. +The default implementation uses lockfiles, +but LockFactory subclasses which are implemented using alternatives such as flock() are possible.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $lock_factory = Lucy::Store::LockFactory->new( + folder => $folder, # required + host => $hostname, # required +);</pre> + +<p>Create a new LockFactory.</p> + +<ul> +<li><b>folder</b> - A <a href="../../Lucy/Store/Folder.html" class="podlinkpod" +>Folder</a>.</li> + +<li><b>host</b> - An identifier which should be unique per-machine.</li> +</ul> + +<h2><a class='u' +name="METHODS" +>METHODS</a></h2> + +<h3><a class='u' +name="make_lock" +>make_lock</a></h3> + +<pre>my $lock = $lock_factory->make_lock( + name => $name # required + timeout => $timeout # default: 0 + interval => $interval # default: 100 +);</pre> + +<p>Return a Lock object, +which, +once <a href="../../Lucy/Store/Lock.html#obtain" class="podlinkpod" +>obtain()</a> returns successfully, +maintains an exclusive lock on a resource.</p> + +<ul> +<li><b>name</b> - A file-system-friendly id which identifies the resource to be locked.</li> + +<li><b>timeout</b> - Time in milliseconds to keep retrying before abandoning the attempt to <a href="../../Lucy/Store/Lock.html#obtain" class="podlinkpod" +>obtain()</a> a lock.</li> + +<li><b>interval</b> - Time in milliseconds between retries.</li> +</ul> + +<h3><a class='u' +name="make_shared_lock" +>make_shared_lock</a></h3> + +<pre>my $lock = $lock_factory->make_shared_lock( + name => $name # required + timeout => $timeout # default: 0 + interval => $interval # default: 100 +);</pre> + +<p>Return a Lock object for which <a href="../../Lucy/Store/Lock.html#shared" class="podlinkpod" +>shared()</a> returns true, +and which maintains a non-exclusive lock on a resource once <a href="../../Lucy/Store/Lock.html#obtain" class="podlinkpod" +>obtain()</a> returns success.</p> + +<ul> +<li><b>name</b> - A file-system-friendly id which identifies the resource to be locked.</li> + +<li><b>timeout</b> - Time in milliseconds to keep retrying before abandoning the attempt to <a href="../../Lucy/Store/Lock.html#obtain" class="podlinkpod" +>obtain()</a> a lock.</li> + +<li><b>interval</b> - Time in milliseconds between retries.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Store::LockFactory isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/Lucy/Store/RAMFolder.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Lucy/Store/RAMFolder.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/Lucy/Store/RAMFolder.mdtext (added) +++ lucy/site/trunk/content/docs/perl/Lucy/Store/RAMFolder.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,57 @@ +Title: Lucy::Store::RAMFolder â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>Lucy::Store::RAMFolder - In-memory Folder implementation.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre>my $folder = Lucy::Store::RAMFolder->new; + +# or sometimes... +my $folder = Lucy::Store::RAMFolder->new( + path => $relative_path, +);</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>RAMFolder is an entirely in-memory implementation of <a href="../../Lucy/Store/Folder.html" class="podlinkpod" +>Folder</a>, +primarily used for testing and development.</p> + +<h2><a class='u' +name="CONSTRUCTORS" +>CONSTRUCTORS</a></h2> + +<h3><a class='u' +name="new" +>new</a></h3> + +<pre>my $folder = Lucy::Store::RAMFolder->new( + path => $relative_path, # default: empty string +);</pre> + +<p>Create a new RAMFolder.</p> + +<ul> +<li><b>path</b> - Relative path, +used for subfolders.</li> +</ul> + +<h2><a class='u' +name="INHERITANCE" +>INHERITANCE</a></h2> + +<p>Lucy::Store::RAMFolder isa <a href="../../Lucy/Store/Folder.html" class="podlinkpod" +>Lucy::Store::Folder</a> isa Clownfish::Obj.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocReader.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocReader.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocReader.mdtext (added) +++ lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocReader.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,25 @@ +Title: LucyX::Index::ByteBufDocReader â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>LucyX::Index::ByteBufDocReader - Read a Doc as a fixed-width byte array.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<pre># See LucyX::Index::ByteBufDocWriter</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>This is a proof-of-concept class to demonstrate alternate implementations for fetching documents. +It is unsupported.</p> + +</div> Added: lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocWriter.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocWriter.mdtext?rev=1737642&view=auto ============================================================================== --- lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocWriter.mdtext (added) +++ lucy/site/trunk/content/docs/perl/LucyX/Index/ByteBufDocWriter.mdtext Mon Apr 4 09:22:30 2016 @@ -0,0 +1,90 @@ +Title: LucyX::Index::ByteBufDocWriter â Apache Lucy Documentation + +<div> +<a name='___top' class='dummyTopAnchor' ></a> + +<h2><a class='u' +name="NAME" +>NAME</a></h2> + +<p>LucyX::Index::ByteBufDocWriter - Write a Doc as a fixed-width byte array.</p> + +<h2><a class='u' +name="SYNOPSIS" +>SYNOPSIS</a></h2> + +<p>Create an <a href="../../Lucy/Plan/Architecture.html" class="podlinkpod" +>Architecture</a> subclass which overrides register_doc_writer() and register_doc_reader():</p> + +<pre>package MyArchitecture; +use base qw( Lucy::Plan::Architecture ); +use LucyX::Index::ByteBufDocReader; +use LucyX::Index::ByteBufDocWriter; + +sub register_doc_writer { + my ( $self, $seg_writer ) = @_; + my $doc_writer = LucyX::Index::ByteBufDocWriter->new( + width => 16, + field => 'value', + snapshot => $seg_writer->get_snapshot, + segment => $seg_writer->get_segment, + polyreader => $seg_writer->get_polyreader, + ); + $seg_writer->register( + api => "Lucy::Index::DocReader", + component => $doc_writer, + ); + $seg_writer->add_writer($doc_writer); +} + +sub register_doc_reader { + my ( $self, $seg_reader ) = @_; + my $doc_reader = LucyX::Index::ByteBufDocReader->new( + width => 16, + field => 'value', + schema => $seg_reader->get_schema, + folder => $seg_reader->get_folder, + segments => $seg_reader->get_segments, + seg_tick => $seg_reader->get_seg_tick, + snapshot => $seg_reader->get_snapshot, + ); + $seg_reader->register( + api => 'Lucy::Index::DocReader', + component => $doc_reader, + ); +} + +package MySchema; +use base qw( Lucy::Plan::Schema ); + +sub architecture { MyArchitecture->new }</pre> + +<p>Proceed as normal in your indexer app, +making sure that every supplied document supplies a valid value for the field in question:</p> + +<pre>$indexer->add_doc({ + title => $title, + content => $content, + id => $id, # <---- Must meet spec. +});</pre> + +<p>Then, +in your search app:</p> + +<pre>my $searcher = Lucy::Search::IndexSearcher->new( + index => '/path/to/index', +); +my $hits = $searcher->hits( query => $query ); +while ( my $id = $hits->next ) { + my $real_doc = $external_document_source->fetch( $doc->{value} ); + ... +}</pre> + +<h2><a class='u' +name="DESCRIPTION" +>DESCRIPTION</a></h2> + +<p>This is a proof-of-concept class to demonstrate alternate implementations for fetching documents. +It is unsupported.</p> + +</div>
