xapian-bindings/tcl8/docs/index.rst

   1 Tcl8 bindings for Xapian
   2 ************************
   3
   4 The Tcl8 bindings for Xapian are packaged in the ``xapian`` namespace,
   5 and largely follow the C++ API, with the following differences and
   6 additions. Tcl8 strings and lists, etc., are converted automatically
   7 in the bindings, so generally it should just work as expected.
   8
   9 The ``examples`` subdirectory contains examples showing how to use the
  10 Tcl8 bindings based on the simple examples from ``xapian-examples``:
  11 `simpleindex.tcl <examples/simpleindex.tcl>`_,
  12 `simplesearch.tcl <examples/simplesearch.tcl>`_,
  13 `simpleexpand.tcl <examples/simpleexpand.tcl>`_.
  14
  15 Unicode Support
  16 ###############
  17
  18 In Xapian 1.0.0 and later, the Xapian::Stem, Xapian::QueryParser, and
  19 Xapian::TermGenerator classes all assume text is in UTF-8.  Tcl8 uses
  20 UTF-8 as its internal representation, except that ASCII nul (character value
  21 0) is represented as the overlong (and thus invalid) UTF-8 sequence
  22 ``\xc0\x80``.  We don't currently convert this to/from
  23 ``\x00`` so you should avoid passing strings containing ASCII nul
  24 between Tcl and Xapian.
  25
  26
  27 Destructors
  28 ###########
  29
  30 To destroy an object ``obj``, you need to use one of
  31 ``obj -delete`` or ``rename obj ""``
  32 (either should work, but see below).
  33
  34 SWIG's Tcl wrapping doesn't handle an object returned by a factory function
  35 correctly.  This only matters for the ``xapian::WritableDatabase`` class, and
  36 the only such factory function is ``xapian::remote_open_writable``.
  37
  38 As of Xapian 1.1.0, you can explicitly close the database, so the lack
  39 of a call to the destructor isn't an issue:
  40
  41 ::
  42
  43   xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE
  44   xapian_db close
  45
  46 If you want compatibility with Xapian 1.0.x, then
  47 Michael Schlenker reports that this form works (i.e. the destructor gets
  48 called):
  49
  50 ::
  51
  52   xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE
  53   rename xapiandb ""
  54
  55 However, apparently none of these forms work:
  56
  57 ::
  58
  59   xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE
  60   set db xapiandb
  61   $db -delete
  62
  63   set db [xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE]
  64   $db -delete
  65
  66   set db [xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE]
  67   rename $db ""
  68
  69
  70 Exceptions
  71 ##########
  72
  73 Xapian::Error exceptions can be handled in Tcl like so:
  74
  75 ::
  76
  77   if [catch {
  78       # Code which might throw an exception.
  79     } msg] {
  80       # Code to handle exceptions.
  81       # $errorCode is "XAPIAN <error_class>" (e.g. "XAPIAN DocNotFoundError".)
  82       # $msg is the result of calling get_msg() on the Xapian::Error object.
  83   }
  84
  85
  86 Iterators
  87 #########
  88
  89 All iterators support ``next`` and ``equals`` methods
  90 to move through and test iterators (as for all language bindings).
  91 MSetIterator and ESetIterator also support ``prev``.
  92
  93 Iterator dereferencing
  94 ######################
  95
  96 C++ iterators are often dereferenced to get information, eg
  97 ``(*it)``. With Tcl8 these are all mapped to named methods, as
  98 follows:
  99
 100 .. table:: Iterator deferencing methods
 101
 102   +------------------+----------------------+
 103   | Iterator         | Dereferencing method |
 104   +==================+======================+
 105   | PositionIterator |    ``get_termpos``   |
 106   +------------------+----------------------+
 107   | PostingIterator  |  ``get_docid``       |
 108   +------------------+----------------------+
 109   | TermIterator     |     ``get_term``     |
 110   +------------------+----------------------+
 111   | ValueIterator    |     ``get_value``    |
 112   +------------------+----------------------+
 113   | MSetIterator     |     ``get_docid``    |
 114   +------------------+----------------------+
 115   | ESetIterator     |     ``get_term``     |
 116   +------------------+----------------------+
 117
 118 Other methods, such as ``MSetIterator::get_document``, are
 119 available under the same names.
 120
 121
 122 MSet
 123 ####
 124
 125 MSet objects have some additional methods to simplify access (these
 126 work using the C++ array dereferencing):
 127
 128 .. table:: MSet additional methods
 129
 130   +---------------------------------------+--------------------------------------------------+
 131   | Method name                           |            Explanation                           |
 132   +=======================================+==================================================+
 133   | ``mset get_hit index``                |   returns MSetIterator at index                  |
 134   +---------------------------------------+--------------------------------------------------+
 135   | ``mset get_document_percentage index``| ``mset convert_to_percent [mset get_hit index]`` |
 136   +---------------------------------------+--------------------------------------------------+
 137   | ``mset get_document index``           | ``[mset get_hit index] get_document``            |
 138   +---------------------------------------+--------------------------------------------------+
 139   | ``mset get_docid index``              | ``[mset get_hit index] get_docid``               |
 140   +---------------------------------------+--------------------------------------------------+
 141
 142
 143 Non-Class Functions
 144 ###################
 145
 146 The C++ API contains a few non-class functions (the Database factory
 147 functions, and some functions reporting version information), which are
 148 wrapped like so for Tcl:
 149
 150 - ``Xapian::version_string()`` is wrapped as ``xapian::version_string``
 151 - ``Xapian::major_version()`` is wrapped as ``xapian::major_version``
 152 - ``Xapian::minor_version()`` is wrapped as ``xapian::minor_version``
 153 - ``Xapian::revision()`` is wrapped as ``xapian::revision``
 154 - ``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).
 155 - ``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).
 156
 157
 158 Constants
 159 #########
 160
 161 For Tcl, constants are wrapped as ``$xapian::CONSTANT_NAME``
 162 or ``$xapian::ClassName_CONSTANT_NAME``.
 163 So ``Xapian::DB_CREATE_OR_OPEN`` is available as
 164 ``$xapian::DB_CREATE_OR_OPEN``, ``Xapian::Query::OP_OR`` is
 165 available as ``$xapian::Query_OP_OR``, and so on.
 166
 167 Query
 168 #####
 169
 170 In C++ there's a Xapian::Query constructor which takes a query operator and
 171 start/end iterators specifying a number of terms or queries, plus an optional
 172 parameter.  In Tcl, this is wrapped to accept a Tcl list
 173 to give the terms/queries, and you can specify
 174 a mixture of terms and queries if you wish.  For example:
 175
 176
 177 ::
 178
 179   set terms [list "hello" "world"]
 180   xapian::Query subq $xapian::Query_OP_AND $terms
 181   xapian::Query bar_term "bar" 2
 182   xapian::Query query $xapian::Query_OP_AND [list subq "foo" bar_term]
 183
 184
 185 MatchAll and MatchNothing
 186 -------------------------
 187
 188 As of Xapian 1.1.1, these are wrapped for Tcl as
 189 ``$xapian::Query_MatchAll`` and
 190 ``$xapian::Query_MatchNothing``.
 191
 192 Enquire
 193 #######
 194
 195 There is an additional method ``get_matching_terms`` which takes
 196 an MSetIterator and returns a list of terms in the current query which
 197 match the document given by that iterator.  You may find this
 198 more convenient than using the TermIterator directly.