xapian_db 0.3.1 → 0.3.2

data/lib/xapian_db/resultset.rb

@@ -1,51 +1,62 @@
 # encoding: utf-8
 
-# The resultset holds a Xapian::Query object and allows paged access
-# to the found documents.
-# author Gernot Kogler
-
 module XapianDb
-  
+
+  # The resultset encapsulates a Xapian::Query object and allows paged access
+  # to the found documents.
+  # @example Process the first page of a resultsest
+  #   resultset.paginate(:page => 1, :per_page => 10).each do |doc|
+  #     # do something with the xapian document
+  #   end
+  # @author Gernot Kogler
   class Resultset
-    
+
+    # The number of documents found
+    # @return [Integer]
     attr_reader :size
-    
+
     # Constructor
-    # @param [Xapian::Enquire] a Xapian query result
-    def initialize(enquiry)
+    # @param [Xapian::Enquire] enquiry a Xapian query result (see http://xapian.org/docs/apidoc/html/classXapian_1_1Enquire.html)
+    # @param [Hash] options
+    # @option options [Integer] :per_page (10) How many docs per page?
+    def initialize(enquiry, options)
       @enquiry = enquiry
       # By passing 0 as the max parameter to the mset method,
       # we only get statistics about the query, no results
-      @size = enquiry.mset(0, 0).matches_estimated
+      @size     = enquiry.mset(0, 0).matches_estimated
+      @per_page = options[:per_page]
     end
 
     # Paginate the result
+    # @param [Hash] opts Options for the persistent database
+    # @option opts [Integer] :page (1) The page to access
     def paginate(opts={})
-      options = {:page => 1, :per_page => 10}.merge(opts)
-      offset = (options[:page] - 1) * options[:per_page]
-      return [] if offset > @size
-      build_page(offset, options[:per_page])
+      options = {:page => 1}.merge(opts)
+      build_page(options[:page])
     end
-    
+
     private
-    
+
     # Build a page of Xapian documents
-    def build_page(offset, count)
+    # @return [Array<Xapian::Document>] An array of xapian documents
+    def build_page(page)
       docs = []
-      result_window = @enquiry.mset(offset, count)
+      offset = (page - 1) * @per_page
+      return [] if offset > @size
+      result_window = @enquiry.mset(offset, @per_page)
       result_window.matches.each do |match|
         docs << decorate(match.document)
       end
       docs
     end
-    
-    # Decorate a Xapian document with field accessors
+
+    # Decorate a Xapian document with field accessors for each configured attribute
     def decorate(document)
       klass_name = document.values[0].value
       blueprint  = XapianDb::DocumentBlueprint.blueprint_for(Kernel.const_get(klass_name))
       document.extend blueprint.accessors_module
     end
-              
+
   end
-  
+
 end

data/lib/xapian_db.rb

@@ -1,45 +1,64 @@
+# encoding: utf-8
+
 require 'digest/sha1'
-require 'rubygems'
 require 'xapian'
 require 'yaml'
-require 'progressbar'
+
+# This is the top level module of xapian_db. It allows you to
+# configure XapianDB, create / open databases and perform
+# searches.
+
+# @author Gernot Kogler
 
 module XapianDb
 
-  # Configure XapianDb
+  # Global configuration for XapianDb. See {XapianDb::Config.setup}
+  # for available options
   def self.setup(&block)
     XapianDb::Config.setup(&block)
   end
-  
-  # Create a database. Overwrites an existing database on disk, if
-  # option :in_memory is set to false.
+
+  # Create a database
+  # @param [Hash] options
+  # @option options [String] :path A path to the file system. If no path is
+  #   given, creates an in memory database. <b>Overwrites an existing database!</b>
+  # @return [XapianDb::Database]
   def self.create_db(options = {})
-    if options[:path] 
-      PersistentDatabase.new(:path => options[:path], :create => true) 
+    if options[:path]
+      PersistentDatabase.new(:path => options[:path], :create => true)
     else
       InMemoryDatabase.new
     end
   end
 
-  # Open a database.
+  # Open a database
+  # @param [Hash] options
+  # @option options [String] :path A path to the file system. If no path is
+  #   given, creates an in memory database. If a path is given, then database
+  #   must exist.
+  # @return [XapianDb::Database]
   def self.open_db(options = {})
-    if options[:path] 
-      PersistentDatabase.new(:path => options[:path], :create => false) 
+    if options[:path]
+      PersistentDatabase.new(:path => options[:path], :create => false)
     else
       InMemoryDatabase.new
     end
   end
-  
-  # Access he configured database
+
+  # Access the configured database. See {XapianDb::Config.setup}
+  # for instructions on how to configure a database
+  # @return [XapianDb::Database]
   def self.database
     XapianDb::Config.database
   end
-  
-  # Query the database
+
+  # Query the configured database.
+  # See {XapianDb::Database#search} for options
+  # @return [XapianDb::Resultset]
   def self.search(expression)
     XapianDb::Config.database.search(expression)
   end
-  
+
 end
 
 require File.dirname(__FILE__) + '/xapian_db/config'

