xapian-bindings/lua/docs/index.rst

   1 Lua bindings for Xapian
   2 ***********************
   3
   4 These bindings require Lua version 5.1 or later, and have been tested with Lua
   5 5.1, 5.2 and 5.3.
   6
   7 The Lua bindings for Xapian are packaged in the ``xapian`` namespace,
   8 and largely follow the C++ API, with the following differences and
   9 additions.
  10
  11 The ``examples`` subdirectory contains examples showing how to use the
  12 Lua bindings based on the simple examples from ``xapian-examples``:
  13 `simpleindex.lua <examples/simpleindex.lua>`_,
  14 `simplesearch.lua <examples/simplesearch.lua>`_,
  15 `simpleexpand.lua <examples/simpleexpand.lua>`_.
  16
  17 There's also
  18 `simplematchdecider.lua <examples/simplematchdecider.lua>`_
  19 which shows how to define a MatchDecider in Lua.
  20
  21 Unicode Support
  22 ###############
  23
  24 In Xapian 1.0.0 and later, the Xapian::Stem, Xapian::QueryParser, and
  25 Xapian::TermGenerator classes all assume text is in UTF-8.  A Lua string
  26 is an arbitrary sequence of values which have at least 8 bits (octets);
  27 they map directly into the char type of the C compiler. Lua does not
  28 reserve any value, including NUL. That means that Lua can store a UTF-8
  29 string without problems.
  30
  31 Method names
  32 ############
  33
  34 Most methods are named the same as in the C++ API - the exceptions are:
  35
  36 ``end`` is a keyword in Lua, so such methods are renamed to
  37 ``_end`` - e.g. in Lua you'd use ``mset:_end()`` to get an
  38 end iterator for an MSet object called mset.
  39 The C++ method ``get_description()`` is mapped to the
  40 ``str`` function in Lua, so ``str(x)`` will return a string
  41 describing object x.
  42
  43 Exceptions
  44 ##########
  45
  46 Exceptions thrown by Xapian are translated into Lua xapian.Error objects
  47 and raised as Lua errors, which you can catch by using ``pcall``
  48 like so:
  49
  50 ::
  51
  52    ok,res = pcall(db.get_document, db, docid)
  53    if ok then
  54       print("Got document data: " .. res:get_data())
  55    else
  56       print("Got exception: " .. tostring(res))
  57    end
  58
  59 Iterators
  60 #########
  61
  62
  63 All iterators support ``next`` and ``equals`` methods
  64 to move through and test iterators (as for all language bindings).
  65 MSetIterator and ESetIterator also support ``prev``. As "end" is
  66 a keyword in Lua, we rename it to "_end" that means the end of the iterator.
  67 The following shows an example of iterating the MSet to get the rank,
  68 document id, and data for each entry in the MSet:
  69
  70 ::
  71
  72    for m in mset:items() do
  73       print(m:get_rank() + 1, m:get_docid(), m:get_document():get_data())
  74    end
  75
  76 Iterator dereferencing
  77 ######################
  78
  79 C++ iterators are often dereferenced to get information, eg
  80 ``(*it)``. With Lua these are all mapped to named methods, as
  81 follows:
  82
  83 +------------------+----------------------+
  84 | Iterator         | Dereferencing method |
  85 +==================+======================+
  86 | PositionIterator |     ``get_termpos``  |
  87 +------------------+----------------------+
  88 | PostingIterator  |     ``get_docid``    |
  89 +------------------+----------------------+
  90 | TermIterator     |     ``get_term``     |
  91 +------------------+----------------------+
  92 | ValueIterator    |     ``get_value``    |
  93 +------------------+----------------------+
  94 | MSetIterator     |     ``get_docid``    |
  95 +------------------+----------------------+
  96 | ESetIterator     |     ``get_term()``   |
  97 +------------------+----------------------+
  98
  99 Other methods, such as ``MSetIterator:get_document``, are
 100 available under the same names.
 101
 102 MSet
 103 ####
 104
 105 MSet objects have some additional methods to simplify access (these
 106 work using the C++ array dereferencing):
 107
 108 +-----------------------------------+----------------------------------------+
 109 | Method name                       |            Explanation                 |
 110 +===================================+========================================+
 111 | ``get_hit(index)``                |  returns MSetItem at index             |
 112 +-----------------------------------+----------------------------------------+
 113 | ``get_documentPercentage(index)`` | ``convert_to_percent(get_hit(index))`` |
 114 +-----------------------------------+----------------------------------------+
 115 | ``get_document(index)``           | ``get_hit(index):get_document()``      |
 116 +-----------------------------------+----------------------------------------+
 117 | ``get_docid(index)``              | ``get_hit(index):get_docid()``         |
 118 +-----------------------------------+----------------------------------------+
 119
 120 The C++ API contains a few non-class functions (the Database factory
 121 functions, and some functions reporting version information), which are
 122 wrapped like so for Lua:
 123
 124
 125 -  ``Xapian::version_string()`` is wrapped as ``xapian.version_string()``
 126 -  ``Xapian::major_version()`` is wrapped as ``xapian.major_version()``
 127 -  ``Xapian::minor_version()`` is wrapped as ``xapian.minor_version()``
 128 -  ``Xapian::revision()`` is wrapped as ``xapian.revision()``
 129 -  ``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).
 130 -  ``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).
 131
 132
 133 Constants
 134 #########
 135
 136 For Lua, constants are wrapped as ``xapian.CONSTANT_NAME``
 137 or ``xapian.ClassName_CONSTANT_NAME``.
 138 So ``Xapian::DB_CREATE_OR_OPEN`` is available as
 139 ``xapian.DB_CREATE_OR_OPEN``, ``Xapian::Query::OP_OR`` is
 140 available as ``xapian.Query_OP_OR``, and so on.
 141
 142 As of 1.3.2, you can also use the form ``xapian.ClassName.CONSTANT_NAME``, e.g.
 143 ``xapian.Query.OP_OR``.
 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 Lua, it is wrapped to accept Lua tables to give the terms/queries,
 151 and you can specify a mixture of terms and queries if you wish.  For example:
 152
 153 ::
 154
 155    subq = xapian.Query(xapian.Query_OP_AND, {"hello", "world"})
 156    q = xapian.Query(xapian.Query_OP_AND, {subq, "foo", xapian.Query("bar", 2)})
 157
 158 MatchAll and MatchNothing
 159 #########################
 160
 161 These are wrapped for Lua as ``xapian.Query_MatchAll`` and
 162 ``xapian.Query_MatchNothing``.
 163
 164 As of 1.3.2, you can also use the forms ``xapian.Query.MatchAll`` and
 165 ``xapian.Query.MatchNothing``.
 166
 167 Enquire
 168 #######
 169
 170 There is an additional method ``get_matching_terms`` which takes
 171 an MSetIterator and returns a list of terms in the current query which
 172 match the document given by that iterator.  You may find this
 173 more convenient than using the TermIterator directly.
 174
 175 MatchDecider
 176 ############
 177
 178 Custom MatchDeciders can be created in Lua in the form of lua function; simply
 179 function ensures you create a subclass of xapian.MatchDecider, which calls
 180 the super-constructor, and overloads the operator method to callback the lua function
 181 that will do the work. The simplest example (which does nothing
 182 useful) would be as follows:
 183
 184 ::
 185
 186    function mymatchdecider(doc)
 187       return 1
 188    end