Tcl8 bindings for Xapian

The Tcl8 bindings for Xapian are packaged in the xapian namespace, and largely follow the C++ API, with the following differences and additions. Tcl8 strings and lists, etc., are converted automatically in the bindings, so generally it should just work as expected.

The examples subdirectory contains examples showing how to use the Tcl8 bindings based on the simple examples from xapian-examples: simpleindex.tcl, simplesearch.tcl.

Destructors

To destroy an object obj, you need to use one of obj -delete or rename obj "" (either should work, but see below).

SWIG's Tcl wrapping doesn't handle an object returned by a factory function correctly. This only matters for the Xapian::WriteableDatabase class, and we avoid wrapping the two problematic factory functions to avoid setting a trap for the unwary - these are the WriteableDatabase version of Xapian::Quartz::open and the WriteableDatabase version of Xapian::Auto::open. The latter is deprecated anyway, and you can just use a Xapian::WriteableDatabase constructor instead. There's no direct replacement for the former, although at present it's actually exactly the same as the latter (since Quartz is the only disk based backend which supports writing).

Michael Schlenker reports that this form works (i.e. the destructor gets called):

xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE
rename xapiandb ""

xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE
set db xapiandb
$db -delete

set db [xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE]
$db -delete

set db [xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE]
rename $db ""

Exceptions

Xapian::Error exceptions can be handled in Tcl like so:

if [catch {
    # Code which might throw an exception.
} msg] {
    # Code to handle exceptions.
    # $errorCode is "XAPIAN " (e.g. "XAPIAN DocNotFoundError".)
    # $msg is the result of calling get_msg() on the Xapian::Error object.
}

Iterators

All iterators support next and equals methods to move through and test iterators (as for all language bindings). MSetIterator and ESetIterator also support prev.

Iterator dereferencing

C++ iterators are often dereferenced to get information, eg (*it). With Tcl8 these are all mapped to named methods, as follows:

Other methods, such as MSetIterator::get_document, are available under the same names.

MSet

MSet objects have some additional methods to simplify access (these work using the C++ array dereferencing):

Database Factory Functions

• Xapian::Auto::open_stub() is wrapped as xapian::open_stub
• Xapian::Quartz::open() is wrapped as xapian::quartz_open (but note that the WriteableDatabase version isn't wrapped - see the 'Destructors' section above for an explanation).
• Xapian::InMemory::open() is wrapped as xapian::inmemory_open
• Xapian::Remote::open() is wrapped as xapian::remote_open (only the TCP version is currently wrapped, the "program" version isn't).

Query

In C++ there's a Xapian::Query constructor which takes a query operator and start/end iterators specifying a number of terms or queries, plus an optional parameter. In Tcl, this is wrapped to accept a Tcl list to give the terms/queries, and you can specify a mixture of terms and queries if you wish. For example:

   set terms [list "hello" "world"]
   xapian::Query subq $xapian::Query_OP_AND $terms
   xapian::Query bar_term "bar" 2
   xapian::Query query $xapian::Query_OP_AND [list subq "foo" bar_term]

Enquire

There is an additional method get_matching_terms which takes an MSetIterator and returns a list of terms in the current query which match the document given by that iterator. You may find this more convenient than using the TermIterator directly.