File: index.html

package info (click to toggle)
xapian-bindings 1.4.29-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 21,436 kB
sloc: cpp: 379,853; python: 10,780; cs: 9,529; java: 6,949; sh: 4,629; perl: 4,435; makefile: 1,274; ruby: 1,028; php: 586; tcl: 246
file content (560 lines) | stat: -rw-r--r-- 17,858 bytes
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
<title>Lua bindings for Xapian</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 9511 2024-01-13 09:50:07Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.
Despite the name, some widely supported CSS2 features are used.

See https://docutils.sourceforge.io/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

.subscript {
  vertical-align: sub;
  font-size: smaller }

.superscript {
  vertical-align: super;
  font-size: smaller }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title, .code .error {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left, table.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right, table.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

table.align-center {
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

.align-top    {
  vertical-align: top }

.align-middle {
  vertical-align: middle }

.align-bottom {
  vertical-align: bottom }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math, pre.code {
  margin-left: 2em ;
  margin-right: 2em }

pre.code .ln { color: gray; } /* line numbers */
pre.code, code { background-color: #eeeeee }
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic, pre.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

/* "booktabs" style (no vertical lines) */
table.docutils.booktabs {
  border: 0px;
  border-top: 2px solid;
  border-bottom: 2px solid;
  border-collapse: collapse;
}
table.docutils.booktabs * {
  border: 0px;
}
table.docutils.booktabs th {
  border-bottom: thin solid;
  text-align: left;
}

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="lua-bindings-for-xapian">
<h1 class="title">Lua bindings for Xapian</h1>

<p>These bindings require Lua version 5.1 or later, and have been tested with Lua
5.1, 5.2 and 5.3.</p>
<p>The Lua bindings for Xapian are packaged in the <tt class="docutils literal">xapian</tt> namespace,
and largely follow the C++ API, with the following differences and
additions.</p>
<p>The <tt class="docutils literal">examples</tt> subdirectory contains examples showing how to use the
Lua bindings based on the simple examples from <tt class="docutils literal"><span class="pre">xapian-examples</span></tt>:
<a class="reference external" href="examples/simpleindex.lua">simpleindex.lua</a>,
<a class="reference external" href="examples/simplesearch.lua">simplesearch.lua</a>,
<a class="reference external" href="examples/simpleexpand.lua">simpleexpand.lua</a>.</p>
<p>There's also
<a class="reference external" href="examples/simplematchdecider.lua">simplematchdecider.lua</a>
which shows how to define a MatchDecider in Lua.</p>
<div class="section" id="unicode-support">
<h1>Unicode Support</h1>
<p>In Xapian 1.0.0 and later, the Xapian::Stem, Xapian::QueryParser, and
Xapian::TermGenerator classes all assume text is in UTF-8.  A Lua string
is an arbitrary sequence of values which have at least 8 bits (octets);
they map directly into the char type of the C compiler. Lua does not
reserve any value, including NUL. That means that Lua can store a UTF-8
string without problems.</p>
</div>
<div class="section" id="method-names">
<h1>Method names</h1>
<p>Most methods are named the same as in the C++ API - the exceptions are:</p>
<p><tt class="docutils literal">end</tt> is a keyword in Lua, so such methods are renamed to
<tt class="docutils literal">_end</tt> - e.g. in Lua you'd use <tt class="docutils literal">mset:_end()</tt> to get an
end iterator for an MSet object called mset.</p>
<p>The C++ method <tt class="docutils literal">get_description()</tt> is mapped to the
<tt class="docutils literal">tostring</tt> function in Lua, so <tt class="docutils literal">tostring(x)</tt> will return a string
describing object x.</p>
</div>
<div class="section" id="exceptions">
<h1>Exceptions</h1>
<p>Exceptions thrown by Xapian are translated into Lua xapian.Error objects
and raised as Lua errors, which you can catch by using <tt class="docutils literal">pcall</tt>
like so:</p>
<pre class="literal-block">
ok,res = pcall(db.get_document, db, docid)
if ok then
   print(&quot;Got document data: &quot; .. res:get_data())
else
   print(&quot;Got exception: &quot; .. tostring(res))
end
</pre>
</div>
<div class="section" id="iterators">
<h1>Iterators</h1>
<p>All iterators support <tt class="docutils literal">next</tt> and <tt class="docutils literal">equals</tt> methods
to move through and test iterators (as for all language bindings).
MSetIterator and ESetIterator also support <tt class="docutils literal">prev</tt>. As &quot;end&quot; is
a keyword in Lua, we rename it to &quot;_end&quot; that means the end of the iterator.
The following shows an example of iterating the MSet to get the rank,
document id, and data for each entry in the MSet:</p>
<pre class="literal-block">
for m in mset:items() do
   print(m:get_rank() + 1, m:get_docid(), m:get_document():get_data())
end
</pre>
</div>
<div class="section" id="iterator-dereferencing">
<h1>Iterator dereferencing</h1>
<p>C++ iterators are often dereferenced to get information, eg
<tt class="docutils literal">(*it)</tt>. With Lua these are all mapped to named methods, as
follows:</p>
<table border="1" class="docutils">
<colgroup>
<col width="45%" />
<col width="55%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Iterator</th>
<th class="head">Dereferencing method</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>PositionIterator</td>
<td><tt class="docutils literal">get_termpos</tt></td>
</tr>
<tr><td>PostingIterator</td>
<td><tt class="docutils literal">get_docid</tt></td>
</tr>
<tr><td>TermIterator</td>
<td><tt class="docutils literal">get_term</tt></td>
</tr>
<tr><td>ValueIterator</td>
<td><tt class="docutils literal">get_value</tt></td>
</tr>
<tr><td>MSetIterator</td>
<td><tt class="docutils literal">get_docid</tt></td>
</tr>
<tr><td>ESetIterator</td>
<td><tt class="docutils literal">get_term()</tt></td>
</tr>
</tbody>
</table>
<p>Other methods, such as <tt class="docutils literal">MSetIterator:get_document</tt>, are
available under the same names.</p>
</div>
<div class="section" id="mset">
<h1>MSet</h1>
<p>MSet objects have some additional methods to simplify access (these
work using the C++ array dereferencing):</p>
<table border="1" class="docutils">
<colgroup>
<col width="47%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Method name</th>
<th class="head">Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal">get_hit(index)</tt></td>
<td>returns MSetItem at index</td>
</tr>
<tr><td><tt class="docutils literal">get_documentPercentage(index)</tt></td>
<td><tt class="docutils literal">convert_to_percent(get_hit(index))</tt></td>
</tr>
<tr><td><tt class="docutils literal">get_document(index)</tt></td>
<td><tt class="docutils literal"><span class="pre">get_hit(index):get_document()</span></tt></td>
</tr>
<tr><td><tt class="docutils literal">get_docid(index)</tt></td>
<td><tt class="docutils literal"><span class="pre">get_hit(index):get_docid()</span></tt></td>
</tr>
</tbody>
</table>
<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 Lua:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">Xapian::version_string()</span></tt> is wrapped as <tt class="docutils literal">xapian.version_string()</tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::major_version()</span></tt> is wrapped as <tt class="docutils literal">xapian.major_version()</tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::minor_version()</span></tt> is wrapped as <tt class="docutils literal">xapian.minor_version()</tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::revision()</span></tt> is wrapped as <tt class="docutils literal">xapian.revision()</tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::Auto::open_stub()</span></tt> is wrapped as <tt class="docutils literal">xapian.open_stub()</tt> (but is now deprecated)</li>
<li><tt class="docutils literal"><span class="pre">Xapian::Chert::open()</span></tt> is wrapped as <tt class="docutils literal">xapian.chert_open()</tt> (but is now deprecated)</li>
<li><tt class="docutils literal"><span class="pre">Xapian::InMemory::open()</span></tt> is wrapped as <tt class="docutils literal">xapian.inmemory_open()</tt> (but is now deprecated)</li>
<li><tt class="docutils literal"><span class="pre">Xapian::Remote::open()</span></tt> is wrapped as <tt class="docutils literal">xapian.remote_open()</tt> (both the TCP and &quot;program&quot; versions are wrapped - the SWIG wrapper checks the parameter list to decide which to call).</li>
<li><tt class="docutils literal"><span class="pre">Xapian::Remote::open_writable()</span></tt> is wrapped as <tt class="docutils literal">xapian.remote_open_writable()</tt> (both the TCP and &quot;program&quot; versions are wrapped - the SWIG wrapper checks the parameter list to decide which to call).</li>
</ul>
</div>
<div class="section" id="constants">
<h1>Constants</h1>
<p>For Lua, constants are wrapped as <tt class="docutils literal">xapian.CONSTANT_NAME</tt>
or <tt class="docutils literal">xapian.ClassName_CONSTANT_NAME</tt>.
So <tt class="docutils literal"><span class="pre">Xapian::DB_CREATE_OR_OPEN</span></tt> is available as
<tt class="docutils literal">xapian.DB_CREATE_OR_OPEN</tt>, <tt class="docutils literal"><span class="pre">Xapian::Query::OP_OR</span></tt> is
available as <tt class="docutils literal">xapian.Query_OP_OR</tt>, and so on.</p>
<p>As of 1.3.2, you can also use the form <tt class="docutils literal">xapian.ClassName.CONSTANT_NAME</tt>, e.g.
<tt class="docutils literal">xapian.Query.OP_OR</tt>.</p>
</div>
<div class="section" id="query">
<h1>Query</h1>
<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 Lua, it is wrapped to accept Lua tables to give the terms/queries,
and you can specify a mixture of terms and queries if you wish.  For example:</p>
<pre class="literal-block">
subq = xapian.Query(xapian.Query_OP_AND, {&quot;hello&quot;, &quot;world&quot;})
q = xapian.Query(xapian.Query_OP_AND, {subq, &quot;foo&quot;, xapian.Query(&quot;bar&quot;, 2)})
</pre>
</div>
<div class="section" id="matchall-and-matchnothing">
<h1>MatchAll and MatchNothing</h1>
<p>These are wrapped for Lua as <tt class="docutils literal">xapian.Query_MatchAll</tt> and
<tt class="docutils literal">xapian.Query_MatchNothing</tt>.</p>
<p>As of 1.3.2, you can also use the forms <tt class="docutils literal">xapian.Query.MatchAll</tt> and
<tt class="docutils literal">xapian.Query.MatchNothing</tt>.</p>
</div>
<div class="section" id="enquire">
<h1>Enquire</h1>
<p>There is an additional method <tt class="docutils literal">get_matching_terms</tt> 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>
</div>
<div class="section" id="matchdecider">
<h1>MatchDecider</h1>
<p>Custom MatchDeciders can be created in Lua in the form of lua function; simply
function ensures you create a subclass of xapian.MatchDecider, which calls
the super-constructor, and overloads the operator method to callback the lua function
that will do the work. The simplest example (which does nothing
useful) would be as follows:</p>
<pre class="literal-block">
function mymatchdecider(doc)
   return 1
end
</pre>
</div>
</div>
</body>
</html>