mhs-xapian 1.0.18a

data/ruby/docs/examples/simpleexpand.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+#
+# Simple example script demonstrating query expansion.
+#
+# Originally by Paul Legato (plegato@nks.net), 4/22/06.
+#
+# Copyright (C) 2006 Networked Knowledge Systems, Inc.
+# 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
+
+require 'xapian'
+
+if ARGV.size < 2
+  $stderr.puts "Usage: #{$0} PATH_TO_DATABASE QUERY [-- [DOCID...]]"
+  exit 99
+end
+
+# Open the database for searching.
+database = Xapian::Database.new(ARGV[0])
+
+# Start an enquire session.
+enquire = Xapian::Enquire.new(database)
+
+queryString = ''
+relevantDocs = Xapian::RSet.new()
+onDocIdsYet = false
+
+# 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.
+ARGV.each_with_index { |arg,index|
+  next if index == 0 # skip path to db
+
+  if arg == '--'
+    onDocIdsYet = true
+    next
+  end
+
+  if onDocIdsYet
+    relevantDocs.add_document(arg.to_i)
+  else
+    queryString += ' ' unless queryString.empty?
+    queryString += arg
+  end
+}
+
+
+# Parse the query string to produce a Xapian::Query object.
+qp = Xapian::QueryParser.new()
+stemmer = Xapian::Stem.new("english")
+qp.stemmer = stemmer
+qp.database = database
+qp.stemming_strategy = Xapian::QueryParser::STEM_SOME
+query = qp.parse_query(queryString)
+
+unless query.empty?
+  puts "Parsed query is: #{query.description()}"
+
+  # Find the top 10 results for the query.
+  enquire.query = query
+  matchset = enquire.mset(0, 10, relevantDocs)
+
+  # Display the results.
+  puts "#{matchset.matches_estimated()} results found."
+  puts "Matches 1-#{matchset.size}:\n"
+
+  matchset.matches.each {|m|
+    puts "#{m.rank + 1}: #{m.percent}% docid=#{m.docid} [#{m.document.data}]\n"
+  }
+end
+  
+# Put the top 5 (at most) docs into the rset if rset is empty
+if relevantDocs.empty?
+  matchset.matches[0..4].each {|match|
+    relevantDocs.add_document(match.docid())
+  }
+end
+
+# Get the suggested expand terms
+expandTerms = enquire.eset(10, relevantDocs)
+puts "#{expandTerms.size()} suggested additional terms:"
+expandTerms.terms.each {|term|
+  puts "  * Term \"#{term.name}\", weight #{term.weight}"
+}

data/ruby/docs/examples/simpleindex.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+#
+# Index each paragraph of a text file as a Xapian document.
+#
+# Originally by Paul Legato (plegato@nks.net), 4/22/06
+# Based on Python's simplesearch.py
+# Copyright (C) 2006 Networked Knowledge Systems, Inc.
+# Copyright (C) 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
+
+require 'xapian'
+
+if ARGV.size != 1
+  $stderr.puts "Usage: #{$0} PATH_TO_DATABASE"
+  exit 99
+end
+
+# Open the database for update, creating a new database if necessary.
+database = Xapian::WritableDatabase.new(ARGV[0], Xapian::DB_CREATE_OR_OPEN)
+
+indexer = Xapian::TermGenerator.new()
+stemmer = Xapian::Stem.new("english")
+indexer.stemmer = stemmer
+
+para = ''
+while line = $stdin.gets()
+  line.strip!()
+  if line.empty?
+    if not para.empty?
+      # We've reached the end of a paragraph, so index it.
+      doc = Xapian::Document.new()
+      doc.data = para
+
+      indexer.document = doc
+      indexer.index_text(para)
+
+      # Add the document to the database
+      database.add_document(doc)
+      para = ''
+    end # if not para.empty?
+  else # line not empty
+    para += ' ' if para != ''
+    para += line
+  end # if line empty
+end
+

