tire 0.1.7 → 0.1.8

data/README.markdown

@@ -189,8 +189,69 @@ count for articles tagged 'php' is excluded, since they don't match the current
     # java       1
 ```
 
-If configuring the search payload with a block somehow feels too weak for you, you can simply pass
-a Ruby `Hash` (or JSON string) with the query declaration to the `search` method:
+Notice, that only variables from the enclosing scope are accesible.
+If we want to access the variables or methods from outer scope,
+we have to use a slight variation of the DSL, by passing the
+`search` and `query` objects around.
+
+```ruby
+    @query = 'title:T*'
+
+    Tire.search 'articles' do |search|
+      search.query do |query|
+        query.string @query
+      end
+    end
+```
+
+Quite often, we need complex queries with boolean logic.
+Instead of composing long query strings such as `tags:ruby OR tags:java AND NOT tags:python`,
+we can use the [_bool_](http://www.elasticsearch.org/guide/reference/query-dsl/bool-query.html)
+query. In _Tire_, we build them declaratively.
+
+```ruby
+    Tire.search('articles') do
+      query do
+        boolean do
+          should   { string 'tags:ruby' }
+          should   { string 'tags:java' }
+          must_not { string 'tags:python' }
+        end
+      end
+    end
+```
+
+The best thing about `boolean` queries is that we can easily save these partial queries as Ruby blocks,
+to mix and reuse them later. So, we may define a query for the _tags_ property:
+
+```ruby
+    tags_query = lambda do
+      boolean.should { string 'tags:ruby' }
+      boolean.should { string 'tags:java' }
+    end
+```
+
+And a query for the _published_on_ property:
+
+```ruby
+    published_on_query = lambda do
+      boolean.must   { string 'published_on:[2011-01-01 TO 2011-01-02]' }
+    end
+```
+
+Now, we can combine these queries for different searches:
+
+```ruby
+    Tire.search('articles') do
+      query do
+        boolean &tags_query
+        boolean &published_on_query
+      end
+    end
+```
+
+If configuring the search payload with blocks somehow feels too weak for you, you can pass
+a plain old Ruby `Hash` (or JSON string) with the query declaration to the `search` method:
 
 ```ruby
     Tire.search 'articles', :query => { :fuzzy => { :title => 'Sour' } }

data/Rakefile

@@ -25,11 +25,8 @@ namespace :test do
 end
 
 # Generate documentation
-begin
-  require 'sdoc'
-rescue LoadError
-end
-require 'rake/rdoctask'
+begin; require 'sdoc'; rescue LoadError; end
+require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "Tire"
@@ -58,17 +55,17 @@ namespace :web do
   task :update => :generate do
     current_branch = `git branch --no-color`.split("\n").select { |line| line =~ /^\* / }.to_s.gsub(/\* (.*)/, '\1')
     (puts "Unable to determine current branch"; exit(1) ) unless current_branch
-    system "git stash save && git checkout web"
+    system "git checkout web"
     system "cp examples/tire-dsl.html index.html"
     system "git add index.html && git co -m 'Updated Tire website'"
     system "git push origin web:gh-pages -f"
-    system "git checkout #{current_branch} && git stash pop"
+    system "git checkout #{current_branch}"
   end
 
   desc "Generate the Rocco documentation page"
   task :generate do
     system "rocco examples/tire-dsl.rb"
-    html = File.read('examples/tire-dsl.html').gsub!(/tire\-dsl\.rb/, 'tire.rb')
+    html = File.read('examples/tire-dsl.html').gsub!(/>tire\-dsl\.rb</, '>tire.rb<')
     File.open('examples/tire-dsl.html', 'w') { |f| f.write html }
     system "open examples/tire-dsl.html"
   end

data/examples/tire-dsl.rb

@@ -14,13 +14,13 @@
 
 # Note, that this file can be executed directly:
 #
-#     ruby examples/tire-dsl.rb
+#     ruby -I lib examples/tire-dsl.rb
 #
 
 
 #### Installation
 
