# ***********************************************
#
# !!!! 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::Highlight::Highlighter - Create and highlight excerpts.
=head1 SYNOPSIS
my $highlighter = Lucy::Highlight::Highlighter->new(
searcher => $searcher,
query => $query,
field => 'body'
);
my $hits = $searcher->hits( query => $query );
while ( my $hit = $hits->next ) {
my $excerpt = $highlighter->create_excerpt($hit);
...
}
=head1 DESCRIPTION
The Highlighter can be used to select relevant snippets from a document,
and to surround search terms with highlighting tags. It handles both stems
and phrases correctly and efficiently, using special-purpose data generated
at index-time.
=head1 CONSTRUCTORS
=head2 new
my $highlighter = Lucy::Highlight::Highlighter->new(
searcher => $searcher, # required
query => $query, # required
field => 'content', # required
excerpt_length => 150, # default: 200
);
Create a new Highlighter.
=over
=item *
B<searcher> - An object which inherits from
L<Searcher|Lucy::Search::Searcher>, such as an
L<IndexSearcher|Lucy::Search::IndexSearcher>.
=item *
B<query> - Query object or a query string.
=item *
B<field> - The name of the field from which to draw the excerpt. The
field must marked as be C<highlightable> (see
L<FieldType|Lucy::Plan::FieldType>).
=item *
B<excerpt_length> - Maximum length of the excerpt, in characters.
=back
=head1 METHODS
=head2 create_excerpt
my $string = $highlighter->create_excerpt($hit_doc);
Take a HitDoc object and return a highlighted excerpt as a string if
the HitDoc has a value for the specified C<field>.
=head2 encode
my $string = $highlighter->encode($text);
Encode text with HTML entities. This method is called internally by
L<create_excerpt()|/create_excerpt> for each text fragment when assembling an excerpt. A
subclass can override this if the text should be encoded differently or
not at all.
=head2 highlight
my $string = $highlighter->highlight($text);
Highlight a small section of text. By default, prepends pre-tag and
appends post-tag. This method is called internally by L<create_excerpt()|/create_excerpt>
when assembling an excerpt.
=head2 set_pre_tag
$highlighter->set_pre_tag($pre_tag);
Setter. The default value is “E<lt>strongE<gt>”.
=head2 set_post_tag
$highlighter->set_post_tag($post_tag);
Setter. The default value is “E<lt>/strongE<gt>”.
=head2 get_pre_tag
my $string = $highlighter->get_pre_tag();
Accessor.
=head2 get_post_tag
my $string = $highlighter->get_post_tag();
Accessor.
=head2 get_field
my $string = $highlighter->get_field();
Accessor.
=head2 get_excerpt_length
my $int = $highlighter->get_excerpt_length();
Accessor.
=head2 get_searcher
my $searcher = $highlighter->get_searcher();
Accessor.
=head2 get_query
my $query = $highlighter->get_query();
Accessor.
=head2 get_compiler
my $compiler = $highlighter->get_compiler();
Accessor for the Lucy::Search::Compiler object derived from
C<query> and C<searcher>.
=head1 INHERITANCE
Lucy::Highlight::Highlighter isa Clownfish::Obj.
=cut