# ***********************************************
# 
# !!!! 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

