mhs-xapian 1.0.18a

data/ruby/smoketest.rb

@@ -0,0 +1,211 @@
+#!/usr/bin/ruby -w
+#
+# smoketest.rb - test Xapian bindings for Ruby
+# Original version by Paul Legato (plegato@nks.net), 4/17/2006
+#
+# Originally based on smoketest.php from the PHP4 bindings.
+#
+# Copyright (C) 2006 Networked Knowledge Systems, Inc.
+# Copyright (C) 2008,2009 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 'test/unit'
+require 'xapian'
+
+class TestMatchDecider < Xapian::MatchDecider
+  def __call__(doc)
+    return doc.value(0) == "yes"
+  end
+end
+
+class XapianSmoketest < Test::Unit::TestCase
+
+  def setup 
+    @stem = Xapian::Stem.new("english")
+
+    @doc = Xapian::Document.new()
+    @doc.data = "is there anybody out there?"
+    @doc.add_posting(@stem.call("is"), 1)
+    @doc.add_posting(@stem.call("there"), 2)
+    @doc.add_posting(@stem.call("anybody"), 3)
+    @doc.add_posting(@stem.call("out"), 4)
+    @doc.add_posting(@stem.call("there"), 5)    
+    @doc.add_term("XYzzy")
+
+    @db = Xapian::inmemory_open()
+    @db.add_document(@doc)
+
+    @enq = Xapian::Enquire.new(@db)
+  end # setup
+
+  def test_version
+    # Test the version number reporting functions give plausible results.
+    @v = sprintf("%d.%d.%d", Xapian::major_version(), Xapian::minor_version(),
+                 Xapian::revision())
+    @v2 = Xapian::version_string()
+    assert_equal(@v2, @v)
+  end # test_version
+
+  def test_stem
+    assert_equal("Xapian::Stem(english)", @stem.description())    
+
+    assert_equal("is", @stem.call("is"))
+    assert_equal("go", @stem.call("going"))
+    assert_equal("want", @stem.call("wanted"))
+    assert_equal("refer", @stem.call("reference"))
+  end # test_stem
+
+  # subtests are those on which some test_foo() method depends.
+  def test_000_document
+    assert_not_nil(@doc)
+
+    assert_equal("is there anybody out there?", @doc.data())
+
+    assert_equal(@doc.termlist_count(), 5)
+    assert_equal("XYzzy", @doc.terms().first.term)
+
+    @doc.add_term("foo")
+    assert_equal(6, @doc.termlist_count())
+    assert_equal(@doc.terms.size(), @doc.termlist_count())
+
+  end # test_document
+
+  def test_001_database
+    assert_not_nil(@db)
+    assert_equal("WritableDatabase()", @db.description())
+    assert_equal(1, @db.doccount())
+  end # test_database
+
+  def test_002_queries
+    assert_equal("Xapian::Query((smoke OR test OR terms))",  
+                 Xapian::Query.new(Xapian::Query::OP_OR ,["smoke", "test", "terms"]).description())
+
+    phraseQuery = Xapian::Query.new(Xapian::Query::OP_PHRASE ,["smoke", "test", "tuple"])
+    xorQuery = Xapian::Query.new(Xapian::Query::OP_XOR, [ Xapian::Query.new("smoke"), phraseQuery, "string" ])
+
+    assert_equal("Xapian::Query((smoke PHRASE 3 test PHRASE 3 tuple))", phraseQuery.description())
+    assert_equal("Xapian::Query((smoke XOR (smoke PHRASE 3 test PHRASE 3 tuple) XOR string))", xorQuery.description())
+
+    assert_equal([Xapian::Term.new("smoke", 1), 
+                  Xapian::Term.new("string", 1), 
+                  Xapian::Term.new("test", 1), 
+                  Xapian::Term.new("tuple", 1)], xorQuery.terms())
+
+    assert_equal(Xapian::Query::OP_ELITE_SET, 10)
+  end # test_queries
+
+  def test_003_enquire
+    @enq = Xapian::Enquire.new(@db)
+    assert_not_nil(@enq)
+    
+    @enq.query = Xapian::Query.new(Xapian::Query::OP_OR, "there", "is")
+    mset = @enq.mset(0, 10)
+
+    assert_equal(1, mset.size())
+
+    # Feature test for Enquire.matching_terms()
+    assert_equal(2, @enq.matching_terms(mset.hit(0)).size())
+    assert_equal([Xapian::Term.new("is", 1), Xapian::Term.new("there", 1)],
+                 @enq.matching_terms(mset.hit(0)))
+  end # test_enquire
+
+  def test_004_mset_iterator
+    @enq = Xapian::Enquire.new(@db)
+    assert_not_nil(@enq)
+    
+    @enq.query = Xapian::Query.new(Xapian::Query::OP_OR, "there", "is")
+    mset = @enq.mset(0, 10)
+
+    assert_equal(mset.matches().size(), mset.size())
+  end
+
+
+  def test_005_eset_iterator
+    rset = Xapian::RSet.new
+
+    rset.add_document(1)
+
+    @enq = Xapian::Enquire.new(@db)
+    @enq.query = Xapian::Query.new(Xapian::Query::OP_OR, "there", "is")
+
+    eset = @enq.eset(10, rset)
+    assert_not_nil(eset)
+
+    assert_equal(3, eset.terms.size())
+  end # test_eset_iter
+
+  # Feature test for Database.allterms
+  def test_006_database_allterms
+    assert_equal(5, @db.allterms.size())
+  end
+  
+  # Feature test for Database.postlist
+  def test_007_database_postlist
+    assert_equal(1, @db.postlist("there").size())
+  end
+
+  # Feature test for Database.termlist
+  def test_008_database_termlist
+    assert_equal(5, @db.termlist(1).size())
+  end
+
+  # Feature test for Database.positionlist
+  def test_009_database_positionlist
+    assert_equal(2, @db.positionlist(1, "there").size())
+  end
+
+  # Feature test for Document.values
+  def test_010_document_values
+    assert_equal(0, @doc.values().size())
+  end
+
+  def test_011_matchdecider
+    @doc = Xapian::Document.new()
+    @doc.data = "Two"
+    @doc.add_posting(@stem.call("out"), 1)
+    @doc.add_posting(@stem.call("source"), 2)
+    @doc.add_value(0, "yes")
+    @db.add_document(@doc)
+
+    @query = Xapian::Query.new(@stem.call("out"))
+    enquire = Xapian::Enquire.new(@db)
+    enquire.query = @query
+    mset = enquire.mset(0, 10, nil, TestMatchDecider.new)
+    assert_equal(mset.size(), 1)
+    assert_equal(mset.docid(0), 2)
+  end
+
+  def test_012_metadata
+    assert_equal(@db.get_metadata('Foo'), '')
+    @db.set_metadata('Foo', 'Foo')
+    assert_equal(@db.get_metadata('Foo'), 'Foo')
+  end
+
+  def test_013_scaleweight
+    query = Xapian::Query.new("foo")
+    query2 = Xapian::Query.new(Xapian::Query::OP_SCALE_WEIGHT, query, 5);
+    assert_equal(query2.description(), "Xapian::Query(5 * foo)")
+  end
+
+  def test_014_sortable_serialise
+    # In Xapian 1.0.13/1.1.1 and earlier, the SWIG generated wrapper code
+    # didn't handle integer values > MAXINT for double parameters.
+    v = 51767811298
+    assert_equal(v, Xapian::sortable_unserialise(Xapian::sortable_serialise(v)))
+  end
+
+end # class XapianSmoketest

