mhs-xapian 1.0.18a

data/tcl8/docs/examples/simpleindex.tcl

@@ -0,0 +1,68 @@
+#!/usr/bin/env tclsh
+# Tcl script to index each paragraph of a text file as a Xapian document.
+#
+# Copyright (C) 2004,2006,2007 Olly Betts
+# Copyright (C) 2004 Michael Schlenker
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+
+# We need at least Tcl version 8.1.
+package require Tcl 8.1
+
+# We need at least Xapian 1.0.0 for TermGenerator.
+package require xapian 1.0.0
+
+if {[llength $argv] != 1} {
+    puts "Usage: $argv0 PATH_TO_DATABASE"
+    exit 1
+}
+
+if {[catch {
+    set dbpath [lindex $argv 0]
+    xapian::WritableDatabase database $dbpath $xapian::DB_CREATE_OR_OPEN
+    xapian::TermGenerator indexer
+    xapian::Stem stemmer "english"
+    indexer set_stemmer stemmer
+
+    set para ""
+    while {![eof stdin]} {
+	gets stdin line
+	set line [string trim $line]
+	if {[string equal $line ""] && [string compare $para ""]} {
+	    # We've reached the end of a paragraph, so index it.
+	    xapian::Document doc
+	    doc set_data $para
+
+	    indexer set_document doc
+	    indexer index_text $para
+
+	    # Add the document to the database.
+	    database add_document doc
+	    set para ""
+	} else {
+	    if {[string equal $para ""]} {
+		set para $line
+	    } else {
+		set para "$para $line"
+	    }
+	}
+    }
+    # We *must* delete the database so that the destructor gets called so
+    # pending changes are flushed and the lock file is removed.
+    database -delete
+} exception]} {
+    puts stderr "Exception: $errorCode $exception"
+    exit 1
+}

data/tcl8/docs/examples/simplesearch.tcl

@@ -0,0 +1,66 @@
+#!/usr/bin/env tclsh
+# Simple command-line search Tcl script.
+#
+# Copyright (C) 2004,2006,2007 Olly Betts
+# Copyright (C) 2004 Michael Schlenker
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+
+# We need at least Tcl version 8.1.
+package require Tcl 8.1
+# We need only actually need Xapian 0.9.3 (for the query from list constructor
+# wrapper), but "package require" doesn't accept differing major versions.
+package require xapian 1.0.0
+
+if {[llength $argv] < 2} {
+    puts "Usage: $argv0 PATH_TO_DATABASE QUERY"
+    exit 1
+}
+
+if {[catch {
+    xapian::Database database [lindex $argv 0]
+
+    # Start an enquire session.
+    xapian::Enquire enquire database
+
+    # Combine the rest of the command line arguments with spaces between
+    # them, so that simple queries don't have to be quoted at the shell
+    # level.
+    set query_string [join [lrange $argv 1 end]]
+    xapian::QueryParser qp
+    xapian::Stem stemmer "english"
+    qp set_stemmer stemmer
+    qp set_database database
+    qp set_stemming_strategy $xapian::QueryParser_STEM_SOME
+    set query [qp parse_query $query_string]
+    puts "Parsed query is: [$query get_description]"
+
+    # Find the top 10 results for the query.
+    enquire set_query $query
+    set matches [enquire get_mset 0 10]
+
+    # Display the results.
+    puts "[$matches get_matches_estimated] results found:"
+
+    for {set i [$matches begin]} {![$i equals [$matches end]]} {$i next} {
+	xapian::Document document [$i get_document]
+	set rank [expr [$i get_rank] + 1]
+	puts [format {%s: %s%% docid=%s [%s]} \
+	    $rank [$i get_percent] [$i get_docid] [document get_data]]
+    }
+} exception]} {
+    puts stderr "Exception: $errorCode $exception"
+    exit 1
+}

data/tcl8/docs/index.html

