xapian-bindings/xapian-headers.i

   1 %{
   2 /* xapian-headers.i: Getting SWIG to parse Xapian's C++ headers.
   3  *
   4  * Copyright 2004-2024 Olly Betts
   5  * Copyright 2014 Assem Chelli
   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
  24 /* Ignore these functions: */
  25 %ignore Xapian::iterator_rewind;
  26 %ignore Xapian::iterator_valid;
  27
  28 /* Ignore anything ending in an underscore, which is for internal use only: */
  29 %rename("$ignore", regexmatch$name="_$") "";
  30
  31 /* A class which can usefully be subclassed in the target language. */
  32 %define SUBCLASSABLE(NS, CLASS)
  33     %ignore NS::CLASS::clone;
  34     %ignore NS::CLASS::serialise;
  35     %ignore NS::CLASS::unserialise;
  36     %#ifdef XAPIAN_SWIG_DIRECTORS
  37     %feature(director) NS::CLASS;
  38     %#endif
  39 %enddef
  40
  41 /* A class which is only useful to wrap if the target language allows
  42  * subclassing of wrapped classes (what SWIG calls "director support").
  43  */
  44 #ifdef XAPIAN_SWIG_DIRECTORS
  45 #define SUBCLASSABLE_ONLY(NS, CLASS) SUBCLASSABLE(NS, CLASS)
  46 #else
  47 #define SUBCLASSABLE_ONLY(NS, CLASS) %ignore NS::CLASS;
  48 #endif
  49
  50 #ifdef SWIGTCL
  51 /* Tcl needs copy constructors it seems. */
  52 %define STANDARD_IGNORES(NS, CLASS)
  53     %ignore NS::CLASS::internal;
  54     %ignore NS::CLASS::CLASS(Internal*);
  55     %ignore NS::CLASS::CLASS(Internal&);
  56     %ignore NS::CLASS::operator=;
  57     %ignore NS::CLASS::CLASS(CLASS &&);
  58 %enddef
  59 #else
  60 %define STANDARD_IGNORES(NS, CLASS)
  61     %ignore NS::CLASS::internal;
  62     %ignore NS::CLASS::CLASS(Internal*);
  63     %ignore NS::CLASS::CLASS(Internal&);
  64     %ignore NS::CLASS::operator=;
  65     %ignore NS::CLASS::CLASS(const CLASS &);
  66     %ignore NS::CLASS::CLASS(CLASS &&);
  67 %enddef
  68 #endif
  69
  70 #ifdef SWIGCSHARP
  71 /* In C#, next and prev return the iterator object. */
  72 #define INC_OR_DEC(METHOD, OP, NS, CLASS, RET_TYPE) NS::CLASS METHOD() { return OP(*self); }
  73 #elif defined SWIGJAVA
  74 /* In Java, next and prev return the result of dereferencing the iterator. */
  75 #define INC_OR_DEC(METHOD, OP, NS, CLASS, RET_TYPE) RET_TYPE METHOD() { return *(OP(*self)); }
  76 #else
  77 /* Otherwise, next and prev return void. */
  78 #define INC_OR_DEC(METHOD, OP, NS, CLASS, RET_TYPE) void METHOD() { OP(*self); }
  79 #endif
  80
  81 #ifdef SWIGPERL
  82 /* In Perl, use inc() and dec() instead of next() and prev(). */
  83 #define NEXT_METHOD inc
  84 #define PREV_METHOD dec
  85 #define OPERATOR_EQ(NS, CLASS) bool equal(const NS::CLASS & o) const { return *self == o; }
  86 #define OPERATOR_NE(NS, CLASS) bool nequal(const NS::CLASS & o) const { return *self != o; }
  87 #else
  88 #define NEXT_METHOD next
  89 #define PREV_METHOD prev
  90 #define OPERATOR_EQ(NS, CLASS) bool equals(const NS::CLASS & o) const { return *self == o; }
  91 #define OPERATOR_NE(NS, CLASS)
  92 #endif
  93
  94 /* For other languages, SWIG already renames operator() suitably. */
  95 #if defined SWIGJAVA || defined SWIGPHP || defined SWIGTCL
  96 %rename(apply) *::operator();
  97 #elif defined SWIGCSHARP
  98 %rename(Apply) *::operator();
  99 #endif
 100
 101 /* We use %ignore and %extend rather than %rename on operator* so that any
 102  * pattern rename used to match local naming conventions applies to
 103  * DEREF_METHOD.
 104  */
 105 %define INPUT_ITERATOR_METHODS(NS, CLASS, RET_TYPE, DEREF_METHOD)
 106     STANDARD_IGNORES(NS, CLASS)
 107     %ignore NS::CLASS::operator++;
 108     %ignore NS::CLASS::operator*;
 109     %extend NS::CLASS {
 110         OPERATOR_EQ(NS, CLASS)
 111         OPERATOR_NE(NS, CLASS)
 112         RET_TYPE DEREF_METHOD() const { return **self; }
 113         INC_OR_DEC(NEXT_METHOD, ++, NS, CLASS, RET_TYPE)
 114     }
 115 %enddef
 116
 117 %define RANDOM_ACCESS_ITERATOR_METHODS(NS, CLASS, RET_TYPE, DEREF_METHOD)
 118     INPUT_ITERATOR_METHODS(NS, CLASS, RET_TYPE, DEREF_METHOD)
 119     %ignore NS::CLASS::operator--;
 120     %ignore NS::CLASS::operator+=;
 121     %ignore NS::CLASS::operator-=;
 122     %ignore NS::CLASS::operator+;
 123     %ignore NS::CLASS::operator-;
 124     %extend NS::CLASS {
 125         INC_OR_DEC(PREV_METHOD, --, NS, CLASS, RET_TYPE)
 126     }
 127 %enddef
 128
 129 %define CONSTANT(TYPE, NS, NAME)
 130     %ignore NS::NAME;
 131     %constant TYPE NAME = NS::NAME;
 132 %enddef
 133
 134 /* Ignore these for all classes: */
 135 %ignore operator==;
 136 %ignore operator!=;
 137 %ignore operator<;
 138 %ignore operator>;
 139 %ignore operator<=;
 140 %ignore operator>=;
 141 %ignore operator+;
 142 %ignore difference_type;
 143 %ignore iterator_category;
 144 %ignore value_type;
 145 %ignore max_size;
 146 %ignore swap;
 147 %ignore iterator;
 148 %ignore const_iterator;
 149 %ignore size_type;
 150 %ignore unserialise(const char **, const char *);
 151 %ignore release();
 152
 153 /* These methods won't throw exceptions. */
 154 %exception Xapian::major_version "$action"
 155 %exception Xapian::minor_version "$action"
 156 %exception Xapian::revision "$action"
 157 %exception Xapian::version_string "$action"
 158 // For XAPIAN_DOCID_BASE_TYPE and XAPIAN_TERMCOUNT_BASE_TYPE:
 159 %import <xapian/version.h>
 160 %include <xapian.h>
 161
 162 // Disable errors about not including headers individually.
 163 #define XAPIAN_IN_XAPIAN_H
 164
 165 /* We don't wrap the version macros - they're useful for compile time checks
 166  * in C++ code, but for a scripting language, the version functions tell us
 167  * the version of Xapian we're actually using, which is more interesting than
 168  * the one the bindings were built against.
 169  */
 170 /* %include <xapian/version.h> */
 171
 172 CONSTANT(Xapian::valueno, Xapian, BAD_VALUENO);
 173
 174 /* Types are needed by most of the other headers. */
 175 %include <xapian/types.h>
 176
 177 CONSTANT(int, Xapian, DB_CREATE);
 178 CONSTANT(int, Xapian, DB_CREATE_OR_OPEN);
 179 CONSTANT(int, Xapian, DB_CREATE_OR_OVERWRITE);
 180 CONSTANT(int, Xapian, DB_OPEN);
 181 CONSTANT(int, Xapian, DB_NO_SYNC);
 182 CONSTANT(int, Xapian, DB_FULL_SYNC);
 183 CONSTANT(int, Xapian, DB_DANGEROUS);
 184 CONSTANT(int, Xapian, DB_NO_TERMLIST);
 185 CONSTANT(int, Xapian, DB_BACKEND_CHERT);
 186 CONSTANT(int, Xapian, DB_BACKEND_GLASS);
 187 CONSTANT(int, Xapian, DB_BACKEND_HONEY);
 188 CONSTANT(int, Xapian, DB_BACKEND_INMEMORY);
 189 CONSTANT(int, Xapian, DB_BACKEND_STUB);
 190 CONSTANT(int, Xapian, DB_RETRY_LOCK);
 191 CONSTANT(int, Xapian, DBCHECK_SHORT_TREE);
 192 CONSTANT(int, Xapian, DBCHECK_FULL_TREE);
 193 CONSTANT(int, Xapian, DBCHECK_SHOW_FREELIST);
 194 CONSTANT(int, Xapian, DBCHECK_SHOW_STATS);
 195 CONSTANT(int, Xapian, DBCHECK_FIX);
 196 CONSTANT(int, Xapian, DBCOMPACT_MULTIPASS);
 197 CONSTANT(int, Xapian, DBCOMPACT_NO_RENUMBER);
 198 CONSTANT(int, Xapian, DBCOMPACT_SINGLE_FILE);
 199 CONSTANT(int, Xapian, DOC_ASSUME_VALID);
 200 %include <xapian/constants.h>
 201
 202 /* The Error subclasses are handled separately for languages where we wrap
 203  * them. */
 204 /* %include <xapian/error.h> */
 205
 206 INPUT_ITERATOR_METHODS(Xapian, PositionIterator, Xapian::termpos, get_termpos)
 207 %include <xapian/positioniterator.h>
 208
 209 %ignore Xapian::DocIDWrapper;
 210 INPUT_ITERATOR_METHODS(Xapian, PostingIterator, Xapian::docid, get_docid)
 211 %include <xapian/postingiterator.h>
 212
 213 INPUT_ITERATOR_METHODS(Xapian, TermIterator, std::string, get_term)
 214 %include <xapian/termiterator.h>
 215
 216 INPUT_ITERATOR_METHODS(Xapian, ValueIterator, std::string, get_value)
 217 %include <xapian/valueiterator.h>
 218
 219 STANDARD_IGNORES(Xapian, Document)
 220 %include <xapian/document.h>
 221
 222 STANDARD_IGNORES(Xapian, Registry)
 223 %include <xapian/registry.h>
 224
 225 STANDARD_IGNORES(Xapian, Query)
 226 %ignore Xapian::Query::Internal;
 227 %ignore operator Query;
 228 %ignore *::operator&(const Xapian::Query &, const Xapian::InvertedQuery_ &);
 229 %ignore *::operator~;
 230 %ignore *::operator&=;
 231 %ignore ::operator&=;
 232 %ignore *::operator|=;
 233 %ignore *::operator^=;
 234 %ignore *::operator*=;
 235 %ignore *::operator/=;
 236 %ignore *::operator&;
 237 %ignore *::operator|;
 238 %ignore *::operator^;
 239 %ignore *::operator*;
 240 %ignore *::operator/;
 241 %ignore Xapian::Query::LEAF_TERM;
 242 %ignore Xapian::Query::LEAF_POSTING_SOURCE;
 243 %ignore Xapian::Query::LEAF_MATCH_ALL;
 244 %ignore Xapian::Query::LEAF_MATCH_NOTHING;
 245
 246 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::Query::Internal;
 247 #if defined SWIGCSHARP || defined SWIGJAVA || defined SWIGPERL || \
 248     defined SWIGPYTHON || defined SWIGRUBY
 249 // C#, Java, Perl, Python and Ruby wrap these "by hand" to give a nicer API
 250 // than SWIG gives by default.
 251 %ignore Xapian::Query::MatchAll;
 252 %ignore Xapian::Query::MatchNothing;
 253 #endif
 254 #ifndef XAPIAN_MIXED_SUBQUERIES_BY_ITERATOR_TYPEMAP
 255 %ignore Query(op op_, XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend,
 256               Xapian::termcount parameter = 0);
 257 #endif
 258 %ignore Xapian::Query::Query(const std::string&, Xapian::termcount = 1, Xapian::termpos = 0);
 259 %ignore Xapian::Query::Query(const char*, Xapian::termcount = 1, Xapian::termpos = 0);
 260 %extend Xapian::Query {
 261     Query(op op_, std::string_view a, std::string_view b) {
 262         return new Xapian::Query(op_, a, b);
 263     }
 264 }
 265 %include <xapian/query.h>
 266
 267 // Suppress warning that Xapian::Internal::intrusive_base is unknown.
 268 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::StemImplementation;
 269 SUBCLASSABLE_ONLY(Xapian, StemImplementation)
 270 #ifndef XAPIAN_SWIG_DIRECTORS
 271 %ignore Xapian::Stem::Stem(Xapian::StemImplementation *);
 272 #endif
 273 STANDARD_IGNORES(Xapian, Stem)
 274 %ignore Xapian::Stem::Stem();
 275 %include <xapian/stem.h>
 276
 277 STANDARD_IGNORES(Xapian, TermGenerator)
 278 %ignore Xapian::TermGenerator::operator=;
 279 /* Ignore forms which use Utf8Iterator, as we don't wrap that class. */
 280 %ignore Xapian::TermGenerator::index_text(const Xapian::Utf8Iterator&);
 281 %ignore Xapian::TermGenerator::index_text(const Xapian::Utf8Iterator&, Xapian::termcount);
 282 %ignore Xapian::TermGenerator::index_text(const Xapian::Utf8Iterator&, Xapian::termcount, std::string_view);
 283 %ignore Xapian::TermGenerator::index_text_without_positions(const Xapian::Utf8Iterator&);
 284 %ignore Xapian::TermGenerator::index_text_without_positions(const Xapian::Utf8Iterator&, Xapian::termcount);
 285 %ignore Xapian::TermGenerator::index_text_without_positions(const Xapian::Utf8Iterator&, Xapian::termcount, std::string_view);
 286 %ignore Xapian::TermGenerator::TermGenerator(const TermGenerator &);
 287 %include <xapian/termgenerator.h>
 288
 289 STANDARD_IGNORES(Xapian, MSet)
 290 #ifdef SWIGJAVA
 291 // For compatibility with the original JNI wrappers.
 292 %rename("getElement") Xapian::MSet::operator[];
 293 #else
 294 %ignore Xapian::MSet::operator[];
 295 #endif
 296 %extend Xapian::MSet {
 297     Xapian::docid get_docid(Xapian::doccount i) const {
 298         return *(*self)[i];
 299     }
 300
 301     Xapian::Document get_document(Xapian::doccount i) const {
 302         return (*self)[i].get_document();
 303     }
 304
 305     Xapian::MSetIterator get_hit(Xapian::doccount i) const {
 306         return (*self)[i];
 307     }
 308
 309     int get_document_percentage(Xapian::doccount i) const {
 310         return self->convert_to_percent((*self)[i]);
 311     }
 312 }
 313
 314 RANDOM_ACCESS_ITERATOR_METHODS(Xapian, MSetIterator, Xapian::docid, get_docid)
 315
 316 %include <xapian/mset.h>
 317
 318 STANDARD_IGNORES(Xapian, ESet)
 319 %ignore Xapian::ESet::operator[];
 320
 321 RANDOM_ACCESS_ITERATOR_METHODS(Xapian, ESetIterator, std::string, get_term)
 322
 323 %include <xapian/eset.h>
 324
 325 STANDARD_IGNORES(Xapian, RSet)
 326
 327 %include <xapian/rset.h>
 328
 329 SUBCLASSABLE(Xapian, MatchDecider)
 330
 331 %include <xapian/matchdecider.h>
 332
 333 STANDARD_IGNORES(Xapian, Enquire)
 334
 335 #ifdef XAPIAN_TERMITERATOR_PAIR_OUTPUT_TYPEMAP
 336 /* Instantiating the template we're going to use avoids SWIG wrapping uses
 337  * of it in SwigValueWrapper.
 338  */
 339 %template() std::pair<Xapian::TermIterator, Xapian::TermIterator>;
 340
 341 %extend Xapian::Enquire {
 342     /* This returns start and end iterators, then a typemap iterates between
 343      * those and returns an array of strings in the target language.
 344      */
 345     std::pair<Xapian::TermIterator, Xapian::TermIterator>
 346     get_matching_terms(const Xapian::MSetIterator & item) const {
 347         return std::make_pair($self->get_matching_terms_begin(item),
 348                               $self->get_matching_terms_end(item));
 349     }
 350 }
 351 #endif
 352
 353 %include <xapian/enquire.h>
 354
 355 SUBCLASSABLE(Xapian, ExpandDecider)
 356 // Suppress warning that Xapian::Internal::opt_intrusive_base is unknown.
 357 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::ExpandDecider;
 358 %ignore Xapian::ExpandDeciderAnd::ExpandDeciderAnd(const ExpandDecider *, const ExpandDecider *);
 359 /* FIXME: %extend ExpandDeciderFilterTerms so it can be constructed from an
 360  * array of strings (or whatever the equivalent is in the target language).
 361  */
 362 %ignore Xapian::ExpandDeciderFilterTerms;
 363 %include <xapian/expanddecider.h>
 364
 365 SUBCLASSABLE(Xapian, KeyMaker)
 366 // Suppress warning that Xapian::Internal::opt_intrusive_base is unknown.
 367 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::KeyMaker;
 368 %include <xapian/keymaker.h>
 369
 370 %extend Xapian::SimpleStopper {
 371     /** Load stop words from a text file (one word per line). */
 372     SimpleStopper(const std::string &file) {
 373         ifstream in_file(file.c_str());
 374         if (!in_file.is_open())
 375             throw Xapian::InvalidArgumentError("Stopword file not found: " + file);
 376         istream_iterator<std::string> in_iter(in_file);
 377         istream_iterator<std::string> eof;
 378         return new Xapian::SimpleStopper(in_iter, eof);
 379     }
 380 }
 381
 382 SUBCLASSABLE(Xapian, FieldProcessor)
 383 // Suppress warning that Xapian::Internal::opt_intrusive_base is unknown.
 384 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::Stopper;
 385 SUBCLASSABLE(Xapian, RangeProcessor)
 386 SUBCLASSABLE(Xapian, Stopper)
 387 // Suppress warning that Xapian::Internal::opt_intrusive_base is unknown.
 388 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::RangeProcessor;
 389 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::FieldProcessor;
 390 STANDARD_IGNORES(Xapian, QueryParser)
 391 %ignore Xapian::QueryParser::QueryParser(const QueryParser &);
 392 CONSTANT(int, Xapian, RP_SUFFIX);
 393 CONSTANT(int, Xapian, RP_REPEATED);
 394 CONSTANT(int, Xapian, RP_DATE_PREFER_MDY);
 395 %include <xapian/queryparser.h>
 396
 397 %include <xapian/valuesetmatchdecider.h>
 398
 399 /* Xapian::Weight isn't usefully subclassable via the bindings, as clone()
 400  * needs to be implemented for it to be usable for weighting a search.  But
 401  * there are several supplied weighting schemes implemented in C++ which can
 402  * usefully be used via the bindings so we wrap those.
 403  */
 404 STANDARD_IGNORES(Xapian, Weight)
 405 /* The copy constructor isn't implemented, but is protected rather than
 406  * private to work around a compiler bug, so we ignore it explicitly.
 407  */
 408 %ignore Xapian::Weight::Weight(const Weight &);
 409 %ignore Xapian::Weight::clone;
 410 %ignore Xapian::Weight::serialise;
 411 %ignore Xapian::Weight::unserialise;
 412 %include <xapian/weight.h>
 413
 414 /* We don't wrap Xapian's Unicode support as other languages usually already
 415  * have their own Unicode support. */
 416 /* %include <xapian/unicode.h> */
 417
 418 SUBCLASSABLE(Xapian, Compactor)
 419 %include <xapian/compactor.h>
 420
 421 SUBCLASSABLE(Xapian, PostingSource)
 422 // Suppress warning that Xapian::Internal::opt_intrusive_base is unknown.
 423 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::PostingSource;
 424 SUBCLASSABLE(Xapian, ValuePostingSource)
 425 SUBCLASSABLE(Xapian, ValueWeightPostingSource)
 426 %ignore Xapian::PostingSource::unserialise_with_registry;
 427 %include <xapian/postingsource.h>
 428
 429 // Suppress warning that Xapian::Internal::intrusive_base is unknown.
 430 %warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Xapian::MatchSpy;
 431 SUBCLASSABLE(Xapian, MatchSpy)
 432 %ignore Xapian::MatchSpy::serialise_results;
 433 %include <xapian/matchspy.h>
 434
 435 SUBCLASSABLE(Xapian, LatLongMetric)
 436 INPUT_ITERATOR_METHODS(Xapian, LatLongCoordsIterator, LatLongCoord, get_coord)
 437 %ignore Xapian::LatLongCoord::operator<;
 438 %include <xapian/geospatial.h>
 439
 440 STANDARD_IGNORES(Xapian, Database)
 441 STANDARD_IGNORES(Xapian, WritableDatabase)
 442 %ignore Xapian::WritableDatabase::WritableDatabase(Database::Internal *);
 443 %ignore Xapian::Database::check(std::string_view, int, std::ostream*);
 444 %ignore Xapian::Database::check(int fd, int, std::ostream*);
 445 %include <xapian/database.h>
 446 %extend Xapian::Database {
 447     static size_t check(std::string_view path, int opts = 0) {
 448         return Xapian::Database::check(path, opts, opts ? &std::cout : NULL);
 449     }
 450 }
 451
 452 #if defined SWIGCSHARP || defined SWIGJAVA
 453
 454 /* C# and Java don't allow functions outside a class so we can't use SWIG's
 455  * %nspace feature here.  Instead we pretend to SWIG that the C++
 456  * Xapian::Remote namespace is actually a Xapian::Remote class with public
 457  * static functions.  The code SWIG generates will work fine, and we get
 458  * xapian.Remote.open() in Java and Xapian.Remote.open() in C#.
 459  */
 460
 461 namespace Xapian {
 462
 463 class Remote {
 464     // Private constructor and destructor so SWIG doesn't try to call them.
 465     Remote();
 466     ~Remote();
 467   public:
 468     static Database open(const std::string &host,
 469                          unsigned int port,
 470                          unsigned timeout = 10000,
 471                          unsigned connect_timeout = 10000);
 472
 473     static WritableDatabase open_writable(const std::string &host,
 474                                           unsigned int port,
 475                                           unsigned timeout = 0,
 476                                           unsigned connect_timeout = 10000,
 477                                           int flags = 0);
 478
 479     static Database open(const std::string &program,
 480                          const std::string &args,
 481                          unsigned timeout = 10000);
 482
 483     static WritableDatabase open_writable(const std::string &program,
 484                                           const std::string &args,
 485                                           unsigned timeout = 0,
 486                                           int flags = 0);
 487 };
 488
 489 }
 490
 491 #else
 492
 493 %rename("remote_open") Xapian::Remote::open;
 494 %rename("remote_open_writable") Xapian::Remote::open_writable;
 495
 496 %include <xapian/dbfactory.h>
 497
 498 #endif