daedal 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 591b82d1a7aec22b940c410fd2d5afe79877e24f
-  data.tar.gz: 16e8916ccff2aef76cc75f1052085ffe3d08527f
+  metadata.gz: c847bcafde8c2364dd1105418bf51ddb0f6ecd42
+  data.tar.gz: 4abb328be7b9473dec47854db2e1207cce6589e9
 SHA512:
-  metadata.gz: f0a6a7d9a161c54625c7dffd3ed1040ba7aee46e13b960ce5caaf56b0be2afa24bfb4dbd5ab9f6b2f2d0a81ee58fa51d4db03c1f4fe324644360dfc930dca525
-  data.tar.gz: e4bc1ce204ce207255e1ebd1c5c1311fd80744fcd323cd737fce6e5fd2ffeb7d1150700d881124576d11fb738e1056a8d16835dbd34b00548429acd432e46527
+  metadata.gz: 50cd4b1ab8720509f8b38a7968b2e1f3258d75c7fd79a3771ddf12390210e1d13d0afcbf72fe961d12d75eba477e719922e53cc17feca06fe6a94b51200d89b6
+  data.tar.gz: cab1fa56a98d7f0c3380d57af1e0a96c027235080a19ad3db38818127f610103633fb91e61169ff63ccc24c9fc1a53c406dcf96f31a11a9101872d3e6e3599d2

data/.gitignore