@@ -0,0 +1,208 @@
+<html><head><title>Tcl8 bindings for Xapian</title></head>
+<body>
+<h1>Tcl8 bindings for Xapian</h1>
+
+<p>
+The Tcl8 bindings for Xapian are packaged in the <code>xapian</code> 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.
+</p>
+
+<p>
+The <code>examples</code> subdirectory contains examples showing how to use the
+Tcl8 bindings based on the simple examples from <code>xapian-examples</code>:
+<a href="examples/simpleindex.tcl">simpleindex.tcl</a>,
+<a href="examples/simplesearch.tcl">simplesearch.tcl</a>,
+<a href="examples/simpleexpand.tcl">simpleexpand.tcl</a>.
+</p>
+
+<h2>Unicode Support</h2>
+
+<p>
+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
+<code>\xc0\x80</code>.  We don't current convert this to/from
+<code>\x00</code> so you should avoid passing strings containing ASCII nul
+to/from Xapian from Tcl8.
+</p>
+
+<h2>Destructors</h2>
+
+<p>
+   To destroy an object <code><i>obj</i></code>, you need to use one of
+   <code><i>obj</i> -delete</code> or <code>rename <i>obj</i> ""</code>
+   (either should work, but see below).
+</p>
+
+<p>
+   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
+   <code>Xapian::Flint::open</code>, <code>Xapian::Quartz::open</code> and
+   <code>Xapian::Auto::open</code>.  The latter is deprecated anyway, and
+   you can just use a <code>Xapian::WritableDatabase</code> constructor
+   instead.  Use of quartz is also deprecated, and the
+   <code>Xapian::WritableDatabase</code> constructor creates flint databases
+   in 1.0 releases anyway.
+</p>
+
+<p>
+  Michael Schlenker reports that this form works (i.e. the destructor gets
+  called):
+
+<blockquote><pre>
+xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE
+rename xapiandb ""
+</pre></blockquote>
+
+  However, apparently none of these forms works:
+
+<blockquote><pre>
+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 ""
+</pre></blockquote>
+</p>
+
+<h2>Exceptions</h2>
+
+<p>
+Xapian::Error exceptions can be handled in Tcl like so:
+</p>
+
+<pre>
+if [catch {
+    # Code which might throw an exception.
+} msg] {
+    # Code to handle exceptions.
+    # $errorCode is "XAPIAN <error_class>" (e.g. "XAPIAN DocNotFoundError".)
+    # $msg is the result of calling get_msg() on the Xapian::Error object.
+}
+</pre>
+
+<h2>Iterators</h2>
+
+<p>
+   All iterators support <code>next</code> and <code>equals</code> methods
+   to move through and test iterators (as for all language bindings).
+   MSetIterator and ESetIterator also support <code>prev</code>.
+</p>
+
+<h2>Iterator dereferencing</h2>
+
+<p>
+   C++ iterators are often dereferenced to get information, eg
+   <code>(*it)</code>. With Tcl8 these are all mapped to named methods, as
+   follows:
+</p>
+
+<table title='Iterator deferencing methods'>
+<thead><td>Iterator</td><td>Dereferencing method</td></thead>
+<tr><td>PositionIterator</td>	<td><code>get_termpos</code></td></tr>
+<tr><td>PostingIterator</td>	<td><code>get_docid</code></td></tr>
+<tr><td>TermIterator</td>	<td><code>get_term</code></td></tr>
+<tr><td>ValueIterator</td>	<td><code>get_value</code></td></tr>
+<tr><td>MSetIterator</td>	<td><code>get_docid</code></td></tr>
+<tr><td>ESetIterator</td>	<td><code>get_term</code></td></tr>
+</table>
+
+<p>
+   Other methods, such as <code>MSetIterator::get_document</code>, are
+   available under the same names.
+</p>
+   
+<h2>MSet</h2>
+
+<p>
+   MSet objects have some additional methods to simplify access (these
+   work using the C++ array dereferencing):
+</p>
+
+<table title='MSet additional methods'>
+<thead><td>Method name</td><td>Explanation</td></thead>
+<tr><td><code>mset get_hit index</code></td><td>returns MSetIterator at index</td></tr>
+<tr><td><code>mset get_document_percentage index</code></td><td><code>mset convert_to_percent [mset get_hit index]</code></td></tr>
+<tr><td><code>mset get_document index</code></td><td><code>[mset get_hit index] get_document</code></td></tr>
+<tr><td><code>mset get_docid index</code></td><td><code>[mset get_hit index] get_docid</code></td></tr>
+</table>
+
+<h2>Non-Class Functions</h2>
+
+<p>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:
+<ul>
+<ul>
+<li> <code>Xapian::version_string()</code> is wrapped as <code>xapian::version_string</code>
+<li> <code>Xapian::major_version()</code> is wrapped as <code>xapian::major_version</code>
+<li> <code>Xapian::minor_version()</code> is wrapped as <code>xapian::minor_version</code>
+<li> <code>Xapian::revision()</code> is wrapped as <code>xapian::revision</code>
+</ul>
+
+<ul>
+<li> <code>Xapian::Auto::open_stub()</code> is wrapped as <code>xapian::open_stub</code>
+<li> <code>Xapian::Flint::open()</code> is wrapped as <code>xapian::flint_open</code> (but note that the WritableDatabase version isn't wrapped - see
+the 'Destructors' section above for an explanation).
+<li> <code>Xapian::Quartz::open()</code> is wrapped as <code>xapian::quartz_open</code> (but note that the WritableDatabase version isn't wrapped - see
+the 'Destructors' section above for an explanation).
+<li> <code>Xapian::InMemory::open()</code> is wrapped as <code>xapian::inmemory_open</code>
+<li> <code>Xapian::Remote::open()</code> is wrapped as <code>xapian::remote_open</code> (both
+the TCP and "program" versions are wrapped - the SWIG wrapper checks the parameter list to
+decide which to call).
+<li> <code>Xapian::Remote::open_writable()</code> is wrapped as <code>xapian::remote_open_writable</code> (both
+the TCP and "program" versions are wrapped - the SWIG wrapper checks the parameter list to
+decide which to call).
+</ul>
+</ul>
+
+<h2>Constants</h2>
+
+<p>
+   For Tcl, constants are wrapped as <code>$xapian::<i>CONSTANT_NAME</i></code>
+   or <code>$xapian::<i>ClassName<i>_<i>CONSTANT_NAME</i></code>.
+   So <code>Xapian::DB_CREATE_OR_OPEN</code> is available as
+   <code>$xapian::DB_CREATE_OR_OPEN</code>, <code>Xapian::Query::OP_OR</code> is
+   available as <code>$xapian::Query_OP_OR</code>, and so on.
+</p>
+
+<h2>Query</h2>
+
+<p>
+   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:
+</p>
+
+<pre>
+   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]
+</pre>
+
+<h2>Enquire</h2>
+
+<p>
+   There is an additional method <code>get_matching_terms</code> 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.
+</p>
+
+<address>
+Last updated $Date: 2008-06-26 23:02:05 +0100 (Thu, 26 Jun 2008) $
+</address>
+</body>
+</html>

