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,
simpleexpand.tcl.
In Xapian 1.0.0 and later, the Xapian::Stem, Xapian::QueryParser, and
Xapian::TermGenerator classes all assume text is in UTF-8. Tcl8 uses
UTF-8 as its internal representation, except that ASCII nul (character value
0) is represented as the overlong (and thus invalid) UTF-8 sequence
\xc0\x80
. We don't currently convert this to/from
\x00
so you should avoid passing strings containing ASCII nul
between Tcl and Xapian.
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::WritableDatabase class, and we
avoid wrapping the problematic factory functions to avoid setting a
trap for the unwary - these are the WritableDatabase versions of
Xapian::Brass::open
,
Xapian::Chert::open
, and Xapian::Flint::open
.
You can just use a Xapian::WritableDatabase
constructor
instead (and set XAPIAN_PREFER_BRASS
in the environment to
select brass rather than chert). You can't create a flint database this
way, but flint is now deprecated.
As of Xapian 1.1.0, you can explicitly close the database, so the lack of a call to the destructor isn't an issue:
If you want compatibility with Xapian 1.0.x, then Michael Schlenker reports that this form works (i.e. the destructor gets called):xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE xapian_db close
However, apparently none of these forms work: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 ""
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. }
All iterators support next
and equals
methods
to move through and test iterators (as for all language bindings).
MSetIterator and ESetIterator also support prev
.
C++ iterators are often dereferenced to get information, eg
(*it)
. With Tcl8 these are all mapped to named methods, as
follows:
Iterator | Dereferencing method |
PositionIterator | get_termpos |
PostingIterator | get_docid |
TermIterator | get_term |
ValueIterator | get_value |
MSetIterator | get_docid |
ESetIterator | get_term |
Other methods, such as MSetIterator::get_document
, are
available under the same names.
MSet objects have some additional methods to simplify access (these work using the C++ array dereferencing):
Method name | Explanation |
mset get_hit index | returns MSetIterator at index |
mset get_document_percentage index | mset convert_to_percent [mset get_hit index] |
mset get_document index | [mset get_hit index] get_document |
mset get_docid index | [mset get_hit index] get_docid |
The C++ API contains a few non-class functions (the Database factory functions, and some functions reporting version information), which are wrapped like so for Tcl:
Xapian::version_string()
is wrapped as xapian::version_string
Xapian::major_version()
is wrapped as xapian::major_version
Xapian::minor_version()
is wrapped as xapian::minor_version
Xapian::revision()
is wrapped as xapian::revision
Xapian::Auto::open_stub()
is wrapped as xapian::open_stub
Xapian::Brass::open()
is wrapped as xapian::brass_open
(but note that the WritableDatabase version isn't wrapped - see
Xapian::Chert::open()
is wrapped as xapian::chert_open
(but note that the WritableDatabase version isn't wrapped - see
the 'Destructors' section above for an explanation).
Xapian::Flint::open()
is wrapped as xapian::flint_open
(but note that the WritableDatabase 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
(both
the TCP and "program" versions are wrapped - the SWIG wrapper checks the parameter list to
decide which to call).
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).
For Tcl, constants are wrapped as $xapian::CONSTANT_NAME
or $xapian::ClassName_CONSTANT_NAME
.
So Xapian::DB_CREATE_OR_OPEN
is available as
$xapian::DB_CREATE_OR_OPEN
, Xapian::Query::OP_OR
is
available as $xapian::Query_OP_OR
, and so on.
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]
As of Xapian 1.1.1, these are wrapped for Tcl as
$xapian::Query_MatchAll
and
$xapian::Query_MatchNothing
.
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.