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 (489 lines) | stat: -rw-r--r-- 16,243 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>Ruby 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="ruby-bindings-for-xapian">
<h1 class="title">Ruby bindings for Xapian</h1>

<p>The Ruby bindings for Xapian are packaged in the <tt class="docutils literal">xapian</tt> module.
Ruby strings and arrays are converted automatically in the bindings, so
generally they should just work naturally.</p>
<p>The <tt class="docutils literal">examples</tt> subdirectory contains examples showing how to use the
Ruby 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.rb">simpleindex.rb</a>,
<a class="reference external" href="examples/simplesearch.rb">simplesearch.rb</a>,
<a class="reference external" href="examples/simpleexpand.rb">simpleexpand.rb</a>.
There's also
<a class="reference external" href="examples/simplematchdecider.rb">simplematchdecider.rb</a>
which shows how to define a MatchDecider in Ruby.</p>
<div class="section" id="usage">
<h1>Usage</h1>
<p>To use the bindings, you need to use <tt class="docutils literal">require 'xapian'</tt>
in your ruby program.</p>
<p>Most standard Xapian methods are available directly
to your Ruby program. Names have been altered to conform to the
standard Ruby naming conventions (i.e. <tt class="docutils literal">get_foo()</tt> in C++ becomes <tt class="docutils literal">foo()</tt>
in Ruby; <tt class="docutils literal">set_foo()</tt> becomes <tt class="docutils literal"><span class="pre">foo=()</span></tt>).  C++ <tt class="docutils literal">operator()</tt> methods are
renamed to <tt class="docutils literal">__call__</tt> methods in Ruby.</p>
<p>The C++ methods are not yet documented in the <a class="reference external" href="rdocs/">RDocs</a>.
In the meantime, refer to the
<a class="reference external" href="https://xapian.org/docs/apidoc/html/annotated.html">C++ API documentation</a>
for information on how to use the various methods. Most are
available directly in the Ruby version. The RDocs currently provide information
only on methods that are unique to the Ruby version.</p>
<p>The dangerous/non-Rubish methods from the C++ API have been renamed to
start with a single underscore (<tt class="docutils literal">_</tt>) in the Ruby bindings. You can see them
in use in xapian.rb. It is strongly recommended that you do not call any
method that starts with a single underscore directly in your code, but instead
use the wrappers defined in xapian.rb. Improper use of such methods can
cause the Ruby process to segfault.</p>
</div>
<div class="section" id="unicode-support">
<h1>Unicode Support</h1>
<p>In Xapian 1.0.0 and later, the <tt class="docutils literal"><span class="pre">Xapian::Stem</span></tt>, <tt class="docutils literal"><span class="pre">Xapian::QueryParser</span></tt>, and
<tt class="docutils literal"><span class="pre">Xapian::TermGenerator</span></tt> classes all assume text is in UTF-8.  If you want
to index or search for strings in a different encoding, convert them to UTF-8
before passing them to Xapian, and when getting strings back from Xapian.
The recommended way to do this is using the <a class="reference external" href="https://ruby-doc.org/core/String.html#method-i-encode">String#encode</a> method.</p>
<!-- Exceptions -->
<!-- ########## -->
<!-- Exceptions are thrown as SWIG exceptions instead of Xapian -->
<!-- exceptions. This isn't done well at the moment; in future we will -->
<!-- throw wrapped Xapian exceptions. For now, it's probably easier to -->
<!-- catch all exceptions and try to take appropriate action based on -->
<!-- their associated string. -->
</div>
<div class="section" id="iterators">
<h1>Iterators</h1>
<p>The iterator classes in the Xapian C++ API are wrapped to allow them
to be used in a more idiomatic way from Ruby.  Where the C++ API
has a pair of methods to return a begin and end iterator, the Ruby
API has a single method which (in Xapian 1.4.12 and later) supports block
iteration, for example:</p>
<pre class="literal-block">
mset.matches {|match|
  # do something
}
</pre>
<p>If no block is specified, an Array is returned instead (which was the only
option prior to Xapian 1.4.12).  You can use <tt class="docutils literal">each</tt> on this Array to achieve
a similar result to passing a block, except the C++ iterator is read eagerly
rather than lazily:</p>
<pre class="literal-block">
mset.matches.each {|match|
  # do something
}
</pre>
</div>
<div class="section" id="non-class-functions">
<h1>Non-Class Functions</h1>
<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 Ruby:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">Xapian::version_string()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::version_string()</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::major_version()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::major_version()</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::minor_version()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::minor_version()</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::revision()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::revision()</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Xapian::Auto::open_stub()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::open_stub()</span></tt> (now deprecated)</li>
<li><tt class="docutils literal"><span class="pre">Xapian::Chert::open()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::chert_open()</span></tt> (now deprecated)</li>
<li><tt class="docutils literal"><span class="pre">Xapian::InMemory::open()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::inmemory_open()</span></tt> (now deprecated)</li>
<li><tt class="docutils literal"><span class="pre">Xapian::Remote::open()</span></tt> is wrapped as <tt class="docutils literal"><span class="pre">Xapian::remote_open()</span></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"><span class="pre">Xapian::remote_open_writable()</span></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="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 Ruby, this is wrapped to accept a Ruby array containing
terms, or queries, or even a mixture of terms and queries.  For example:</p>
<pre class="literal-block">
subq = Xapian::Query.new(Xapian::Query::OP_AND, &quot;hello&quot;, &quot;world&quot;)
q = Xapian::Query.new(Xapian::Query::OP_AND, [subq, &quot;foo&quot;, Xapian::Query.new(&quot;bar&quot;, 2)])
</pre>
<div class="section" id="matchall-and-matchnothing">
<h2>MatchAll and MatchNothing</h2>
<p>In Xapian 1.3.0 and later, these are wrapped as class constants
<tt class="docutils literal"><span class="pre">Xapian::Query::MatchAll</span></tt> and <tt class="docutils literal"><span class="pre">Xapian::Query::MatchNothing</span></tt>.</p>
<p>If you want to be compatible with earlier versions, you can continue to use
<tt class="docutils literal"><span class="pre">Xapian::Query.new(&quot;&quot;)</span></tt> for MatchAll and
<tt class="docutils literal"><span class="pre">Xapian::Query.new()</span></tt> for MatchNothing.</p>
</div>
</div>
<div class="section" id="matchdecider">
<h1>MatchDecider</h1>
<p>Custom MatchDeciders can be created in Ruby; simply subclass
Xapian::MatchDecider, ensure you call the superclass constructor, and define a
<tt class="docutils literal">__call__</tt> method that will do the work. The simplest example (which does
nothing useful) would be as follows:</p>
<pre class="literal-block">
class MyMatchDecider &lt; Xapian::MatchDecider
  def __call__(doc):
    return true
  end
end
</pre>
</div>
</div>
</body>
</html>