xapian-core/include/xapian/snipper.h

   1 /** @file snipper.h
   2  * @brief Generate snippets from text relevant to MSet.
   3  */
   4 /* Copyright (C) 2012 Mihai Bivol
   5  * Copyright (C) 2014 Olly Betts
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as
   9  * published by the Free Software Foundation; either version 2 of the
  10  * License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  20  * USA
  21  */
  22
  23 #ifndef XAPIAN_INCLUDED_SNIPPER_H
  24 #define XAPIAN_INCLUDED_SNIPPER_H
  25
  26 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  27 # error "Never use <xapian/snipper.h> directly; include <xapian.h> instead."
  28 #endif
  29
  30 #include <string>
  31 #include <xapian/intrusive_ptr.h>
  32 #include <xapian/types.h>
  33 #include <xapian/visibility.h>
  34
  35 namespace Xapian {
  36
  37 class MSet;
  38 class Stem;
  39
  40 /** Class used to generate snippets from a given text.
  41  *
  42  *  For generating a snippet, a MSet is needed to calculate a relevance model.
  43  */
  44 class XAPIAN_VISIBILITY_DEFAULT Snipper {
  45   public:
  46     /// Class representing snipper internals.
  47     class Internal;
  48
  49     /// @private @internal Reference counted internals.
  50     Xapian::Internal::intrusive_ptr<Internal> internal;
  51
  52     /// Default constructor.
  53     Snipper();
  54
  55     /// Copy constructor.
  56     Snipper(const Snipper & other);
  57
  58     /// Assignment.
  59     Snipper & operator=(const Snipper & other);
  60
  61     /// Destructor.
  62     ~Snipper();
  63
  64     /** Set the stemmer for the Snipper object. */
  65     void set_stemmer(const Xapian::Stem & stemmer);
  66
  67     /**
  68      * Set the MSet and calculate the relevance model according to it.
  69      *
  70      * @param mset      MSet with the documents relevant to the query.
  71      * @param rm_docno  Maximum number of documents for the relevance
  72      *                  model (default: 10).
  73      */
  74     void set_mset(const MSet & mset,
  75                   Xapian::doccount rm_docno = 10);
  76
  77     /** Generate snippet from given text.
  78      *
  79      * @param text          The text from which to generate the snippet
  80      * @param length        Maximum length of the result in bytes
  81      *                      (default: 200)
  82      * @param window_size   Size of the window (default: 25)
  83      * @param smoothing     Smoothing coefficient (default: 0.5)
  84      *
  85      * @return      Text of the snippet relevant to the model from input.
  86      */
  87     std::string generate_snippet(const std::string & text,
  88                                  size_t length = 200,
  89                                  Xapian::termcount window_size = 25,
  90                                  double smoothing = 0.5);
  91
  92     /// Return a string describing this object.
  93     std::string get_description() const;
  94 };
  95
  96 }
  97
  98 #endif /* XAPIAN_INCLUDED_SNIPPER_H */