# ***********************************************
#
# !!!! DO NOT EDIT !!!!
#
# This file was auto-generated by Build.PL.
#
# ***********************************************
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
=encoding utf8
=head1 NAME
Lucy::Search::Compiler - Query-to-Matcher compiler.
=head1 SYNOPSIS
# (Compiler is an abstract base class.)
package MyCompiler;
use base qw( Lucy::Search::Compiler );
sub make_matcher {
my $self = shift;
return MyMatcher->new( @_, compiler => $self );
}
=head1 DESCRIPTION
The purpose of the Compiler class is to take a specification in the form of
a L<Query|Lucy::Search::Query> object and compile a
L<Matcher|Lucy::Search::Matcher> object that can do real work.
The simplest Compiler subclasses – such as those associated with
constant-scoring Query types – might simply implement a L<make_matcher()|/make_matcher>
method which passes along information verbatim from the Query to the
Matcher’s constructor.
However it is common for the Compiler to perform some calculations which
affect it’s “weight” – a floating point multiplier that the Matcher will
factor into each document’s score. If that is the case, then the Compiler
subclass may wish to override L<get_weight()|/get_weight>, L<sum_of_squared_weights()|/sum_of_squared_weights>, and
L<apply_norm_factor()|/apply_norm_factor>.
Compiling a Matcher is a two stage process.
The first stage takes place during the Compiler’s construction, which is
where the Query object meets a L<Searcher|Lucy::Search::Searcher>
object for the first time. Searchers operate on a specific document
collection and they can tell you certain statistical information about the
collection – such as how many total documents are in the collection, or
how many documents in the collection a particular term is present in.
Lucy’s core Compiler classes plug this information into the classic
TF/IDF weighting algorithm to adjust the Compiler’s weight; custom
subclasses might do something similar.
The second stage of compilation is L<make_matcher()|/make_matcher>, method, which is where
the Compiler meets a L<SegReader|Lucy::Index::SegReader> object.
SegReaders are associated with a single segment within a single index on a
single machine, and are thus lower-level than Searchers, which may
represent a document collection spread out over a search cluster
(comprising several indexes and many segments). The Compiler object can
use new information supplied by the SegReader – such as whether a term is
missing from the local index even though it is present within the larger
collection represented by the Searcher – when figuring out what to feed to
the Matchers’s constructor, or whether L<make_matcher()|/make_matcher> should return a
Matcher at all.
=head1 CONSTRUCTORS
=head2 new
my $compiler = MyCompiler->SUPER::new(
parent => $my_query,
searcher => $searcher,
similarity => $sim, # default: undef
boost => undef, # default: see below
);
Abstract constructor.
=over
=item *
B<parent> - The parent Query.
=item *
B<searcher> - A Lucy::Search::Searcher, such as an
IndexSearcher.
=item *
B<similarity> - A Similarity.
=item *
B<boost> - An arbitrary scoring multiplier. Defaults to the boost of
the parent Query.
=back
=head1 ABSTRACT METHODS
=head2 make_matcher
my $matcher = $compiler->make_matcher(
reader => $reader # required
need_score => $need_score # required
);
Factory method returning a Matcher.
=over
=item *
B<reader> - A SegReader.
=item *
B<need_score> - Indicate whether the Matcher must implement L<score()|Lucy::Search::Matcher/score>.
=back
Returns: a Matcher, or undef if the Matcher would have matched
no documents.
=head1 METHODS
=head2 get_weight
my $float = $compiler->get_weight();
Return the Compiler’s numerical weight, a scoring multiplier. By
default, returns the object’s boost.
=head2 get_similarity
my $similarity = $compiler->get_similarity();
Accessor for the Compiler’s Similarity object.
=head2 get_parent
my $query = $compiler->get_parent();
Accessor for the Compiler’s parent Query object.
=head2 sum_of_squared_weights
my $float = $compiler->sum_of_squared_weights();
Compute and return a raw weighting factor. (This quantity is used by
L<normalize()|/normalize>). By default, simply returns 1.0.
=head2 apply_norm_factor
$compiler->apply_norm_factor($factor);
Apply a floating point normalization multiplier. For a TermCompiler,
this involves multiplying its own weight by the supplied factor;
combining classes such as ORCompiler would apply the factor recursively
to their children.
The default implementation is a no-op; subclasses may wish to multiply
their internal weight by the supplied factor.
=over
=item *
B<factor> - The multiplier.
=back
=head2 normalize
$compiler->normalize();
Take a newly minted Compiler object and apply query-specific
normalization factors. Should be invoked by Query subclasses during
L<make_compiler()|Lucy::Search::Query/make_compiler> for top-level nodes.
For a TermQuery, the scoring formula is approximately:
(tf_d * idf_t / norm_d) * (tf_q * idf_t / norm_q)
L<normalize()|/normalize> is theoretically concerned with applying the second half of
that formula to a the Compiler’s weight. What actually happens depends
on how the Compiler and Similarity methods called internally are
implemented.
=head1 INHERITANCE
Lucy::Search::Compiler isa L<Lucy::Search::Query> isa Clownfish::Obj.
=cut