tclxapian 1.2.19-2 / usr / share / doc / tclxapian / index.html

This file is indexed.

/usr/share/doc/tclxapian/index.html is in tclxapian 1.2.19-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
<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 currently convert this to/from
<code>\x00</code> so you should avoid passing strings containing ASCII nul
between Tcl and Xapian.
</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::Brass::open</code>,
   <code>Xapian::Chert::open</code>, and <code>Xapian::Flint::open</code>.
   You can just use a <code>Xapian::WritableDatabase</code> constructor
   instead (and set <code>XAPIAN_PREFER_BRASS</code> in the environment to
   select brass rather than chert).  You can't create a flint database this
   way, but flint is now deprecated.
</p>

<p>
  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:

<blockquote><pre>
xapian::WritableDatabase xapiandb testdir $::xapian::DB_CREATE_OR_OVERWRITE
xapian_db close
</pre></blockquote>

  If you want compatibility with Xapian 1.0.x, then
  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 work:

<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::Brass::open()</code> is wrapped as <code>xapian::brass_open</code> (but note that the WritableDatabase version isn't wrapped - see
<li> <code>Xapian::Chert::open()</code> is wrapped as <code>xapian::chert_open</code> (but note that the WritableDatabase version isn't wrapped - see
the 'Destructors' section above for an explanation).
<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::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>

<h3>MatchAll and MatchNothing</h3>

<p>
As of Xapian 1.1.1, these are wrapped for Tcl as
<code>$xapian::Query_MatchAll</code> and
<code>$xapian::Query_MatchNothing</code>.
</p>

<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: 2011-05-30 08:06:45 +0100 (Mon, 30 May 2011) $
</address>
</body>
</html>

APT Browse - Built by Thomas Orozco.