data/tcl8/except.i

@@ -0,0 +1,48 @@
+%{
+/* tcl8/except.i: Custom tcl8 exception handling.
+ *
+ * Copyright (c) 2006,2007 Olly Betts
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
+ * USA
+ */
+
+static int XapianTclHandleError(Tcl_Interp * interp, const Xapian::Error &e) {
+    Tcl_ResetResult(interp);
+    Tcl_SetErrorCode(interp, "XAPIAN", e.get_type(), NULL);
+    Tcl_AppendResult(interp, e.get_msg().c_str(), NULL);
+    return TCL_ERROR;
+}
+
+static int XapianTclHandleError(Tcl_Interp * interp) {
+    Tcl_ResetResult(interp);
+    Tcl_SetErrorCode(interp, "XAPIAN ?", NULL);
+    Tcl_AppendResult(interp, "Unknown Error", NULL);
+    return TCL_ERROR;
+}
+
+%}
+
+%exception {
+    try {
+	$function
+    } catch (const Xapian::Error &e) {
+	return XapianTclHandleError(interp, e);
+    } catch (...) {
+	return XapianTclHandleError(interp);
+    }
+}
+
+/* vim:set syntax=cpp:set noexpandtab: */

data/tcl8/pkgIndex.tcl

@@ -0,0 +1 @@
+package ifneeded xapian 1.0.18 [list load [file join $dir xapian[info sharedlibextension]]]

data/tcl8/pkgIndex.tcl.in

@@ -0,0 +1 @@
+package ifneeded xapian @VERSION_NO_SNAPSHOT@ [list load [file join $dir xapian[info sharedlibextension]]]

data/tcl8/run-tcl-test

@@ -0,0 +1,15 @@
+#!/bin/sh
+${LIBTOOL-../libtool} --config > libtoolconfig.$$
+. ./libtoolconfig.$$
+rm -f libtoolconfig.$$
+module=yes
+eval shlibext=$shrext_cmds
+
+tclshlibext=`echo 'puts [info sharedlibextension]'|${TCLSH-tclsh}`
+
+rm -f xapian$tclshlibext
+ln -s $objdir/xapian$shlibext xapian$tclshlibext
+${TCLSH-tclsh} ${srcdir-.}/runtest.tcl ${srcdir-.}/smoketest.tcl
+rc=$?
+rm -f xapian$tclshlibext
+exit $rc

data/tcl8/runtest.tcl

@@ -0,0 +1,29 @@
+# Allow a tcl script to be run against an uninstalled libtool-built tcl module
+#
+# Copyright (C) 2006,2007 Olly Betts
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
+# USA
+
+# Syntax: runtest.tcl SCRIPT.TCL [ARGS]
+
+# We need at least Tcl version 8
+package require Tcl 8
+
+lappend auto_path "."
+
+set argv0 [lindex $argv 0]
+set argv [lrange $argv 1 end]
+exit [expr [source $argv0] +0]