# ***********************************************
# 
# !!!! 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::Query - A specification for a search query.

=head1 SYNOPSIS

    # 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 );
    ...

=head1 DESCRIPTION

Query objects are simple containers which contain the minimum information
necessary to define a search query.

The most common way to generate Query objects is to feed a search string
such as ‘foo AND bar’ to a L<QueryParser’s|Lucy::Search::QueryParser>
L<parse()|Lucy::Search::QueryParser/parse> method, which outputs an abstract syntax tree built up from various
Query subclasses such as L<ANDQuery|Lucy::Search::ANDQuery> and
L<TermQuery|Lucy::Search::TermQuery>.  However, it is also possible
to use custom Query objects to build a search specification which cannot be
easily represented using a search string.

Subclasses of Query must implement L<make_compiler()|/make_compiler>, which is the first step
in compiling a Query down to a L<Matcher|Lucy::Search::Matcher> which
can actually match and score documents.

=head1 CONSTRUCTORS

=head2 new

    my $query = MyQuery->SUPER::new(
        boost => 2.5,
    );

Abstract constructor.

=over

=item *

B<boost> - 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.

=back

=head1 ABSTRACT METHODS

=head2 make_compiler

    my $compiler = $query->make_compiler(
        searcher    => $searcher,     # required
        boost       => $boost,        # required
        subordinate => $subordinate,  # default: false
    );

Abstract factory method returning a Compiler derived from this Query.

=over

=item *

B<searcher> - A Searcher.

=item *

B<boost> - A scoring multiplier.

=item *

B<subordinate> - Indicates whether the Query is a subquery (as
opposed to a top-level query).  If false, the implementation must
invoke L<normalize()|Lucy::Search::Compiler/normalize> on the newly minted Compiler object before returning
it.

=back

=head1 METHODS

=head2 set_boost

    $query->set_boost($boost);

Set the Query’s boost.

=head2 get_boost

    my $float = $query->get_boost();

Get the Query’s boost.

=head2 dump

    my $obj = $query->dump();

=head2 load

    my $obj = $query->load($dump);

=head1 INHERITANCE

Lucy::Search::Query isa Clownfish::Obj.

=cut