xapian-bindings/ruby/docs/index.rst

   1 Ruby bindings for Xapian
   2 ************************
   3
   4 The Ruby bindings for Xapian are packaged in the ``xapian`` module.
   5 Ruby strings and arrays are converted automatically in the bindings, so
   6 generally they should just work naturally.
   7
   8 The ``examples`` subdirectory contains examples showing how to use the
   9 Ruby bindings based on the simple examples from ``xapian-examples``:
  10 `simpleindex.rb <examples/simpleindex.rb>`_,
  11 `simplesearch.rb <examples/simplesearch.rb>`_,
  12 `simpleexpand.rb <examples/simpleexpand.rb>`_.
  13 There's also
  14 `simplematchdecider.rb <examples/simplematchdecider.rb>`_
  15 which shows how to define a MatchDecider in Ruby.
  16
  17
  18 Usage
  19 #####
  20
  21 To use the bindings, you need to use ``require 'xapian'``
  22 in your ruby program.
  23
  24 Most standard Xapian methods are available directly
  25 to your Ruby program. Names have been altered to conform to the
  26 standard Ruby naming conventions (i.e. get_foo() in C++ becomes foo()
  27 in Ruby; set_foo() becomes foo=().)  C++ 'operator()' methods are
  28 renamed to 'call' methods in Ruby.
  29
  30 The C++ methods are not yet documented in the `RDocs <rdocs/>`_.
  31 In the meantime, refer to the
  32 `C++ API documentation <https://xapian.org/docs/apidoc/html/annotated.html>`_
  33 for information on how to use the various methods. Most are
  34 available directly in the Ruby version. The RDocs currently provide information
  35 only on methods that are unique to the Ruby version.
  36
  37 The dangerous/non-Rubish methods from the C++ API have been renamed to
  38 start with underscores ('_') in the Ruby bindings. You can see them in
  39 use in xapian.rb. It is strongly recommended that you do not call any
  40 method that starts with _ directly in your code, but instead use the
  41 wrappers defined in xapian.rb. Improper use of an _ method can cause
  42 the Ruby process to segfault.
  43
  44 Unicode Support
  45 ###############
  46
  47 In Xapian 1.0.0 and later, the Xapian::Stem, Xapian::QueryParser, and
  48 Xapian::TermGenerator classes all assume text is in UTF-8.  If you want
  49 to index strings in a different encoding, use the Ruby
  50 `Iconv Class <http://www.ruby-doc.org/stdlib/libdoc/iconv/rdoc/index.html>`_
  51 to convert them to UTF-8 before passing them to Xapian, and
  52 when reading values back from Xapian.
  53
  54 .. Exceptions
  55 .. ##########
  56 .. Exceptions are thrown as SWIG exceptions instead of Xapian
  57 .. exceptions. This isn't done well at the moment; in future we will
  58 .. throw wrapped Xapian exceptions. For now, it's probably easier to
  59 .. catch all exceptions and try to take appropriate action based on
  60 .. their associated string.
  61
  62 Iterators
  63 #########
  64
  65 One important difference from the C++ API is that \*Iterator
  66 classes should not be used from Ruby, as they fit awkwardly into
  67 standard Ruby iteration paradigms, and as many of them cause segfaults
  68 if used improperly. They have all been wrapped with appropriate
  69 methods that simply return the \*Iterator objects in an Array, so that
  70 you can use 'each' to iterate through them.
  71
  72 ::
  73
  74   mset.matches.each {|match|
  75     # do something
  76   }
  77
  78
  79 .. Iterator dereferencing
  80 .. ######################
  81 .. C++ iterators are often dereferenced to get information, eg
  82 .. ``(*it)``. With Python these are all mapped to named methods, as
  83 .. follows:
  84
  85 .. .. table:: Iterator deferencing methods
  86
  87 .. +------------------+----------------------+
  88 .. | Iterator         | Dereferencing method |
  89 .. +==================+======================+
  90 .. | PositionIterator |    ``get_termpos()`` |
  91 .. +------------------+----------------------+
  92 .. | PostingIterator  |  ``get_docid()``     |
  93 .. +------------------+----------------------+
  94 .. | TermIterator     |     ``get_term()``   |
  95 .. +------------------+----------------------+
  96 .. | ValueIterator    |     ``get_value()``  |
  97 .. +------------------+----------------------+
  98 .. | MSetIterator     |     ``get_docid()``  |
  99 .. +------------------+----------------------+
 100 .. | ESetIterator     |     ``get_term()``   |
 101 .. +------------------+----------------------+
 102
 103 .. Other methods, such as ``MSetIterator.get_document()``, are
 104 .. available unchanged.
 105
 106 .. MSet
 107 .. ####
 108
 109 .. MSet objects have some additional methods to simplify access (these
 110 .. work using the C++ array dereferencing):
 111
 112 .. ..table:: MSet additional methods
 113
 114 .. +-----------------------------------+----------------------------------------+
 115 .. | Method name                       |            Explanation                 |
 116 .. +===================================+========================================+
 117 .. | ``get_hit(index)``                |   returns MSetIterator at index        |
 118 .. +-----------------------------------+----------------------------------------+
 119 .. | ``get_document_percentage(index)``| ``convert_to_percent(get_hit(index))`` |
 120 .. +-----------------------------------+----------------------------------------+
 121 .. | ``get_document(index)``           | ``get_hit(index).get_document()``      |
 122 .. +-----------------------------------+----------------------------------------+
 123 .. | ``get_docid(index)``              | ``get_hit(index).get_docid()``         |
 124 .. +-----------------------------------+----------------------------------------+
 125
 126
 127 Non-Class Functions
 128 ###################
 129
 130 The C++ API contains a few non-class functions (the Database factory
 131 functions, and some functions reporting version information), which are
 132 wrapped like so for Ruby:
 133
 134 - ``Xapian::version_string()`` is wrapped as ``Xapian::version_string()``
 135 - ``Xapian::major_version()`` is wrapped as ``Xapian::major_version()``
 136 - ``Xapian::minor_version()`` is wrapped as ``Xapian::minor_version()``
 137 - ``Xapian::revision()`` is wrapped as ``Xapian::revision()``
 138 - ``Xapian::Auto::open_stub()`` is wrapped as ``Xapian::open_stub()``
 139 - ``Xapian::Chert::open()`` is wrapped as ``Xapian::chert_open()`` (now deprecated)
 140 - ``Xapian::InMemory::open()`` is wrapped as ``Xapian::inmemory_open()`` (now deprecated)
 141 - ``Xapian::Remote::open()`` is wrapped as ``Xapian::remote_open()`` (both the TCP and "program" versions are wrapped - the SWIG wrapper checks the parameter list to decide which to call).
 142 - ``Xapian::Remote::open_writable()`` is wrapped as ``Xapian::remote_open_writable()`` (both the TCP and "program" versions are wrapped - the SWIG wrapper checks the parameter list to decide which to call).
 143
 144
 145 Query
 146 #####
 147
 148 In C++ there's a Xapian::Query constructor which takes a query operator and
 149 start/end iterators specifying a number of terms or queries, plus an optional
 150 parameter.  In Ruby, this is wrapped to accept a Ruby array containing
 151 terms, or queries, or even a mixture of terms and queries.  For example:
 152
 153 ::
 154
 155   subq = Xapian::Query.new(Xapian::Query::OP_AND, "hello", "world")
 156   q = Xapian::Query.new(Xapian::Query::OP_AND, [subq, "foo", Xapian::Query.new("bar", 2)])
 157
 158
 159 MatchAll and MatchNothing
 160 -------------------------
 161
 162 In Xapian 1.3.0 and later, these are wrapped as class constants
 163 ``Xapian::Query::MatchAll`` and ``Xapian::Query::MatchNothing``.
 164
 165 If you want to be compatible with earlier versions, you can continue to use
 166 ``Xapian::Query.new("")`` for MatchAll and
 167 ``Xapian::Query.new()`` for MatchNothing.
 168
 169
 170 MatchDecider
 171 ############
 172
 173 Custom MatchDeciders can be created in Ruby; simply subclass
 174 Xapian::MatchDecider, ensure you call the superclass constructor, and define a
 175 __call__ method that will do the work. The simplest example (which does nothing
 176 useful) would be as follows:
 177
 178 ::
 179
 180   class MyMatchDecider < Xapian\::MatchDecider
 181     def __call__(doc):
 182       return true
 183     end
 184   end