data/ruby/docs/examples/simplematchdecider.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+#
+# Simple command-line match decider example.
+#
+#
+# Copyright (C) 2006 Networked Knowledge Systems, Inc.
+# 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
+
+require 'xapian'
+
+if ARGV.size < 3
+  $stderr.puts "Usage: #{$0} PATH_TO_DATABASE AVOID_VALUE QUERY"
+  exit 99
+end
+
+class MyMatchDecider < Xapian::MatchDecider
+  def initialize(avoidvalue)
+    @avoidvalue = avoidvalue
+    super()
+  end
+
+  def __call__(doc)
+    return doc.value(0) != @avoidvalue
+  end
+end
+
+# Open the database for searching.
+database = Xapian::Database.new(ARGV[0])
+
+# Start an enquire session.
+enquire = Xapian::Enquire.new(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.
+queryString = ARGV[2..-1].join(' ')
+
+# Parse the query string to produce a Xapian::Query object.
+qp = Xapian::QueryParser.new()
+stemmer = Xapian::Stem.new("english")
+qp.stemmer = stemmer
+qp.database = database
+qp.stemming_strategy = Xapian::QueryParser::STEM_SOME
+query = qp.parse_query(queryString)
+
+puts "Parsed query is: #{query.description()}"
+
+# Find the top 10 results for the query.
+enquire.query = query
+mdecider = MyMatchDecider.new(ARGV[1])
+matchset = enquire.mset(0, 10, nil, mdecider)
+
+# Display the results.
+puts "#{matchset.matches_estimated()} results found."
+puts "Matches 1-#{matchset.size}:\n"
+
+matchset.matches.each {|m|
+  puts "#{m.rank + 1}: #{m.percent}% docid=#{m.docid} [#{m.document.data}]\n"
+}

data/ruby/docs/examples/simplesearch.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+#
+# Simple command-line search script.
+#
+# Originally by Paul Legato (plegato@nks.net), 4/22/06.
+#
+# Copyright (C) 2006 Networked Knowledge Systems, Inc.
+# 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
+
+require 'xapian'
+
+if ARGV.size < 2
+  $stderr.puts "Usage: #{$0} PATH_TO_DATABASE QUERY"
+  exit 99
+end
+
+# Open the database for searching.
+database = Xapian::Database.new(ARGV[0])
+
+# Start an enquire session.
+enquire = Xapian::Enquire.new(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.
+queryString = ARGV[1..-1].join(' ')
+
+# Parse the query string to produce a Xapian::Query object.
+qp = Xapian::QueryParser.new()
+stemmer = Xapian::Stem.new("english")
+qp.stemmer = stemmer
+qp.database = database
+qp.stemming_strategy = Xapian::QueryParser::STEM_SOME
+query = qp.parse_query(queryString)
+
+puts "Parsed query is: #{query.description()}"
+
+# Find the top 10 results for the query.
+enquire.query = query
+matchset = enquire.mset(0, 10)
+
+# Display the results.
+puts "#{matchset.matches_estimated()} results found."
+puts "Matches 1-#{matchset.size}:\n"
+
+matchset.matches.each {|m|
+  puts "#{m.rank + 1}: #{m.percent}% docid=#{m.docid} [#{m.document.data}]\n"
+}

data/ruby/docs/index.html

@@ -0,0 +1,197 @@
+<html><head><title>Ruby bindings for Xapian</title></head>
+<body>
+<h1>Ruby bindings for Xapian</h1>
+
+<p>
+The Ruby bindings for Xapian are packaged in the <code>xapian</code> module.
+Ruby strings and arrays are converted automatically in the bindings, so
+generally they should just work naturally.
+</p>
+
+<p>
+The <code>examples</code> subdirectory contains examples showing how to use the
+Ruby bindings based on the simple examples from <code>xapian-examples</code>:
+<a href="examples/simpleindex.rb">simpleindex.rb</a>,
+<a href="examples/simplesearch.rb">simplesearch.rb</a>,
+<a href="examples/simpleexpand.rb">simpleexpand.rb</a>.
+There's also 
+<a href="examples/simplematchdecider.rb">simplematchdecider.rb</a>
+which shows how to define a MatchDecider in Ruby.
+</p>
+
+<h2>Usage</h2>
+
+<p>To use the bindings, you need to use <code>require 'xapian'</code>
+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. get_foo() in C++ becomes foo()
+in Ruby; set_foo() becomes foo=().)  C++ 'operator()' methods are
+renamed to 'call' methods in Ruby.
+</p>
+
+<p>
+The C++ methods are not yet documented in the <a href="rdocs/">RDocs</a>.
+In the meantime, refer to the 
+<a href="http://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 underscores ('_') 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 _ directly in your code, but instead use the
+wrappers defined in xapian.rb. Improper use of an _ method can cause
+the Ruby process to segfault.
+</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.  If you want
+to index strings in a different encoding, use the Ruby
+<a href="http://www.ruby-doc.org/stdlib/libdoc/iconv/rdoc/index.html"
+><code>Iconv</code> class</a>
+to convert them to UTF-8 before passing them to Xapian, and
+when reading values back from Xapian.
+</p>
+
+<!--
+<h2>Exceptions</h2>
+
+<p>
+   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.
+</p>
+-->
+
+<h2>Iterators</h2>
+
+<p>
+One important difference from the C++ API is that *Iterator
+classes should not be used from Ruby, as they fit awkwardly into
+standard Ruby iteration paradigms, and as many of them cause segfaults
+if used improperly. They have all been wrapped with appropriate
+methods that simply return the *Iterator objects in an Array, so that
+you can use 'each' to iterate through them.
+</p>
+
+<pre>
+   mset.matches.each {|match|
+     # do something
+   }
+</pre>
+
+<!--
+<h2>Iterator dereferencing</h2>
+
+<p>
+   C++ iterators are often dereferenced to get information, eg
+   <code>(*it)</code>. With Python 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 unchanged.
+</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>get_hit(index)</code></td><td>returns MSetIterator at index</td></tr>
+<tr><td><code>get_document_percentage(index)</code></td><td><code>convert_to_percent(get_hit(index))</code></td></tr>
+<tr><td><code>get_document(index)</code></td><td><code>get_hit(index).get_document()</code></td></tr>
+<tr><td><code>get_docid(index)</code></td><td><code>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 Ruby:
+<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>
+<li> <code>Xapian::InMemory::open()</code> is wrapped as <code>Xapian::inmemory_open()</code>
+<li> <code>Xapian::Quartz::open()</code> is wrapped as <code>Xapian::quartz_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>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 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>
+   subq = Xapian::Query.new(Xapian::Query::OP_AND, "hello", "world")
+   q = Xapian::Query.new(Xapian::Query::OP_AND, [subq, "foo", Xapian::Query.new("bar", 2)])
+</pre>
+
+<h2>MatchDecider</h2>
+
+<p>
+Custom MatchDeciders can be created in Ruby; simply subclass
+Xapian::MatchDecider, ensure you call the superclass constructor, and define a
+__call__ method that will do the work. The simplest example (which does nothing
+useful) would be as follows:
+</p>
+
+<pre>
+class MyMatchDecider &lt; Xapian::MatchDecider
+  def __call__(doc):
+    return true
+  end
+end
+</pre>
+
+<address>
+Last updated $Date: 2006-04-01 16:35:10 +0100 (Sat, 01 Apr 2006) $
+</address>
+</body>
+</html>