couchrest_model_search 0.0.4 → 0.0.5

data/.rvmrc

@@ -1 +1 @@
-rvm 1.8.7@couchrest_model_search --create
+rvm default@couchrest_model_search --create

data/CHANGELOG

@@ -1,3 +1,6 @@
+v0.0.5
+  -- new feature: `escaped_search` (see README)
+
 v0.0.4
 
   -- bug fix: don't update the design doc unless you absolutely have to.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    couchrest_model_search (0.0.3)
+    couchrest_model_search (0.0.4)
       couchrest_model (~> 1.0.0)
 
 GEM
@@ -60,7 +60,7 @@ GEM
       rake (>= 0.8.7)
       thor (~> 0.14.4)
     rake (0.9.2)
-    rest-client (1.6.3)
+    rest-client (1.6.7)
       mime-types (>= 1.16)
     rspec (2.6.0)
       rspec-core (~> 2.6.0)

data/README.markdown

@@ -8,17 +8,99 @@ Search integration for `couchrest_model` users that are using couchdb-lucene.
   
 ## Usage
 
+By simply requiring 'couchrest_model_search' in your project, all of your `CouchRest::Model::Base` models will respond to a `search` class method. This method will, by default, perform a full-text search on your model for any query you pass to it. 
+
+For example, suppose we have defined the following model:
+
+    class Article < CouchRest::Model::Base
+      property :title
+      property :author
+      property :body
+    end
+
+And now, let's create some articles:
+
+    Article.create(
+      :title => "CouchDB is fun!", 
+      :author => "moonmaster9000", 
+      :body => "CouchDB is the most fun EVAR."
+    )
+
+    Article.create(
+      :title => "CouchDB Lucene FTW", 
+      :author => "moonmaster9000", 
+      :body => "CouchDB Lucene makes your documents easily searchable!"
+    )
+
+    Article.create(
+      :title => "Search your CouchDB documents from Ruby", 
+      :author => "dorren", 
+      :body => "Use the couchrest_model_search gem to search your documents from Ruby."
+    )
+
+If we searched for "CouchDB", we would receive all documents we've created, since they all contained the word "CouchDB" in one of the properties:
+
+    Article.search("CouchDB").map(&:title) 
+      #==> ["CouchDB is fun!", "CouchDB Lucene FTW", "Search your CouchDB documents from Ruby"]
+
+Of course, searching for "moonmaster9000" would only return the first two documents:
+
+    Article.search("moonmaster9000").map(&:title) 
+      #==> ["CouchDB is fun!", "CouchDB Lucene FTW"]
+
+
+### Creating more search functions
+
+By default, the `search` method will use an underlying fulltext search index function to query your content. You can override the definition of this default "fulltext" search index function via the `search_by` class method:
+
     class Article < CouchRest::Model::Base
+      property :title
+      property :author
+      property :body
+
+      search_by :fulltext, 
+        :index => %(
+          function(doc){
+            //... your code here
+          }
+        )
     end
 
-    @articles = Article.search "apple"  # search by keyword apple
-    
-    # you can also customize the search function.
-    class CustomArticle < CouchRest::Model::Base
-      search_by :fulltext,
-                :index => %(
-                   function(doc) {
-                     // ....
-                   }
-                )
+You can also create other search indexes. For example, suppose we'd like to index only the titles of articles for search:
+
+
+    class Article < CouchRest::Model::Base
+      property :title
+      property :author
+      property :body
+
+      search_by :title, 
+        :index => %(
+          function(doc){
+            var contentToIndex = new Document();
+            contentToIndex.add(doc.title);
+            return contentToIndex;
+          }
+        )
     end
+
+Now, to perform a search by title (instead of a fulltext search), simply pass `:by_title` along with your query to the `search` method:
+
+    Article.search "some query", :by_title
+
+### CouchDB-Lucene Query options
+
+You can pass any CouchDB-Lucene query options to your search via an optional third parameter to search:
+
+    Article.search "apples", :fulltext, :limit => 10
+
+
+### Escaping special characters
+
+The following characters have special meaning to Lucene when added to a query:
+
+    + - && || ! ( ) { } [ ] ^ " ~ * ? : \
+
+By default, `couchrest_model_search` will not escape your query. If you want it to automatically escape these special characters in your query, then use the `escaped_search` method:
+
+    Article.escaped_search "2001:March:10"

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.5

data/lib/couchrest_model_search.rb

@@ -82,6 +82,15 @@ class CouchRest::Model::Base
     ret = self.database.search(self.to_s, view_fn, query, options)
     ret['rows'].map {|r| self.new(r['doc'])}
   end
+
+  def self.escaped_search(query, view_fn="by_fulltext", options={})
+    self.lucene_special_characters.map {|c| query.gsub!(c, %{\\} + c)}
+    self.search query, view_fn, options
+  end
+
+  def self.lucene_special_characters
+    @lucene_special_characters ||= %w[\ + - && || ! ( ) { } [ ] ^ " ~ * ? :]
+  end
   
   # example search functions
   #   class Aritlce

data/spec/couchrest_model_search_spec.rb

@@ -16,6 +16,13 @@ describe "CouchrestModelSearch" do
     Article.design_doc["fulltext"].should_not be_nil
   end  
 end
+
+describe "##escaped_search" do
+  it "should escape the first parameter, then pass all args off to the search method" do
+    Article.should_receive(:search).with('hello\:there', "by_fulltext", {}).and_return nil
+    Article.escaped_search "hello:there"
+  end
+end
   
 describe "overwrite design doc" do  
   class CustomArticle < CouchRest::Model::Base

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: couchrest_model_search
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 0
   - 0
-  - 4
-  version: 0.0.4
+  - 5
+  version: 0.0.5
 platform: ruby
 authors: 
 - Dorren Chen
@@ -16,8 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-18 00:00:00 -04:00
-default_executable: 
+date: 2010-10-18 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: couchrest_model
@@ -88,7 +87,6 @@ files:
 - lib/couchrest_model_search.rb
 - spec/couchrest_model_search_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
 homepage: http://github.com/dorren/couchrest_model_search
 licenses: []
 
@@ -118,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Add couchdb-lucene search support to CouchRest Model