data/ruby/util.i

@@ -0,0 +1,232 @@
+%{
+/* ruby/util.i: custom Ruby typemaps for xapian-bindings
+ *
+ * Original version by Paul Legato (plegato@nks.net), 4/17/06.
+ * Based on the php4 and python util.i files.
+ *
+ * Copyright (C) 2006 Networked Knowledge Systems, Inc.
+ * Copyright (C) 2006,2007,2009 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
+ *
+ */
+
+%}
+
+// Use SWIG directors for Ruby wrappers.
+#define XAPIAN_SWIG_DIRECTORS
+
+// We don't use the Iterator and ConstIterator wrappers which SWIG now offers,
+// so disable them to reduce the generated C++ wrapper code.
+#define SWIG_NO_EXPORT_ITERATOR_METHODS
+
+/////////////////////////////////////
+// Rename function and method names to match Ruby conventions
+// e.g. from get_data to data and from set_data to data=
+
+// Getters
+%rename("available_languages") get_available_languages;
+%rename("avlength") get_avlength;
+%rename("collapse_count") get_collapse_count;
+%rename("collection_freq") get_collection_freq;
+%rename("context") get_context;
+%rename("data") get_data;
+%rename("default_op") get_default_op;
+%rename("description") get_description;
+%rename("docid") get_docid;
+%rename("document_id") get_document_id;
+%rename("document_percentage") get_document_percentage;
+%rename("doccount") get_doccount;
+%rename("doclength") get_doclength;
+%rename("document") get_document;
+%rename("ebound") get_ebound;
+%rename("errno") get_errno;
+%rename("eset") get_eset;
+%rename("firstitem") get_firstitem;
+%rename("hit") get_hit;
+%rename("lastdocid") get_lastdocid;
+%rename("length") get_length;
+%rename("matches_estimated") get_matches_estimated;
+%rename("matches_lower_bound") get_matches_lower_bound;
+%rename("matches_upper_bound") get_matches_upper_bound;
+%rename("matching_terms") get_matching_terms;
+%rename("max_attained") get_max_attained;
+%rename("max_possible") get_max_possible;
+%rename("maxextra") get_maxextra;
+%rename("maxpart") get_maxpart;
+%rename("mset") get_mset;
+%rename("msg") get_msg;
+%rename("op_name") get_op_name;
+%rename("percent") get_percent;
+%rename("query") get_query;
+%rename("rank") get_rank;
+%rename("sumextra") get_sumextra;
+%rename("sumpart") get_sumpart;
+%rename("sumpart_needs_doclength") get_sumpart_needs_doclength;
+%rename("termfreq") get_termfreq;
+%rename("terms") get_terms;
+%rename("term") get_term;
+%rename("termpos") get_termpos;
+%rename("termname") get_termname;
+%rename("termweight") get_termweight;
+%rename("type") get_type;
+%rename("value") get_value;
+%rename("valueno") get_valueno;
+%rename("wdf") get_wdf;
+%rename("weight") get_weight;
+
+// These are 'dangerous' methods; i.e. they can cause a segfault if used
+// improperly.  We prefix with _dangerous_ so that Ruby users will not use them
+// inadvertently.
+//
+// There is a safe wrapper for their functionality provided in xapian.rb.
+
+// in Xapian::Document and Xapian::Database
+%rename("_dangerous_termlist_begin") termlist_begin;
+%rename("_dangerous_termlist_end") termlist_end;
+// in Xapian::Query
+%rename("_dangerous_terms_begin") get_terms_begin;
+%rename("_dangerous_terms_end") get_terms_end;
+// in Xapian::Enquire
+%rename("_dangerous_matching_terms_begin") get_matching_terms_begin;
+%rename("_dangerous_matching_terms_end") get_matching_terms_end;
+// in Xapian::Database
+%rename("_dangerous_allterms_begin") allterms_begin;
+%rename("_dangerous_allterms_end") allterms_end;
+// in Xapian::Database
+%rename("_dangerous_postlist_begin") postlist_begin;
+%rename("_dangerous_postlist_end") postlist_end;
+// in Xapian::Database
+%rename("_dangerous_positionlist_begin") positionlist_begin;
+%rename("_dangerous_positionlist_end") positionlist_end;
+// in Xapian::Document
+%rename("_dangerous_values_begin") values_begin;
+%rename("_dangerous_values_end") values_end;
+
+
+// MSetIterators are not dangerous, just inconvenient to use within a Ruby
+// idiom.
+%rename ("_begin") begin;
+%rename ("_end") end;
+%rename ("_back") back;
+
+
+
+// Setters
+%rename("collapse_key=") set_collapse_key;
+%rename("cutoff!") set_cutoff;
+%rename("data=") set_data;
+%rename("database=") set_database;
+%rename("default_op=") set_default_op;
+%rename("docid_order=") set_docid_order;
+%rename("document=") set_document;
+%rename("query=") set_query(const Query &);
+%rename("query!") set_query(const Query &, termcount qlen);
+%rename("sort_by_relevance!") set_sort_by_relevance;
+%rename("sort_by_relevance_then_value!") set_sort_by_relevance_then_value;
+%rename("sort_by_value_then_relevance!") set_sort_by_value_then_relevance;
+%rename("sort_by_value!") set_sort_by_value;
+%rename("stemmer=") set_stemmer;
+%rename("stemming_strategy=") set_stemming_strategy;
+%rename("stopper=") set_stopper;
+%rename("weighting_scheme=") set_weighting_scheme;
+
+// Booleans
+%predicate empty;
+
+// Other deprecated methods
+%ignore Xapian::xapian_version_string();
+%ignore Xapian::xapian_major_version();
+%ignore Xapian::xapian_minor_version();
+%ignore Xapian::xapian_revision();
+
+#define XAPIAN_MIXED_VECTOR_QUERY_INPUT_TYPEMAP
+/*
+ * Check to see what is equivalent to a C++ Vector for the purposes of a Query
+ * instantiation.
+ * At the moment, we take Ruby Arrays.
+ */
+%typemap(typecheck, precedence=500) const vector<Xapian::Query> & {
+    $1 = (TYPE($input) == T_ARRAY);
+
+    /* Says Olly:
+     * Currently, the only wrapped method which takes a Ruby array is the
+     * "extra" constructor Query(OP, ARRAY), where ARRAY can contain any mix of
+     * strings and Query objects.
+     *
+     * If we ever had a method (or function) which had two overloaded forms
+     * only differentiated by what type of array can be passed we'd need to
+     * look at the type of the array element in the typecheck typemaps.
+     */
+}
+
+/*
+ * Convert Ruby Arrays to C++ Vectors for Query instantiation.
+ */
+%typemap(in) const vector<Xapian::Query> & (vector<Xapian::Query> v) {
+    if (TYPE($input) != T_ARRAY) {
+	SWIG_exception(SWIG_ValueError, "expected array of queries");
+    }
+
+    int numitems = RARRAY_LEN($input);
+    v.reserve(numitems);
+    for (int i = 0; i < numitems; ++i) {
+      VALUE arrayEntry = rb_ary_entry($input, i);
+      if (TYPE(arrayEntry) == T_STRING) {
+        v.push_back(Xapian::Query(string(RSTRING_PTR(arrayEntry),
+					 RSTRING_LEN(arrayEntry))));
+      }
+      else {
+        // array element may be a Xapian::Query object. Add it if it is,
+        // otherwise error out.
+        Xapian::Query *subq = 0;
+        if (SWIG_ConvertPtr(arrayEntry, (void **)&subq,
+                            SWIGTYPE_p_Xapian__Query, 0) < 0) {
+          subq = 0;
+        }
+        if (!subq) {
+          SWIG_exception(SWIG_ValueError, "elements of Arrays passed to Query must be either Strings or other Queries");
+        }
+        v.push_back(*subq);            
+      }
+
+    }       
+
+    $1 = &v;
+}
+
+
+#if 0
+// We don't want to generate get_matching_terms this way for Ruby - instead
+// we define it in xapian.rb.
+/*
+ * Convert a begin/end pair of TermIterators into Arrays of Terms.
+ */
+#define XAPIAN_TERMITERATOR_PAIR_OUTPUT_TYPEMAP
+%typemap(out) std::pair<Xapian::TermIterator, Xapian::TermIterator> {
+    $result = rb_ary_new();
+
+    for (Xapian::TermIterator i = $1.first; i != $1.second; ++i) {
+	VALUE str = rb_str_new((*i).data(), (*i).size());
+	rb_ary_push($result, str);
+    }
+}
+#endif
+
+// For MatchDecider::operator() and ExpandDecider::operator().
+%typemap(directorout) int = bool;
+
+/* vim:set syntax=cpp:set noexpandtab: */