@@ -11,4 +11,11 @@
 # Ignore all logfiles and tempfiles.
 /log/*.log
 /tmp
-*.swp
+*.swp
+
+# Ignore coverage stuff
+/coverage
+/.coveralls.yml
+
+# Ignore gem builds
+*.gem

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+    - 2.0.0
+notifications:
+    email:
+        - cas13091@gmail.com
+script: "bundle exec rspec"

data/Gemfile

@@ -1,9 +1,11 @@
 source 'https://rubygems.org'
 
-gem 'rspec'
-gem 'guard'
-gem 'guard-rspec'
-gem 'require_all'
-gem 'fuubar'
-gem 'debugger'
-gem 'virtus', '>= 1.0.0'
+gemspec
+
+group :development, :test do
+  gem 'rspec'
+  gem 'coveralls'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'fuubar'
+end

data/Gemfile.lock

@@ -1,3 +1,9 @@
+PATH
+  remote: .
+  specs:
+    daedal (0.0.4)
+      virtus (>= 1.0.0)
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -5,64 +11,74 @@ GEM
       descendants_tracker (~> 0.0.1)
       ice_nine (~> 0.9)
     backports (3.3.5)
-    coderay (1.0.9)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    coderay (1.1.0)
     coercible (0.2.0)
       backports (~> 3.0, >= 3.1.0)
       descendants_tracker (~> 0.0.1)
-    columnize (0.3.6)
-    debugger (1.6.2)
-      columnize (>= 0.3.1)
-      debugger-linecache (~> 1.2.0)
-      debugger-ruby_core_source (~> 1.2.3)
-    debugger-linecache (1.2.0)
-    debugger-ruby_core_source (1.2.3)
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
     descendants_tracker (0.0.3)
-    diff-lcs (1.2.4)
+    diff-lcs (1.2.5)
     equalizer (0.0.8)
-    ffi (1.9.0)
+    ffi (1.9.3)
     formatador (0.2.4)
     fuubar (1.2.1)
       rspec (~> 2.0)
       rspec-instafail (~> 0.2.0)
       ruby-progressbar (~> 1.0)
-    guard (1.8.3)
+    guard (2.2.4)
       formatador (>= 0.2.4)
-      listen (~> 1.3)
-      lumberjack (>= 1.0.2)
-      pry (>= 0.9.10)
-      thor (>= 0.14.6)
-    guard-rspec (3.0.2)
-      guard (>= 1.8)
-      rspec (~> 2.13)
+      listen (~> 2.1)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    guard-rspec (4.2.0)
+      guard (>= 2.1.1)
+      rspec (>= 2.14, < 4.0)
     ice_nine (0.10.0)
-    listen (1.3.1)
+    listen (2.4.0)
+      celluloid (>= 0.15.2)
       rb-fsevent (>= 0.9.3)
       rb-inotify (>= 0.9)
-      rb-kqueue (>= 0.2)
     lumberjack (1.0.4)
     method_source (0.8.2)
-    pry (0.9.12.2)
-      coderay (~> 1.0.5)
+    mime-types (2.0)
+    multi_json (1.8.2)
+    pry (0.9.12.4)
+      coderay (~> 1.0)
       method_source (~> 0.8)
       slop (~> 3.4)
     rb-fsevent (0.9.3)
     rb-inotify (0.9.2)
       ffi (>= 0.5.0)
-    rb-kqueue (0.2.0)
-      ffi (>= 0.5.0)
-    require_all (1.3.1)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
     rspec (2.14.1)
       rspec-core (~> 2.14.0)
       rspec-expectations (~> 2.14.0)
       rspec-mocks (~> 2.14.0)
-    rspec-core (2.14.5)
-    rspec-expectations (2.14.2)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-instafail (0.2.4)
-    rspec-mocks (2.14.3)
+    rspec-mocks (2.14.4)
     ruby-progressbar (1.2.0)
-    slop (3.4.6)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    slop (3.4.7)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
     thor (0.18.1)
+    timers (1.1.0)
+    tins (0.13.1)
     virtus (1.0.0)
       axiom-types (~> 0.0.5)
       coercible (~> 0.2)
@@ -73,10 +89,9 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  debugger
+  coveralls
+  daedal!
   fuubar
   guard
   guard-rspec
-  require_all
   rspec
-  virtus (>= 1.0.0)

data/README.md

@@ -1,79 +1,109 @@
 Daedal
 ======
+[![Build Status](https://travis-ci.org/cschuch/daedal.png?branch=master)](https://travis-ci.org/cschuch/daedal)
+[![Coverage Status](https://coveralls.io/repos/cschuch/daedal/badge.png)](https://coveralls.io/r/cschuch/daedal)
+[![Gem Version](https://badge.fury.io/rb/daedal.png)](http://badge.fury.io/rb/daedal)
 
 This repository contains a set of Ruby classes designed to make ElasticSearch
-query creation simpler and easier to debug. The goal is to reproduce all
-components of the ElasticSearch [Query DSL](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html)
-to aid in the construction of complex queries. Type checking and attribute
+query creation simpler and easier to debug. Type checking and attribute
 coercion are handled using [Virtus](https://github.com/solnic/virtus) to make
 it harder to construct invalid ElasticSearch queries before sending them to the server.
 
-The ElasticSearch Query DSL is huge! There are also a ton of different options within each
-component. My goal is to include as much of that functionality and flexibility as possible, but
-also maintain as high of test coverage as possible. That means it'll take some time for this project
-to reach full coverage of the Query DSL, so please feel free to contribute or be patient :)
+The ElasticSearch [Query DSL](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html)
+has a tremendous amount of flexibility, allowing users to finely tune their search results.
+However, elaborate queries often take the form of a complex, deeply nested hash,
+which can become difficult to create or traverse. By wrapping the core components of the
+query DSL into Ruby objects, Daedal addresses the following issues:
+
+* Constructing a large nested hash can be a headache, and using tools like `Hashie` may result in performance issues
+* Remembering all the optional parameters each query can take, where they reside within the query structure, and what values they can take can be challenging
+* Improperly structured queries, or queries with bad parameters, are hard to catch before sending to the server (and receiving an error)
+* Debugging invalid queries can be a grueling task
+
+Daedal also makes it easy to define custom queries tailored to your specific use case - you can see
+a simple example at the end of the documentation.
 
 Installation
 ------------
 
+From the terminal:
 ``` terminal
 $ gem install daedal
 ```
 
-or in your `Gemfile`
+or in your `Gemfile`:
 
 ``` ruby
 gem 'daedal'
 ```
 
+Then, it's as simple as including the line:
+
+``` ruby
+require 'daedal'
+```
+
 Usage
 --------
 
+See the [Daedal Wiki](https://github.com/cschuch/daedal/wiki) for some examples.
+
 ### ElasticSearch Query DSL
 
 Other Ruby packages for ElasticSearch allow you to create queries either as
 hashes or by constructing raw JSON:
 
 ``` ruby
-match_query = {'match' => {'foo' => {'query' => 'bar'}}}
+author_query = {'match' => {'author' => {'query' => 'Beckett'}}}
 ```
 
-For more complicated queries, dealing with the resulting large nested hash can be
-frustrating. Inspired by ElasticSearch's built in 
+For simple queries like the example above, this works just fine. However, as queries become
+more complicated, the hash can quickly take on a life of its own. Inspired by ElasticSearch's
 [Java API](http://www.elasticsearch.org/guide/en/elasticsearch/client/java-api/current/),
-Daedal contains Ruby classes designed to make query construction more Ruby-like.
+Daedal contains Ruby classes designed to make query construction more manageable.
 
 ### Queries
 
-Queries are contained within the `Queries` module. You can construct query components like:
+Queries are contained within the `Daedal::Queries` module. You can construct query components like:
 
 ``` ruby
-require 'daedal'
-
-# creates the basic match query
-match_query = Daedal::Queries::MatchQuery.new(field: 'foo', query: 'bar')
+author_query = Daedal::Queries::MatchQuery.new(field: 'author', query: 'Beckett')
 ```
-Each query object has `#to_json` defined for easy conversion for use with any of the Ruby
+
+Each query has `#to_json` defined for easy conversion for use with any of the Ruby
 ElasticSearch clients out there:
+
 ``` ruby
-match_query.to_json # => "{\"match\":{\"foo\":{\"query\":\"bar\"}}}"
+author_query.to_json # => "{\"match\":{\"author\":{\"query\":\"Beckett\"}}}"
 ```
 
-To date (12/8/2013), I have implemented the following queries:
+The benefits of using Daedal become more obvious for aggregate queries such as the `bool query`:
+
+``` ruby
+bool_query = Daedal::Queries::BoolQuery.new(must: [author_query])
+bool_query.to_json # => "{\"bool\":{\"should\":[],\"must\":[{\"match\":{\"author\":{\"query\":\"Beckett\"}}}],\"must_not\":[]}}"
+
+lines_query = Daedal::Queries::MatchQuery.new(field: 'lines', query: "We're waiting for Godot")
+bool_query.should << lines_query
+
+bool_query.to_json # => "{\"bool\":{\"should\":[{\"match\":{\"lines\":{\"query\":\"We're waiting for Godot\"}}}],\"must\":[{\"match\":{\"author\":{\"query\":\"Beckett\"}}}],\"must_not\":[]}}"
+```
+
+Currently, the following queries have been implemented:
 * [bool query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html)
 * [constant score query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-constant-score-query.html)
 * [dis max query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-dis-max-query.html)
 * [filtered query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-filtered-query.html)
+* [fuzzy query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-fuzzy-query.html)
 * [match all query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-match-all-query.html)
 * [match query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-match-query.html)
 * [multi match query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html)
 * [nested query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html)
 * [prefix query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-prefix-query.html)
+* [query string query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html)
 
-To be implemented next:
+On deck:
 * [function score query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html)
-* [fuzzy query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-fuzzy-query.html)
-* [query string query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html)
 * [range query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-range-query.html)
 * [regexp query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-regexp-query.html)
 * [term query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-term-query.html)
@@ -89,28 +119,26 @@ Queries I'm not planning on implementing at all, since they're deprecated:
 
 ### Filters
 
-Filters are contained within the `Filters` module. You can construct filter components
+Filters are contained within the `Daedal::Filters` module. You can construct filter components
 in the same way as queries:
 
 ``` ruby
-require 'daedal'
-
-term_filter = Daedal::Filters::TermFilter.new(field: 'foo', term: 'bar')
+term_filter = Daedal::Filters::TermFilter.new(field: 'characters', term: 'Pozzo')
 
-term_filter.to_json # => "{\"term\":{\"foo\":\"bar\"}}"
+term_filter.to_json # => "{\"term\":{\"characters\":\"Pozzo\"}}"
 ```
 
-To date (12/8/2013), I have implemented the following filters:
+Currently, the following filters have been implemented:
 * [and filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-and-filter.html)
+* [bool filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-bool-filter.html)
 * [geo distance filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-geo-distance-filter.html)
+* [or filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-or-filter.html)
 * [range filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-range-filter.html)
 * [term filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-term-filter.html)
 * [terms filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-terms-filter.html)
 
-To be implemented next:
-* [bool filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-bool-filter.html)
+On deck:
 * [nested filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-nested-filter.html)
-* [or filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-or-filter.html)
 
 ### Type checking and attribute coercion
 
@@ -125,54 +153,85 @@ constant_score_query = {'constant_score' => {'boost' => 'foo', 'query' => {'matc
 would yield a server error, since the `boost` parameter must be a number.
 
 Daedal uses [Virtus](https://github.com/solnic/virtus) to perform data-type coercions. 
-That way, invalid query parameters are surfaced at runtime, making debugging easier.
-The previous `constant_score_query` example in Daedal would raise an error:
+Invalid query parameters are surfaced at runtime, making debugging much easier.
+The previous example in Daedal would raise an error:
 
 ``` ruby
-match_all_query = Daedal::Queries::MatchAllQuery.new()
-constant_score_query = Daedal::Queries::ConstantScoreQuery.new(boost: 'foo', query: match_all_query)
+match_all_query = Daedal::Queries::MatchAllQuery.new
 
+constant_score_query = Daedal::Queries::ConstantScoreQuery.new(boost: 'foo', query: match_all_query)
 # Virtus::CoercionError: Failed to coerce "foo" into Float
 ```
 
-### Creating your own queries
+Similarly, trying to add non-queries to an aggregate query like the `bool` or `dis max` queries
+will result in an error:
 
-Currently, I've only made it through a fraction of the entire Query DSL, but will be working to
-achieve complete coverage as quickly as possible. If you need to use a query that
-I haven't gotten to yet, or if you want to create your own more specialized queries within
-your own project, defining the query classes is relatively straightforward - just make
-your new class a sublass of the `Daedal::Queries::BaseQuery` or `Daedal::Filters::BaseFilter`
-classes, and define the `to_hash` method. All methods made available by including `Virtus.model` in your
-class will be available to you, as well.
+``` ruby
+dis_max_query = Daedal::Queries::DisMaxQuery.new
+
+dis_max_query.queries << :foo
+# Virtus::CoercionError: Failed to coerce :foo into "Daedal::Queries::Query"
+```
 
-Example:
+### Creating custom queries
+
+Currently, I've only made it through a fraction of the entire Query DSL, but will be adding more
+as time goes by. If there's a component of the query DSL that you need that isn't implemented yet,
+it's easy to define it yourself within your project (or, feel free to contribute to Daedal!).
+
+Creating custom filters or queries tailored specifically to your use case is also pretty straightforward.
+Here are some guidelines:
+
+* Make your class inherit from `Daedal::Queries::Query` or `Daedal::Filters::Filter`
+* Define the parameters for your query using [Virtus](https://github.com/solnic/virtus) attributes (**note**: `strict` coercion is being used)
+* Define the `#to_hash` method
+
+Example of a custom query:
 ``` ruby
-class MyQuery < Daedal::Queries::BaseQuery
+class PlayQuery < Daedal::Queries::Query
   
-  # define the attributes that you need in your query
-  attribute :foo, String
-  attribute :bar, String
+  # define the parameters that you want in your query
+  # if the field is optional, make sure to set required to false
+  attribute :author, String
+
+  attribute :characters, Array[String], required: false
+  attribute :title, String, required: false
+
+  def construct_query
+    author_query = Daedal::Queries::MatchQuery.new(field: 'author', query: author)
+    title_query = Daedal::Queries::MatchQuery.new(field: 'title', query: title)
+
+    full_query = Daedal::Queries::BoolQuery.new(must: [author_query], should: [title_query])
+    characters.each do |character|
+      full_query.should << Daedal::Queries::MatchQuery.new(field: 'characters', query: character)
+    end
+
+    full_query
+  end
 
   # define the to_hash method to convert for use in ElasticSearch 
   def to_hash
-    ...
+    construct_query.to_hash
   end
 end
+
+play_query = PlayQuery.new(author: 'Beckett', title: 'Waiting for Godot', characters: ['Estragon', 'Vladimir'])
+puts play_query.to_json # => {"bool":{"should":[{"match":{"title":{"query":"Waiting for Godot"}}},{"match":{"characters":{"query":"Estragon"}}},{"match":{"characters":{"query":"Vladimir"}}}],"must":[{"match":{"author":{"query":"Beckett"}}}],"must_not":[]}}
 ```
 
 Contributing
 -------------
 
-The ElasticSearch Query DSL is pretty large and includes a ton of nuance. I'm starting with the
+The ElasticSearch Query DSL is pretty big and includes a ton of nuance. I'm starting with the
 most basic parts of the DSL (and the parts I use for work), so if you want to help out with the project
 to meet your needs please feel free to contribute! I just ask that you:
 
-* Fork the project.
-* Make your changes or additions.
-* Add tests! My goal is complete test coverage, so please take the effort to make them pretty comprehensive.
-* Send me a pull request.
+* Fork the project
+* Make your changes or additions
+* Add tests! My goal is to keep Daedal a thoroughly tested project
+* Send me a pull request
 
-Feedback or suggestions are also always welcome. 
+Feedback or suggestions are also always welcome!
 
 License
 -------