-# Install _Tire_ with Rubygems.
+# Install _Tire_ with _Rubygems_:
 
 #
 #     gem install tire
@@ -38,7 +38,7 @@ require 'tire'
 
 #### Prerequisites
 
-# You'll need a working and running _ElasticSearch_ server. Thankfully, that's easy.
+# We'll need a working and running _ElasticSearch_ server, of course. Thankfully, that's easy.
 ( puts <<-"INSTALL" ; exit(1) ) unless (RestClient.get('http://localhost:9200') rescue false)
 
  [ERROR] You don’t appear to have ElasticSearch installed. Please install and launch it with the following commands:
@@ -82,7 +82,6 @@ Tire.index 'articles' do
   create :mappings => {
 
     # Specify for which type of documents this mapping should be used.
-    # (The documents must provide a `type` method or property then.)
     #
     :article => {
       :properties => {
@@ -95,7 +94,7 @@ Tire.index 'articles' do
         # has [more information](http://elasticsearch.org/guide/reference/mapping/index.html)
         # about this. Proper mapping is key to efficient and effective search.
         # But don't fret about getting the mapping right the first time, you won't.
-        # In most cases, the default mapping is just fine for prototyping.
+        # In most cases, the default, dynamic mapping is just fine for prototyping.
         #
         :title    => { :type => 'string', :analyzer => 'snowball', :boost => 2.0             },
         :tags     => { :type => 'string', :analyzer => 'keyword'                             },
@@ -105,13 +104,13 @@ Tire.index 'articles' do
   }
 end
 
-#### Bulk Storage
+#### Bulk Indexing
 
 # Of course, we may have large amounts of data, and adding them to the index one by one really isn't the best idea.
-# We can use _ElasticSearch's_ [bulk storage](http://www.elasticsearch.org/guide/reference/api/bulk.html)
+# We can use _ElasticSearch's_ [bulk API](http://www.elasticsearch.org/guide/reference/api/bulk.html)
 # for importing the data.
 
-# So, for demonstration purposes, let's suppose we have a plain collection of hashes to store.
+# So, for demonstration purposes, let's suppose we have a simple collection of hashes to store.
 #
 articles = [
 
@@ -134,7 +133,7 @@ end
 Tire.index 'articles' do
   delete
 
-  # ... by just passing a block to the `import` method. The collection will
+  # ... by passing a block to the `import` method. The collection will
   # be available in the block argument.
   #
   import articles do |documents|
@@ -152,8 +151,7 @@ end
 
 # With the documents indexed and stored in the _ElasticSearch_ database, we can search them, finally.
 #
-# Tire exposes the search interface via simple domain-specific language.
-
+# _Tire_ exposes the search interface via simple domain-specific language.
 
 #### Simple Query String Searches
 
@@ -161,7 +159,7 @@ end
 #
 s = Tire.search('articles') do
   query do
-    string "title:One"
+    string "title:one"
   end
 end
 
@@ -189,12 +187,14 @@ s.results.each do |document|
   puts "* #{ document.title } [published: #{document.published_on}]"
 end
 
-# Of course, we may write the blocks in shorter notation.
-# Local variables from outer scope are passed down the chain.
+# Notice, that we can access local variables from the _enclosing scope_.
+# (Of course, we may write the blocks in shorter notation.)
 
-# Let's search for articles whose titles begin with letter “T”.
+# We will define the query in a local variable named `q`...
 #
 q = "title:T*"
+# ... and we can use it inside the `query` block.
+#
 s = Tire.search('articles') { query { string q } }
 
 # The results:
@@ -205,17 +205,50 @@ s.results.each do |document|
   puts "* #{ document.title } [tags: #{document.tags.join(', ')}]"
 end
 
-# In fact, we can use any valid [Lucene query syntax](http://lucene.apache.org/java/3_0_3/queryparsersyntax.html)
-# for the query string queries.
+# Often, we need to access variables or methods defined in the _outer scope_.
+# To do that, we have to use a slight variation of the DSL.
+#
+
+# Let's assume we have a plain Article class.
+#
+class Article
+
+  # We will define the query in a class method...
+  #
+  def self.q
+    "title:T*"
+  end
+
+  # ... and wrap the _Tire_ search method.
+  def self.search
+
+    # Notice how we pass the `search` object around as a block argument.
+    #
+    Tire.search('articles') do |search|
+
+      # And we pass the query object in a similar matter.
+      #
+      search.query do |query|
+
+        # Which means we can access the `q` class method.
+        #
+        query.string self.q
+      end
+    end.results
+  end
+end
+
+# We may use any valid [Lucene query syntax](http://lucene.apache.org/java/3_0_3/queryparsersyntax.html)
+# for the `query_string` queries.
 
-# For debugging, we can display the JSON which is being sent to _ElasticSearch_.
+# For debugging our queries, we can display the JSON which is being sent to _ElasticSearch_.
 #
 #     {"query":{"query_string":{"query":"title:T*"}}}
 #
 puts "", "Query:", "-"*80
 puts s.to_json
 
-# Or better, we may display a complete `curl` command to recreate the request in terminal,
+# Or better yet, we may display a complete `curl` command to recreate the request in terminal,
 # so we can see the naked response, tweak request parameters and meditate on problems.
 #
 #     curl -X POST "http://localhost:9200/articles/_search?pretty=true" \
@@ -279,8 +312,6 @@ end
 
 ### Complex Searching
 
-#### Other Types of Queries
-
 # Query strings are convenient for simple searches, but we may want to define our queries more expressively,
 # using the _ElasticSearch_ [Query DSL](http://www.elasticsearch.org/guide/reference/query-dsl/index.html).
 #
@@ -326,6 +357,71 @@ s.results.each do |document|
   puts "* #{ document.title } [tags: #{document.tags.join(', ')}]"
 end
 
+#### Boolean Queries
+
+# Quite often, we need complex queries with boolean logic.
+# Instead of composing long query strings such as `tags:ruby OR tags:java AND NOT tags:python`,
+# we can use the [_bool_](http://www.elasticsearch.org/guide/reference/query-dsl/bool-query.html)
+# query.
+
+s = Tire.search('articles') do
+  query do
+
+    # In _Tire_, we can build `bool` queries declaratively, as usual.
+    boolean do
+
+      # Let's define a `should` (`OR`) query for _ruby_,
+      #
+      should   { string 'tags:ruby' }
+
+      # as well as for _java_,
+      should   { string 'tags:java' }
+
+      # while defining a `must_not` (`AND NOT`) query for _python_.
+      must_not { string 'tags:python' }
+    end
+  end
+end
+
+# The search returns these documents:
+#
+#     * One [tags: ruby]
+#     * Three [tags: java]
+#     * Four [tags: ruby, php]
+#
+s.results.each do |document|
+  puts "* #{ document.title } [tags: #{document.tags.join(', ')}]"
+end
+
+# The best thing about `boolean` queries is that we can very easily save these partial queries as Ruby blocks,
+# to mix and reuse them later, since we can call the `boolean` method multiple times.
+#
+
+# Let's define the query for the _tags_ property,
+#
+tags_query = lambda do |boolean|
+  boolean.should { string 'tags:ruby' }
+  boolean.should { string 'tags:java' }
+end
+
+# ... and a query for the _published_on_ property.
+published_on_query = lambda do |boolean|
+  boolean.must   { string 'published_on:[2011-01-01 TO 2011-01-02]' }
+end
+
+# Now, we can use the `tags_query` on its own.
+#
+Tire.search('articles') { query { boolean &tags_query } }
+
+# Or, we can combine it with the `published_on` query.
+#
+Tire.search('articles') do
+  query do
+    boolean &tags_query
+    boolean &published_on_query
+  end
+end
+
 # _ElasticSearch_ supports many types of [queries](http://www.elasticsearch.org/guide/reference/query-dsl/).
 #
 # Eventually, _Tire_ will support all of them. So far, only these are supported:
@@ -333,6 +429,7 @@ end
 # * [string](http://www.elasticsearch.org/guide/reference/query-dsl/query-string-query.html)
 # * [term](http://elasticsearch.org/guide/reference/query-dsl/term-query.html)
 # * [terms](http://elasticsearch.org/guide/reference/query-dsl/terms-query.html)
+# * [bool](http://www.elasticsearch.org/guide/reference/query-dsl/bool-query.html)
 # * [all](http://www.elasticsearch.org/guide/reference/query-dsl/match-all-query.html)
 # * [ids](http://www.elasticsearch.org/guide/reference/query-dsl/ids-query.html)
 

data/lib/tire/search.rb

@@ -9,10 +9,9 @@ module Tire
         @options = indices.last.is_a?(Hash) ? indices.pop  : {}
         @indices = indices
         raise ArgumentError, 'Please pass index or indices to search' if @indices.empty?
-        if @options
-          Configuration.wrapper @options[:wrapper] if @options[:wrapper]
-        end
-        instance_eval(&block) if block_given?
+
+        Configuration.wrapper @options[:wrapper] if @options[:wrapper]
+        block.arity < 1 ? instance_eval(&block) : block.call(self) if block_given?
       end
 
       def query(&block)

data/lib/tire/search/query.rb

@@ -25,9 +25,6 @@ module Tire
       end
 
       def boolean(options={}, &block)
-        # TODO: Try to get rid of the `boolean` method
-        raise ArgumentError, "Please pass a block to boolean query" unless block_given?
-
         @boolean ||= BooleanQuery.new(options)
         block.arity < 1 ? @boolean.instance_eval(&block) : block.call(@boolean) if block_given?
         @value[:bool] = @boolean.to_hash

data/lib/tire/version.rb

@@ -1,3 +1,3 @@
 module Tire
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

data/test/unit/search_query_test.rb

@@ -67,8 +67,8 @@ module Tire::Search
 
     context "BooleanQuery" do
 
-      should "raise ArgumentError when no block given" do
-        assert_raise(ArgumentError) { Query.new.boolean }
+      should "not raise an error when no block is given" do
+        assert_nothing_raised { Query.new.boolean }
       end
 
       should "encode options" do

data/test/unit/search_test.rb

@@ -11,22 +11,24 @@ module Tire
         assert_raise(ArgumentError) { Search::Search.new }
       end
 
-      should "have the query method" do
-        assert_respond_to Search::Search.new('index'), :query
-      end
-
       should "allow to pass block to query" do
         Search::Query.any_instance.expects(:instance_eval)
 
-        Search::Search.new('index').query { string 'foo' }
+        Search::Search.new('index') do
+          query { string 'foo' }
+        end
       end
 
-      should "allow to pass block with argument to query, allowing to use local variables from outer scope" do
-        foo = 'bar'
-        query_block = lambda { |query| query.string foo }
+      should "allow to pass block with argument to query (use variables from outer scope)" do
+        def foo; 'bar'; end
+
         Search::Query.any_instance.expects(:instance_eval).never
 
-        Search::Search.new('index').query &query_block
+        Search::Search.new('index') do |search|
+          search.query do |query|
+            query.string foo
+          end
+        end
       end
 
       should "store indices as an array" do
@@ -253,27 +255,6 @@ module Tire
           assert_equal( { 'terms' => { 'tags' => ['baz'] } }, query['must'].last)
         end
 
-        should "allow passing variables from outer scope" do
-          q1 = 'foo'
-          q2 = 'bar'
-
-          assert_nothing_raised do
-            @search = Search::Search.new('index') do
-              query do
-                boolean do
-                  must   { string q1 }
-                  must   { string q2 }
-                end
-              end
-            end
-          end
-
-          hash  = MultiJson.decode(@search.to_json)
-          query = hash['query']['bool']
-
-          assert_equal 2, query['must'].size
-        end
-
       end
 
     end

data/tire.gemspec

@@ -25,15 +25,16 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.6"
 
   s.add_dependency "rake",        ">= 0.8.0"
-  s.add_dependency "bundler",     "~> 1.0.0"
   s.add_dependency "rest-client", "~> 1.6.0"
   s.add_dependency "multi_json",  "~> 1.0"
   s.add_dependency "activemodel", "~> 3.0"
 
+  s.add_development_dependency "bundler",     "~> 1.0.0"
   s.add_development_dependency "yajl-ruby",   "~> 0.8.0"
   s.add_development_dependency "turn"
   s.add_development_dependency "shoulda"
   s.add_development_dependency "mocha"
+  s.add_development_dependency "rdoc"
   s.add_development_dependency "sdoc"
   s.add_development_dependency "rcov"
   s.add_development_dependency "activerecord", "~> 3.0.7"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: tire
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 11
   prerelease: 
   segments: 
   - 0
   - 1
-  - 7
-  version: 0.1.7
+  - 8
+  version: 0.1.8
 platform: ruby
 authors: 
 - Karel Minarik
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-07 00:00:00 +02:00
+date: 2011-06-08 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,23 +35,23 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: bundler
+  name: rest-client
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 23
+        hash: 15
         segments: 
         - 1
+        - 6
         - 0
-        - 0
-        version: 1.0.0
+        version: 1.6.0
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rest-client
+  name: multi_json
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
@@ -61,40 +61,40 @@ dependencies:
         hash: 15
         segments: 
         - 1
-        - 6
         - 0
-        version: 1.6.0
+        version: "1.0"
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: multi_json
+  name: activemodel
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 15
+        hash: 7
         segments: 
-        - 1
+        - 3
         - 0
-        version: "1.0"
+        version: "3.0"
   type: :runtime
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
-  name: activemodel
+  name: bundler
   prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 7
+        hash: 23
         segments: 
-        - 3
+        - 1
         - 0
-        version: "3.0"
-  type: :runtime
+        - 0
+        version: 1.0.0
+  type: :development
   version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: yajl-ruby
@@ -155,7 +155,7 @@ dependencies:
   type: :development
   version_requirements: *id009
 - !ruby/object:Gem::Dependency 
-  name: sdoc
+  name: rdoc
   prerelease: false
   requirement: &id010 !ruby/object:Gem::Requirement 
     none: false
@@ -169,7 +169,7 @@ dependencies:
   type: :development
   version_requirements: *id010
 - !ruby/object:Gem::Dependency 
-  name: rcov
+  name: sdoc
   prerelease: false
   requirement: &id011 !ruby/object:Gem::Requirement 
     none: false
@@ -183,9 +183,23 @@ dependencies:
   type: :development
   version_requirements: *id011
 - !ruby/object:Gem::Dependency 
-  name: activerecord
+  name: rcov
   prerelease: false
   requirement: &id012 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id012
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id013 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -197,11 +211,11 @@ dependencies:
         - 7
         version: 3.0.7
   type: :development
-  version_requirements: *id012
+  version_requirements: *id013
 - !ruby/object:Gem::Dependency 
   name: supermodel
   prerelease: false
-  requirement: &id013 !ruby/object:Gem::Requirement 
+  requirement: &id014 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -211,11 +225,11 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id013
+  version_requirements: *id014
 - !ruby/object:Gem::Dependency 
   name: sqlite3
   prerelease: false
-  requirement: &id014 !ruby/object:Gem::Requirement 
+  requirement: &id015 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -225,7 +239,7 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id014
+  version_requirements: *id015
 description: "   Tire is a Ruby client for the ElasticSearch search engine/database.\n\n   It provides Ruby-like API for fluent communication with the ElasticSearch server\n   and blends with ActiveModel class for convenient usage in Rails applications.\n\n   It allows to delete and create indices, define mapping for them, supports\n   the bulk API, and presents an easy-to-use DSL for constructing your queries.\n\n   It has full ActiveRecord/ActiveModel compatibility, allowing you to index\n   your models (incrementally upon saving, or in bulk), searching and\n   paginating the results.\n"
 email: karmi@karmi.cz
 executables: []