data/ruby/xapian.rb

@@ -0,0 +1,280 @@
+# :title:Ruby Xapian bindings
+# =Ruby Xapian bindings
+#
+# Original version by Paul Legato (plegato@nks.net), 4/20/06.
+#
+# Copyright (C) 2006 Networked Knowledge Systems, Inc.
+#
+# 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
+#
+# ==Underscore methods
+# Note: Methods whose names start with an underscore character _ are internal
+# methods from the C++ API. Their functionality is not accessible in a
+# Ruby-friendly way, so this file provides wrapper code to make it easier to
+# use them from a Ruby programming idiom.  Most are also dangerous insofar as
+# misusing them can cause your program to segfault.  In particular, all of
+# Xapian's *Iterator classes are wrapped into nice Ruby-friendly Arrays.
+#
+# It should never be necessary to use any method whose name starts with an
+# underscore from user-level code. Make sure you are _VERY_ certain that you
+# know exactly what you're doing if you do use one of these methods. Beware.
+# You've been warned...
+#
+
+
+module Xapian
+  ######## load the SWIG-generated library
+  require '_xapian'
+
+
+  # iterate over two dangerous iterators (i.e. those that can cause segfaults
+  # if used improperly.)
+  # Return the results as an Array.
+  # Users should never need to use this method.
+  #
+  # Takes a block that returns some appropriate Ruby object to wrap the
+  # underlying Iterator
+  def _safelyIterate(dangerousStart, dangerousEnd) #:nodoc:
+    retval = Array.new
+    
+    item = dangerousStart
+    lastTerm = dangerousEnd
+    
+    return retval if dangerousStart.equals(dangerousEnd)
+
+    begin      
+      retval.push(yield(item))
+      item.next()
+    end while not item.equals(lastTerm) # must use primitive C++ comparator 
+    
+    return retval
+  end # _safelyIterate
+  module_function :_safelyIterate
+
+  #--
+  ### safe Ruby wrapper for the dangerous C++ Xapian::TermIterator class
+  class Xapian::Term
+    attr_accessor :term, :wdf, :termfreq
+
+    def initialize(term, wdf=nil, termfreq=nil)
+      @term = term
+      @wdf = wdf
+      @termfreq = termfreq
+    end
+
+    def ==(other)
+      return other.is_a?(Xapian::Term) && other.term == @term && other.wdf == @wdf && other.termfreq == @termfreq
+    end
+  end # class Term
+
+  ### Ruby wrapper for a Match, i.e. a Xapian::MSetIterator (Match Set) in C++.
+  # it's no longer an iterator in the Ruby version, but we want to preserve its
+  # non-iterative data.
+  # (MSetIterator is not dangerous, but it is inconvenient to use from a Ruby
+  # idiom, so we wrap it..)
+  class Xapian::Match     
+    attr_accessor :docid, :document, :rank, :weight, :collapse_count, :percent
+
+    def initialize(docid, document, rank, weight, collapse_count, percent)
+      @docid = docid
+      @document = document
+      @rank = rank
+      @weight = weight
+      @collapse_count = collapse_count
+      @percent = percent
+    end # initialize
+
+    def ==(other)
+      return other.is_a?(Xapian::Match) && other.docid == @docid && other.rank == @rank && 
+        other.weight == @weight && other.collapse_count == @collapse_count && other.percent == @percent
+    end
+  end # class Xapian::Match
+
+  # Ruby wrapper for an ExpandTerm, i.e. a Xapian::ESetIterator in C++
+  # Not dangerous, but inconvenient to use from a Ruby programming idiom, so we
+  # wrap it.
+  class Xapian::ExpandTerm
+    attr_accessor :name, :weight
+
+    def initialize(name, weight)
+      @name = name
+      @weight = weight
+    end # initialize
+
+    def ==(other)
+      return other.is_a?(Xapian::ExpandTerm) && other.name == @name && other.weight == @weight
+    end
+
+  end # Xapian::ExpandTerm
+
+  # Ruby wrapper for Xapian::ValueIterator
+  class Xapian::Value
+    attr_accessor :value, :valueno
+    
+    def initialize(value, valueno)
+      @value = value
+      @valueno = valueno
+    end # initialize
+
+    def ==(other)
+      return other.is_a?(Xapian::Value) && other.value == @value && other.valueno == @valueno
+    end
+  end # Xapian::Value
+
+  # Refer to the
+  # {Xapian::Document C++ API documentation}[http://xapian.org/docs/apidoc/html/classXapian_1_1Document.html]
+  # for methods not specific to Ruby.
+  #--
+  # Extend Xapian::Document with a nice wrapper for its nasty input_iterators
+  class Xapian::Document
+    def terms
+      Xapian._safelyIterate(self._dangerous_termlist_begin(), self._dangerous_termlist_end()) { |item|
+        Xapian::Term.new(item.term, item.wdf)
+      }
+    end # terms
+
+    def values
+      Xapian._safelyIterate(self._dangerous_values_begin(), self._dangerous_values_end()) { |item|
+        Xapian::Value.new(item.value, item.valueno)
+      }
+    end # terms
+
+  end # class Xapian::Document
+
+  # Refer to the
+  # {Xapian::Query C++ API documentation}[http://xapian.org/docs/apidoc/html/classXapian_1_1Query.html]
+  # for methods not specific to Ruby.
+  #--
+  # Extend Xapian::Query with a nice wrapper for its dangerous iterators
+  class Xapian::Query
+    def terms
+      Xapian._safelyIterate(self._dangerous_terms_begin(), self._dangerous_terms_end()) { |item|
+        Xapian::Term.new(item.term, item.wdf)
+        # termfreq is not supported by TermIterators from Queries
+      }
+    end
+  end # Xapian::Query
+
+  # Refer to the
+  # {Xapian::Enquire C++ API documentation}[http://xapian.org/docs/apidoc/html/classXapian_1_1Enquire.html]
+  # for methods not specific to Ruby.
+  #--
+  # Extend Xapian::Enquire with a nice wrapper for its dangerous iterators
+  class Xapian::Enquire
+    # Get matching terms for some document.
+    # document can be either a Xapian::DocID or a Xapian::MSetIterator
+    def matching_terms(document)
+      Xapian._safelyIterate(self._dangerous_matching_terms_begin(document), 
+                            self._dangerous_matching_terms_end(document)) { |item|
+        Xapian::Term.new(item.term, item.wdf)
+      }
+    end
+  end # Xapian::Enquire
+
+  # Refer to the
+  # {Xapian::MSet C++ API documentation}[http://xapian.org/docs/apidoc/html/classXapian_1_1MSet.html]
+  # for methods not specific to Ruby.
+  #--
+  # MSetIterators are not dangerous, just inconvenient to use within a Ruby
+  # programming idiom. So we wrap them.
+  class Xapian::MSet
+    def matches
+      Xapian._safelyIterate(self._begin(), 
+                            self._end()) { |item|
+        Xapian::Match.new(item.docid, item.document, item.rank, item.weight, item.collapse_count, item.percent)
+      }
+
+    end # matches
+  end # Xapian::MSet
+
+  # Refer to the
+  # {Xapian::ESet C++ API documentation}[http://xapian.org/docs/apidoc/html/classXapian_1_1ESet.html]
+  # for methods not specific to Ruby.
+  #--
+  # ESetIterators are not dangerous, just inconvenient to use within a Ruby
+  # programming idiom. So we wrap them.
+  class Xapian::ESet
+    def terms
+      Xapian._safelyIterate(self._begin(), 
+                            self._end()) { |item|
+	# note: in the ExpandTerm wrapper, we implicitly rename
+	# ESetIterator#termname() (defined in xapian.i) to ExpandTerm#term()
+        Xapian::ExpandTerm.new(item.termname, item.weight)
+      }
+
+    end # terms
+  end # Xapian::ESet
+
+
+  #--
+  # Wrapper for the C++ class Xapian::PostingIterator
+  class Xapian::Posting
+    attr_accessor :docid, :doclength, :wdf
+
+    def initialize(docid, doclength, wdf)
+      @docid = docid
+      @doclength = doclength
+      @wdf = wdf
+    end
+
+    def ==(other)
+      return other.is_a?(Xapian::Posting) && other.docid == @docid && other.doclength == @doclength &&
+        other.wdf == @wdf
+    end
+  end # Xapian::Posting
+
+  # Refer to the
+  # {Xapian::Database C++ API documentation}[http://xapian.org/docs/apidoc/html/classXapian_1_1Database.html]
+  # for methods not specific to Ruby.
+  #--
+  # Wrap some dangerous iterators.
+  class Xapian::Database
+    # Returns an Array of all Xapian::Terms for this database.
+    def allterms
+      Xapian._safelyIterate(self._dangerous_allterms_begin(), 
+                            self._dangerous_allterms_end()) { |item|
+        Xapian::Term.new(item.term, 0, item.termfreq)
+      }
+    end # allterms
+
+    # Returns an Array of Xapian::Postings for the given term.
+    # term is a string.
+    def postlist(term)
+      Xapian._safelyIterate(self._dangerous_postlist_begin(term), 
+                            self._dangerous_postlist_end(term)) { |item|
+        Xapian::Posting.new(item.docid, item.doclength, item.wdf)
+      }      
+    end # postlist(term)
+
+    # Returns an Array of Terms for the given docid.
+    def termlist(docid)
+      Xapian._safelyIterate(self._dangerous_termlist_begin(docid),
+                            self._dangerous_termlist_end(docid)) { |item|
+        Xapian::Term.new(item.term, item.wdf, item.termfreq)
+      }
+    end # termlist(docid)
+    
+    # Returns an Array of Xapian::Termpos objects for the given term (a String)
+    # in the given docid.
+    def positionlist(docid, term)
+      Xapian._safelyIterate(self._dangerous_positionlist_begin(docid, term),
+                            self._dangerous_positionlist_end(docid, term)) { |item|
+        item.termpos
+      }
+    end # positionlist
+  end # Xapian::Database
+
+end # Xapian module