metadata

@@ -5,20 +5,20 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 1
-  version: 0.3.1
+  - 2
+  version: 0.3.2
 platform: ruby
 authors: 
-- Gernot kogler
+- Gernot Kogler
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-12-06 00:00:00 +01:00
+date: 2010-12-10 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: progressbar
+  name: rspec
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -26,35 +26,51 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version 
         segments: 
+        - 2
+        - 1
         - 0
-        - 9
-        - 0
-        version: 0.9.0
-  type: :runtime
+        version: 2.1.0
+  type: :development
   version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: simplecov
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 3
+        - 2
+        version: 0.3.2
+  type: :development
+  version_requirements: *id002
 description: Ruby library to use a Xapian db as a key/value store with high performance fulltext search
 email: gernot.kogler (at) garaio (dot) com
 executables: []
 
 extensions: []
 
-extra_rdoc_files: 
-- CHANGELOG
+extra_rdoc_files: []
+
 files: 
-- CHANGELOG
-- lib/xapian_db.rb
-- lib/xapian_db/railtie.rb
+- lib/xapian_db/adapters/active_record_adapter.rb
+- lib/xapian_db/adapters/datamapper_adapter.rb
+- lib/xapian_db/adapters/generic_adapter.rb
 - lib/xapian_db/config.rb
-- lib/xapian_db/index_writers/direct_writer.rb
 - lib/xapian_db/database.rb
 - lib/xapian_db/document_blueprint.rb
+- lib/xapian_db/index_writers/direct_writer.rb
 - lib/xapian_db/indexer.rb
-- lib/xapian_db/adapters/generic_adapter.rb
-- lib/xapian_db/adapters/datamapper_adapter.rb
-- lib/xapian_db/adapters/active_record_adapter.rb
 - lib/xapian_db/query_parser.rb
+- lib/xapian_db/railtie.rb
 - lib/xapian_db/resultset.rb
-- examples/basic.rb
+- lib/xapian_db.rb
+- LICENSE
+- README.rdoc
+- CHANGELOG.md
 has_rdoc: true
 homepage: https://github.com/garaio/xapian_db
 licenses: []
@@ -84,8 +100,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version 
       segments: 
       - 1
-      - 2
-      version: "1.2"
+      - 3
+      - 6
+      version: 1.3.6
 requirements: []
 
 rubyforge_project: 

data/CHANGELOG

@@ -1,15 +0,0 @@
-*0.1.0* (November 23th, 2010)
-
-* Proof of concept, not really useful for real world usage
-
-*0.2.0* (December 1st, 2010)
-
-* Blueprint configuration extended
-* Adapter for Datamapper
-* Search by attribute names
-* Search with wildcards
-* Document attributes can carry anything that is serializable by YAML
-
-*0.3.0* (December 4st, 2010)
-
-* Rails integration with configuration file (config/xapian_db.yml) and automatic setup

data/examples/basic.rb

@@ -1,59 +0,0 @@
-# encoding: utf-8
-
-# This example shows the most basic way to use xapian_db
-# To run the example, please install the xapian_db gem first
-
-require 'rubygems'
-require 'xapian_db'
-
-puts "Setting up the demo..."
-
-# 1: Open an in memory database
-db = XapianDb.create_db
-
-# 2: Define a class which should get indexed; we define a class that
-# could be an ActiveRecord or Datamapper Domain class
-class People
-  
-  attr_accessor :id, :name, :first_name
-  
-  def initialize(data)
-    @id, @name, @first_name = data[:id], data[:name], data[:first_name]
-  end
-  
-end
-
-# 3: Configure the generic adapter with a unique key expression
-XapianDb::Adapters::GenericAdapter.unique_key do
-  "#{self.class}-#{self.id}"
-end
-
-# 4: Define a document blueprint for our class; the blueprint describes
-# the structure of all documents for our class. Attribute values can
-# be accessed later for each retrieved doc. Attributes are indexed
-# by default.
-XapianDb::DocumentBlueprint.setup(People) do |blueprint|
-  blueprint.attribute :name
-  blueprint.attribute :first_name
-end
-
-# 5: Let's create some objects
-person_1 = People.new(:id => 1, :name => "Kogler", :first_name => "Gernot")
-person_2 = People.new(:id => 2, :name => "Frey",   :first_name => "Daniel")
-person_3 = People.new(:id => 3, :name => "Garaio", :first_name => "Thomas")
-
-# 6: Now add them to the database
-blueprint = XapianDb::DocumentBlueprint.blueprint_for(People)
-db.store_doc(blueprint.indexer.build_document_for(person_1))
-db.store_doc(blueprint.indexer.build_document_for(person_2))
-db.store_doc(blueprint.indexer.build_document_for(person_3))
-
-# 7: Now find the gem author ;-)
-puts "Searching for Gernot..."
-results = db.search("Gernot")
-puts "We found #{results.size} documents"
-puts "And the first document looks like this:"
-page = results.paginate(:page => 1)
-doc  = page.first
-puts "name: #{doc.name}"
-puts "first name: #{doc.first_name}"