xapian-bindings/ruby/ruby.i

   1 %module(directors="1") xapian
   2 %{
   3 /* ruby.i: SWIG interface file for the Ruby bindings
   4  *
   5  * Original version by Paul Legato (plegato@nks.net), 4/17/06.
   6  * Based on the php4 and python util.i files.
   7  *
   8  * Copyright (C) 2006 Networked Knowledge Systems, Inc.
   9  * Copyright (C) 2006,2007,2008,2009,2010,2011,2012,2019 Olly Betts
  10  * Copyright (C) 2010 Richard Boulton
  11  *
  12  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  25  * USA
  26  */
  27
  28 %}
  29
  30 %begin %{
  31 // The Ruby 2.3 headers contain things which cause warnings with more recent
  32 // C++ compilers.  There's nothing we can really do about them, so just
  33 // suppress them.
  34 #ifdef __clang__
  35 # pragma clang diagnostic push
  36 # pragma clang diagnostic ignored "-Wdeprecated-register"
  37 # pragma clang diagnostic ignored "-Wreserved-user-defined-literal"
  38 #elif defined __GNUC__
  39 // Warning added in GCC 4.8 and we don't support anything older.
  40 # pragma GCC diagnostic push
  41 # pragma GCC diagnostic ignored "-Wliteral-suffix"
  42 #endif
  43
  44 #if defined __clang__ && !defined _WIN32
  45 // Ruby 3.0.0 tries to use __declspec on non-Microsoft platforms because
  46 // clang's __has_declspec_attribute(x) gives 1 even when __declspec support
  47 // isn't actually enabled.  We undefine __has_declspec_attribute to avoid
  48 // this, and suppress the warning clang gives about undefining a builtin macro.
  49 # pragma clang diagnostic push
  50 # pragma clang diagnostic ignored "-Wbuiltin-macro-redefined"
  51 # undef __has_declspec_attribute
  52 # pragma clang diagnostic pop
  53 #endif
  54
  55 #include <ruby.h>
  56
  57 #ifdef __clang__
  58 # pragma clang diagnostic pop
  59 #elif defined __GNUC__
  60 # pragma GCC diagnostic pop
  61 #endif
  62 %}
  63
  64 // Use SWIG directors for Ruby wrappers.
  65 #define XAPIAN_SWIG_DIRECTORS
  66
  67 // We don't use the Iterator and ConstIterator wrappers which SWIG now offers,
  68 // so disable them to reduce the generated C++ wrapper code.
  69 #define SWIG_NO_EXPORT_ITERATOR_METHODS
  70
  71 %include ../xapian-head.i
  72
  73 /////////////////////////////////////
  74 // Rename function and method names to match Ruby conventions
  75 // e.g. from get_data to data and from set_data to data=
  76
  77 // Getters
  78 %rename("available_languages") get_available_languages;
  79 %rename("avlength") get_avlength;
  80 %rename("collapse_count") get_collapse_count;
  81 %rename("collection_freq") get_collection_freq;
  82 %rename("context") get_context;
  83 %rename("data") get_data;
  84 %rename("default_op") get_default_op;
  85 %rename("description") get_description;
  86 %rename("docid") get_docid;
  87 %rename("document_id") get_document_id;
  88 %rename("document_percentage") get_document_percentage;
  89 %rename("doccount") get_doccount;
  90 %rename("doclength") get_doclength;
  91 %rename("document") get_document;
  92 %rename("ebound") get_ebound;
  93 %rename("eset") get_eset;
  94 %rename("firstitem") get_firstitem;
  95 %rename("hit") get_hit;
  96 %rename("lastdocid") get_lastdocid;
  97 %rename("length") get_length;
  98 %rename("matches_estimated") get_matches_estimated;
  99 %rename("matches_lower_bound") get_matches_lower_bound;
 100 %rename("matches_upper_bound") get_matches_upper_bound;
 101 %rename("matching_terms") get_matching_terms;
 102 %rename("max_attained") get_max_attained;
 103 %rename("max_possible") get_max_possible;
 104 %rename("maxextra") get_maxextra;
 105 %rename("maxpart") get_maxpart;
 106 %rename("mset") get_mset;
 107 %rename("msg") get_msg;
 108 %rename("op_name") get_op_name;
 109 %rename("percent") get_percent;
 110 %rename("query") get_query;
 111 %rename("rank") get_rank;
 112 %rename("sumextra") get_sumextra;
 113 %rename("sumpart") get_sumpart;
 114 %rename("termfreq") get_termfreq;
 115 %rename("terms") get_terms;
 116 %rename("term") get_term;
 117 %rename("termpos") get_termpos;
 118 %rename("termweight") get_termweight;
 119 %rename("type") get_type;
 120 %rename("value") get_value;
 121 %rename("valueno") get_valueno;
 122 %rename("wdf") get_wdf;
 123 %rename("weight") get_weight;
 124
 125 // These are 'dangerous' methods; i.e. they can cause a segfault if used
 126 // improperly.  We prefix with _dangerous_ so that Ruby users will not use them
 127 // inadvertently.
 128 //
 129 // There is a safe wrapper for their functionality provided in xapian.rb.
 130
 131 // in Xapian::Document and Xapian::Database
 132 %rename("_dangerous_termlist_begin") termlist_begin;
 133 %rename("_dangerous_termlist_end") termlist_end;
 134 // in Xapian::Query
 135 %rename("_dangerous_terms_begin") get_terms_begin;
 136 %rename("_dangerous_terms_end") get_terms_end;
 137 // in Xapian::Query
 138 %rename("_dangerous_unique_terms_begin") get_unique_terms_begin;
 139 %rename("_dangerous_unique_terms_end") get_unique_terms_end;
 140 // in Xapian::Enquire
 141 %rename("_dangerous_matching_terms_begin") get_matching_terms_begin;
 142 %rename("_dangerous_matching_terms_end") get_matching_terms_end;
 143 // in Xapian::Database
 144 %rename("_dangerous_allterms_begin") allterms_begin;
 145 %rename("_dangerous_allterms_end") allterms_end;
 146 // in Xapian::Database
 147 %rename("_dangerous_metadata_keys_begin") metadata_keys_begin;
 148 %rename("_dangerous_metadata_keys_end") metadata_keys_end;
 149 // in Xapian::Database
 150 %rename("_dangerous_postlist_begin") postlist_begin;
 151 %rename("_dangerous_postlist_end") postlist_end;
 152 // in Xapian::Database
 153 %rename("_dangerous_positionlist_begin") positionlist_begin;
 154 %rename("_dangerous_positionlist_end") positionlist_end;
 155 // in Xapian::Database
 156 %rename("_dangerous_spellings_begin") spellings_begin;
 157 %rename("_dangerous_spellings_end") spellings_end;
 158 // in Xapian::Database
 159 %rename("_dangerous_synonyms_begin") synonyms_begin;
 160 %rename("_dangerous_synonyms_end") synonyms_end;
 161 // in Xapian::Database
 162 %rename("_dangerous_synonym_keys_begin") synonym_keys_begin;
 163 %rename("_dangerous_synonym_keys_end") synonym_keys_end;
 164 // in Xapian::Database
 165 %rename("_dangerous_valuestream_begin") valuestream_begin;
 166 %rename("_dangerous_valuestream_end") valuestream_end;
 167 // in Xapian::Document and Xapian::ValueCountMatchSpy
 168 %rename("_dangerous_values_begin") values_begin;
 169 %rename("_dangerous_values_end") values_end;
 170 // in Xapian::ValueCountMatchSpy
 171 %rename("_dangerous_top_values_begin") top_values_begin;
 172 %rename("_dangerous_top_values_end") top_values_end;
 173 // in Xapian::QueryParser
 174 %rename("_dangerous_stoplist_begin") stoplist_begin;
 175 %rename("_dangerous_stoplist_end") stoplist_end;
 176 // in Xapian::QueryParser
 177 %rename("_dangerous_unstem_begin") unstem_begin;
 178 %rename("_dangerous_unstem_end") unstem_end;
 179
 180
 181 // MSetIterators are not dangerous, just inconvenient to use within a Ruby
 182 // idiom.
 183 %rename ("_begin") begin;
 184 %rename ("_end") end;
 185 %rename ("_back") back;
 186
 187
 188
 189 // Setters
 190 %rename("collapse_key=") set_collapse_key;
 191 %rename("cutoff!") set_cutoff;
 192 %rename("data=") set_data;
 193 %rename("database=") set_database;
 194 %rename("default_op=") set_default_op;
 195 %rename("docid_order=") set_docid_order;
 196 %rename("document=") set_document;
 197 %rename("query=") set_query(const Xapian::Query &);
 198 %rename("query!") set_query(const Xapian::Query &, Xapian::termcount qlen);
 199 %rename("sort_by_relevance!") set_sort_by_relevance;
 200 %rename("sort_by_relevance_then_value!") set_sort_by_relevance_then_value;
 201 %rename("sort_by_value_then_relevance!") set_sort_by_value_then_relevance;
 202 %rename("sort_by_value!") set_sort_by_value;
 203 %rename("stemmer=") set_stemmer;
 204 %rename("stemming_strategy=") set_stemming_strategy;
 205 %rename("stopper=") set_stopper;
 206 %rename("weighting_scheme=") set_weighting_scheme;
 207
 208 // Booleans
 209 %predicate empty;
 210
 211 #define XAPIAN_MIXED_SUBQUERIES_BY_ITERATOR_TYPEMAP
 212
 213 /* FIXME:
 214  * Check to see what is equivalent to a C++ Vector for the purposes of a Query
 215  * instantiation.
 216  * At the moment, we take Ruby Arrays.
 217  */
 218 %typemap(typecheck, precedence=500) (XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend) {
 219     $1 = (TYPE($input) == T_ARRAY);
 220     /* Currently, the only wrapped method which takes a Ruby array is the
 221      * "extra" constructor Query(OP, ARRAY), where ARRAY can contain any mix of
 222      * strings and Query objects.
 223      *
 224      * If we ever had a method (or function) which had two overloaded forms
 225      * only differentiated by what type of array can be passed we'd need to
 226      * look at the type of the array elements in the typecheck typemaps.
 227      */
 228 }
 229
 230 %{
 231 class XapianSWIGQueryItor {
 232     VALUE array;
 233
 234     int i;
 235
 236   public:
 237     typedef std::random_access_iterator_tag iterator_category;
 238     typedef Xapian::Query value_type;
 239     typedef Xapian::termcount_diff difference_type;
 240     typedef Xapian::Query * pointer;
 241     typedef Xapian::Query & reference;
 242
 243     XapianSWIGQueryItor() { }
 244
 245     void begin(VALUE array_) {
 246         array = array_;
 247         i = 0;
 248     }
 249
 250     void end(int n) {
 251         i = n;
 252     }
 253
 254     XapianSWIGQueryItor & operator++() {
 255         ++i;
 256         return *this;
 257     }
 258
 259     Xapian::Query operator*() const {
 260         VALUE entry = rb_ary_entry(array, i);
 261         if (TYPE(entry) == T_STRING) {
 262             return Xapian::Query(string(RSTRING_PTR(entry),
 263                                         RSTRING_LEN(entry)));
 264         }
 265
 266         // array element may be a Xapian::Query object. Add it if it is,
 267         // otherwise error out.
 268         Xapian::Query *subq = 0;
 269         if (SWIG_ConvertPtr(entry, (void **)&subq,
 270                             SWIGTYPE_p_Xapian__Query, 0) < 0 || !subq) {
 271             SWIG_exception(SWIG_ValueError, "Elements of Arrays passed to Query must be either Strings or other Query objects");
 272             return Xapian::Query();
 273         }
 274         return *subq;
 275     }
 276
 277     bool operator==(const XapianSWIGQueryItor & o) {
 278         return i == o.i;
 279     }
 280
 281     bool operator!=(const XapianSWIGQueryItor & o) {
 282         return !(*this == o);
 283     }
 284
 285     difference_type operator-(const XapianSWIGQueryItor &o) const {
 286         return i - o.i;
 287     }
 288 };
 289
 290 %}
 291
 292 %typemap(in) (XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend) {
 293     if (TYPE($input) == T_ARRAY) {
 294         // The typecheck typemap should have ensured this is an array.
 295         $1.begin($input);
 296         $2.end(RARRAY_LEN($input));
 297     } else {
 298         $1.end(0);
 299         $2.end(0);
 300     }
 301 }
 302
 303 %typemap(directorin) (size_t num_tags, const std::string tags[]) {
 304     $input = rb_ary_new();
 305     for (size_t i = 0; i != num_tags; ++i) {
 306         VALUE str = rb_str_new(tags[i].data(), tags[i].size());
 307         rb_ary_push($input, str);
 308     }
 309 }
 310
 311 // For MatchDecider::operator() and ExpandDecider::operator().
 312 %typemap(directorout) int = bool;
 313
 314 %include ../generic/except.i
 315
 316 %include ../xapian-headers.i
 317
 318 %include extra.i