The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
/* 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.
 */

parcel Lucy;

/** Create and highlight excerpts.
 *
 * 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.
*/
public class Lucy::Highlight::Highlighter inherits Clownfish::Obj {

    Searcher   *searcher;
    Query      *query;
    String     *field;
    uint32_t    excerpt_length;
    uint32_t    slop;
    String     *pre_tag;
    String     *post_tag;
    Compiler   *compiler;

    /** Create a new Highlighter.
     *
     * @param searcher An object which inherits from
     * [](cfish:Searcher), such as an
     * [](cfish:IndexSearcher).
     * @param query Query object or a query string.
     * @param field The name of the field from which to draw the excerpt.  The
     * field must marked as be `highlightable` (see
     * [](cfish:FieldType)).
     * @param excerpt_length Maximum length of the excerpt, in characters.
     */
    public inert incremented Highlighter*
    new(Searcher *searcher, Obj *query, String *field,
        uint32_t excerpt_length = 200);

    /** Initialize a Highlighter.
     *
     * @param searcher An object which inherits from
     * [](cfish:Searcher), such as an
     * [](cfish:IndexSearcher).
     * @param query Query object or a query string.
     * @param field The name of the field from which to draw the excerpt.  The
     * field must marked as be `highlightable` (see
     * [](cfish:FieldType)).
     * @param excerpt_length Maximum length of the excerpt, in characters.
     */
    public inert Highlighter*
    init(Highlighter *self, Searcher *searcher, Obj *query,
         String *field, uint32_t excerpt_length = 200);

    /** Take a HitDoc object and return a highlighted excerpt as a string if
     * the HitDoc has a value for the specified `field`.
     */
    public incremented String*
    Create_Excerpt(Highlighter *self, HitDoc *hit_doc);

    /** Encode text with HTML entities. This method is called internally by
     * [](cfish:.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.
     */
    public incremented String*
    Encode(Highlighter *self, String *text);

    /** Highlight a small section of text.  By default, prepends pre-tag and
     * appends post-tag.  This method is called internally by [](cfish:.Create_Excerpt)
     * when assembling an excerpt.
     */
    public incremented String*
    Highlight(Highlighter *self, String *text);

    /** Setter.  The default value is "\<strong>".
     */
    public void
    Set_Pre_Tag(Highlighter *self, String *pre_tag);

    /** Setter.  The default value is "\</strong>".
     */
    public void
    Set_Post_Tag(Highlighter *self, String *post_tag);

    /** Accessor.
     */
    public String*
    Get_Pre_Tag(Highlighter *self);

    /** Accessor.
     */
    public String*
    Get_Post_Tag(Highlighter *self);

    /** Accessor.
     */
    public String*
    Get_Field(Highlighter *self);

    /** Accessor.
     */
    public uint32_t
    Get_Excerpt_Length(Highlighter *self);

    /** Accessor.
     */
    public Searcher*
    Get_Searcher(Highlighter *self);

    /** Accessor.
     */
    public Query*
    Get_Query(Highlighter *self);

    /** Accessor for the Lucy::Search::Compiler object derived from
     * `query` and `searcher`.
     */
    public Compiler*
    Get_Compiler(Highlighter *self);

    /** Decide based on heat map the best fragment of field to concentrate on.
     * Take the fragment and determine the best edges for it based on
     * sentence boundaries when possible.  Add ellipses when boundaries cannot
     * be found.
     *
     * (Helper function for Create_Excerpt only exposed for testing purposes.)
     */
    String*
    Raw_Excerpt(Highlighter *self, String *field_value, int32_t *top,
                HeatMap *heat_map);

    /** Take the text in raw_excerpt, add highlight tags, encode, and place
     * the result into `highlighted`.
     *
     * (Helper function for Create_Excerpt only exposed for testing purposes.)
     */
    String*
    Highlight_Excerpt(Highlighter *self, Vector *spans, String *raw_excerpt,
                      int32_t top);

    public void
    Destroy(Highlighter *self);
}