flex-scopes 1.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2013 by Domizio Demichelis
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,25 @@
+# flex-scopes
+
+Provides an easy to use ruby API to search elasticsearch with ActiveRecord-like chainable and mergeables scopes.
+
+
+## Links
+
+* [Flex Repository](https://github.com/ddnexus/flex)
+* [Flex Project (Global Documentation)](http://ddnexus.github.io/flex/doc/)
+* [flex-scopes Gem (Specific Documentation)](http://ddnexus.github.io/flex/doc/3-flex-scopes)
+* [Issues](https://github.com/ddnexus/flex-scopes/issues)
+* [Pull Requests](https://github.com/ddnexus/flex-scopes/pulls)
+
+## Branches
+
+The master branch reflects the last published gem. Then you may find a next-version branch (named after the version string), with the commits that will be merged in master just before publishing the next gem version. The next-version branch may get rebased or force pushed.
+
+## Credits
+
+Special thanks for their sponsorship to [Escalate Media](http://www.escalatemedia.com) and [Barquin International](http://www.barquin.com).
+
+## Copyright
+
+Copyright (c) 2012-2013 by [Domizio Demichelis](mailto://dd.nexus@gmail.com)<br>
+See [LICENSE](https://github.com/ddnexus/flex-scopes/blob/master/LICENSE) for details.

data/VERSION

@@ -0,0 +1 @@
+1.0.1

data/flex-scopes.gemspec

@@ -0,0 +1,19 @@
+require 'date'
+version = File.read(File.expand_path('../VERSION', __FILE__)).strip
+
+Gem::Specification.new do |s|
+  s.name                      = 'flex-scopes'
+  s.summary                   = 'ActiveRecord-like chainable scopes and finders for Flex.'
+  s.description               = 'Provides an easy to use ruby API to search elasticsearch with ActiveRecord-like chainable and mergeables scopes.'
+  s.homepage                  = 'http://github.com/ddnexus/flex-scopes'
+  s.authors                   = ["Domizio Demichelis"]
+  s.email                     = 'dd.nexus@gmail.com'
+  s.extra_rdoc_files          = %w[README.md]
+  s.files                     = `git ls-files -z`.split("\0")
+  s.version                   = version
+  s.date                      = Date.today.to_s
+  s.required_rubygems_version = ">= 1.3.6"
+  s.rdoc_options              = %w[--charset=UTF-8]
+
+  s.add_runtime_dependency 'flex', version
+end

data/lib/flex-scopes.rb

@@ -0,0 +1,12 @@
+require 'flex'
+require 'flex/scope/utils'
+require 'flex/scope/filter_methods'
+require 'flex/scope/vars_methods'
+require 'flex/scope/query_methods'
+require 'flex/scope'
+require 'flex/scopes'
+require 'flex/result/scope'
+
+Flex::LIB_PATHS << File.dirname(__FILE__)
+
+Flex::Conf.result_extenders |= [Flex::Result::Scope]

data/lib/flex/result/scope.rb

@@ -0,0 +1,12 @@
+module Flex
+  class Result
+    module Scope
+
+      def get_docs
+        return self if variables[:raw_result]
+        respond_to?(:collection) ? collection : self
+      end
+
+    end
+  end
+end

data/lib/flex/scope.rb

@@ -0,0 +1,42 @@
+module Flex
+  # never instantiate this class directly: it is automatically done by the scoped method
+  class Scope < Vars
+
+    class Error < StandardError; end
+
+    include FilterMethods
+    include VarsMethods
+    include QueryMethods
+
+    SCOPED_METHODS = FilterMethods.instance_methods + VarsMethods.instance_methods + QueryMethods.instance_methods
+
+    def inspect
+      "#<#{self.class.name} #{self}>"
+    end
+
+    def respond_to?(meth, private=false)
+      super || is_template?(meth) || is_scope?(meth)
+    end
+
+    def method_missing(meth, *args, &block)
+      super unless respond_to?(meth)
+      case
+      when is_scope?(meth)
+        deep_merge self[:context].send(meth, *args, &block)
+      when is_template?(meth)
+        self[:context].send(meth, deep_merge(*args), &block)
+      end
+    end
+
+  private
+
+    def is_template?(name)
+      self[:context].respond_to?(:template_methods) && self[:context].template_methods.include?(name.to_sym)
+    end
+
+    def is_scope?(name)
+      self[:context].scope_methods.include?(name.to_sym)
+    end
+
+  end
+end

data/lib/flex/scope/filter_methods.rb

@@ -0,0 +1,81 @@
+module Flex
+  class Scope
+    module FilterMethods
+
+      include Scope::Utils
+
+      # accepts also :any_term => nil for missing values
+      def terms(value)
+        terms, missing_list = {}, []
+        value.each { |f, v| v.nil? ? missing_list.push({ :missing => f }) : (terms[f] = v) }
+        terms, term = terms.partition{|k,v| v.is_a?(Array)}
+        term_list = []
+        term.each do |term, value|
+          term_list.push(:term => {term => value})
+        end
+        deep_merge boolean_wrapper( :terms_list    => Hash[terms],
+                                    :term_list     => term_list,
+                                    :_missing_list => missing_list )
+      end
+
+      # accepts one or an array or a list of filter structures
+      def filters(*value)
+        deep_merge boolean_wrapper( :filters => array_value(value) )
+      end
+
+      def missing(*fields)
+        missing_list = []
+        for field in fields
+          missing_list.push(:missing => field)
+        end
+        deep_merge :_missing_list => missing_list
+      end
+
+      # accepts a single key hash or a multiple keys hash, that will be translated in a array of single key hashes
+      def term(term_or_terms_hash)
+        term_list = []
+        term_or_terms_hash.each do |term, value|
+          term_list.push(:term => {term => value})
+        end
+        deep_merge boolean_wrapper(:term_list => term_list)
+      end
+
+      # accepts one hash of ranges documented at
+      # http://www.elasticsearch.org/guide/reference/query-dsl/range-filter/
+      def range(value)
+        deep_merge boolean_wrapper(:range => value)
+      end
+
+
+      %w[and or].each do |m|
+        class_eval <<-ruby, __FILE__, __LINE__
+        def #{m}(&block)
+          vars = {:_#{m} => Hash[Flex::Scope.new.instance_eval(&block).to_a]}
+          vars.merge!(:_boolean_wrapper => :_#{m}) if context_scope?
+          deep_merge vars
+        end
+        ruby
+      end
+
+    private
+
+      def context_scope?
+        has_key?(:context)
+      end
+
+      def boolean_wrapper(value)
+        if context_scope?
+          if has_key?(:_boolean_wrapper) && self[:_boolean_wrapper] != :_and
+            current_wrapper = {self[:_boolean_wrapper] => delete(self[:_boolean_wrapper])}
+            self.and{ current_wrapper }.and{ value }
+          else
+            self.and{value}
+          end
+        else
+          value
+        end
+      end
+
+    end
+  end
+end

data/lib/flex/scope/queries.yml

@@ -0,0 +1,52 @@
+ANCHORS:
+  - &filters
+    - <<filters= ~ >>
+    - <<term_list= ~ >>
+    - terms: <<terms_list= ~ >>
+    - <<_missing_list= ~ >>
+    - <<_and= ~ >>
+    - <<_or= ~ >>
+    - range: <<range= ~ >>
+
+  - &scope
+    query:
+      query_string:
+        "<<cleanable_query= {query: '*'} >>"
+    script_fields:
+      <<script_fields= ~ >>
+    sort: <<sort= ~ >>
+    facets: <<facets= ~ >>
+    highlight: <<highlight= ~ >>
+    filter: <<_boolean_wrapper= :_and >>
+
+_and:
+  and: *filters
+
+_or:
+  or: *filters
+
+_missing_fields:
+  missing:
+    field: <<missing>>
+
+get:
+- GET
+- /<<index>>/<<type>>/_search
+- *scope
+
+
+
+delete:
+- DELETE
+- /<<index>>/<<type>>/_query
+- filtered:
+    <<: *scope
+
+
+
+ids:
+- GET
+- /<<index>>/<<type>>/_search
+- query:
+    terms:
+      _id: <<ids>>

data/lib/flex/scope/query_methods.rb

@@ -0,0 +1,89 @@
+module Flex
+  class Scope
+
+    module Query
+
+      include Templates
+      flex.load_source File.expand_path('../queries.yml', __FILE__)
+
+    end
+
+    module QueryMethods
+
+      #    MyModel.find(ids, *vars)
+      #    - ids can be a single id or an array of ids
+      #
+      #    MyModel.find '1Momf4s0QViv-yc7wjaDCA'
+      #      #=> #<MyModel ... color: "red", size: "small">
+      #
+      #    MyModel.find ['1Momf4s0QViv-yc7wjaDCA', 'BFdIETdNQv-CuCxG_y2r8g']
+      #      #=> [#<MyModel ... color: "red", size: "small">, #<MyModel ... color: "bue", size: "small">]
+      #
+      def find(ids, *vars)
+        raise ArgumentError, "Empty argument passed (got #{ids.inspect})" \
+              if ids.nil? || ids.respond_to?(:empty?) && ids.empty?
+        wrapped = ids.is_a?(::Array) ? ids : [ids]
+        result  = Query.ids self, *vars, :ids => wrapped
+        docs    = result.get_docs
+        ids.is_a?(::Array) ? docs : docs.first
+      end
+
+      # it limits the size of the query to the first document and returns it as a single document object
+      def first(*vars)
+        result = Query.get params(:size => 1), *vars
+        docs   = result.get_docs
+        docs.is_a?(Array) ? docs.first : docs
+      end
+
+      # it limits the size of the query to the last document and returns it as a single document object
+      def last(*vars)
+        result = Query.get params(:from => count-1, :size => 1), *vars
+        docs   = result.get_docs
+        docs.is_a?(Array) ? docs.first : docs
+      end
+
+      # will retrieve all documents, the results will be limited by the default :size param
+      # use #scan_all if you want to really retrieve all documents (in batches)
+      def all(*vars)
+        result = Query.get self, *vars
+        result.get_docs
+      end
+
+      def each(*vars, &block)
+        all(*vars).each &block
+      end
+
+      # scan_search: the block will be yielded many times with an array of batched results.
+      # You can pass :scroll and :size as params in order to control the action.
+      # See http://www.elasticsearch.org/guide/reference/api/search/scroll.html
+      def scan_all(*vars, &block)
+        Query.flex.scan_search(:get, self, *vars) do |result|
+          block.call result.get_docs
+        end
+      end
+      alias_method :each_batch, :scan_all
+      alias_method :find_in_batches, :scan_all
+
+      def delete(*vars)
+        Query.delete self, *vars
+      end
+
+      # performs a count search on the scope
+      # you can pass a template name as the first arg and
+      # it will be used to compute the count. For example:
+      # SearchClass.scoped.count(:search_template, vars)
+      #
+      def count(*vars)
+        result = if vars.first.is_a?(Symbol)
+                   template = vars.shift
+                   # preserves an eventual wrapper by calling the template method
+                   self[:context].send(template, params(:search_type => 'count'), *vars)
+                 else
+                   Query.flex.count_search(:get, self, *vars)
+                 end
+        result['hits']['total']
+      end
+
+    end
+  end
+end

data/lib/flex/scope/utils.rb

@@ -0,0 +1,13 @@
+module Flex
+  class Scope < Vars
+    module Utils
+
+    private
+
+      def array_value(value)
+        (value.first.is_a?(::Array) && value.size == 1) ? value.first : value
+      end
+
+    end
+  end
+end

data/lib/flex/scope/vars_methods.rb

@@ -0,0 +1,81 @@
+module Flex
+  class Scope
+    module VarsMethods
+
+      include Scope::Utils
+
+      def query_string(q)
+        hash = q.is_a?(Hash) ? q : {:query => q}
+        deep_merge :cleanable_query => hash
+      end
+      alias_method :query, :query_string
+
+      # accepts one or an array or a list of sort structures documented at
+      # http://www.elasticsearch.org/guide/reference/api/search/sort.html
+      # doesn't probably support the multiple hash form, but you can pass an hash as single argument
+      # or an array or list of hashes
+      def sort(*value)
+        deep_merge :sort => array_value(value)
+      end
+
+      # the fields that you want to retrieve (limiting the size of the response)
+      # the returned records will be frozen (for Flex::ActiveModel objects), and the missing fields will be nil
+      # pass an array eg fields.([:field_one, :field_two]) or a list of fields e.g. fields(:field_one, :field_two)
+      def fields(*value)
+        deep_merge :params => {:fields => array_value(value)}
+      end
+
+      # limits the size of the retrieved hits
+      def size(value)
+        deep_merge :params => {:size => value}
+      end
+
+      # sets the :from param so it will return the nth page of size :size
+      def page(value)
+        deep_merge :page => value || 1
+      end
+
+      # the standard :params variable
+      def params(value)
+        deep_merge :params => value
+      end
+
+      # meaningful alias of deep_merge
+      def variables(*variables)
+        deep_merge *variables
+      end
+
+      def index(val)
+        deep_merge :index => val
+      end
+
+      def type(val)
+        deep_merge :type => val
+      end
+
+      # script_fields(:my_field       => 'script ...',                   # simpler form
+      #               :my_other_field => {:script => 'script ...', ...}) # ES API
+      def script_fields(hash)
+        hash.keys.each do |k|
+          v = hash[k]
+          hash[k] = {:script => v} unless v.is_a?(Hash)
+          hash[k][:script].gsub!(/\n+\s*/,' ')
+        end
+        deep_merge :script_fields => hash
+      end
+
+      def facets(hash)
+        deep_merge :facets => hash
+      end
+
+      def highlight(hash)
+        deep_merge :highlight => hash
+      end
+
+      def metrics
+        deep_merge :params => {:search_type => 'count'}
+      end
+
+    end
+  end
+end

data/lib/flex/scopes.rb

@@ -0,0 +1,89 @@
+module Flex
+  module Scopes
+
+    def self.included(context)
+      context.class_eval do
+        @flex ||= ClassProxy::Base.new(context)
+        def self.flex; @flex end
+
+        extend ClassMethods
+
+        @scope_methods = []
+        def self.scope_methods; @scope_methods end
+      end
+    end
+
+    module ClassMethods
+
+      #    Scope methods. They returns a Scope object similar to AR.
+      #    You can chain scopes, then you can call :count, :first, :all and :scan_all to get your result
+      #    See Flex::Scope
+      #
+      #    scoped = MyModel.terms(:field_one => 'something', :field_two => nil)
+      #                    .sort(:field_three => :desc)
+      #                    .filters(:range => {:created_at => {:from => 2.days.ago, :to => Time.now})
+      #                    .fields('field_one,field_two,field_three') # or [:field_one, :field_two, ...]
+      #                    .params(:any => 'param')
+      #
+      #    # add another filter or other terms at any time
+      #    scoped2 = scoped.terms(...).filters(...)
+      #
+      #    scoped2.count
+      #    scoped2.first
+      #    scoped2.all
+      #    scoped2.scan_all {|batch| do_something_with_results batch}
+      #
+      Utils.define_delegation :to  => :scoped,
+                              :in  => self,
+                              :by  => :module_eval,
+                              :for => Scope::SCOPED_METHODS
+
+
+      # You can start with a non restricted Flex::Scope object
+      def scoped
+        @scoped ||= Scope[:context => flex.context]
+      end
+
+
+      #    define scopes as class methods
+      #
+      #  class MyModel
+      #    include Flex::StoredModel
+      #    ...
+      #    scope :red, terms(:color => 'red').sort(:supplier => :asc)
+      #    scope :size do |size|
+      #      terms(:size => size)
+      #    end
+      #
+      #    MyModel.size('large').first
+      #    MyModel.red.all
+      #    MyModel.size('small').red.all
+      #
+      def scope(name, scope=nil, &block)
+        raise ArgumentError, "Dangerous scope name: a :#{name} method is already defined. Please, use another one." \
+              if respond_to?(name)
+        proc = case
+               when block_given?
+                 block
+               when scope.is_a?(Flex::Scope)
+                 lambda {scope}
+               when scope.is_a?(Proc)
+                 scope
+               else
+                 raise ArgumentError, "Scope object or Proc expected (got #{scope.inspect})"
+               end
+        metaclass = class << self; self end
+        metaclass.send(:define_method, name) do |*args|
+          scope = proc.call(*args)
+          raise Scope::Error, "The scope :#{name} does not return a Flex::Scope object (got #{scope.inspect})" \
+                unless scope.is_a?(Flex::Scope)
+          scope
+        end
+        scope_methods << name
+      end
+
+    end
+
+  end
+end
+

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: flex-scopes
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Domizio Demichelis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: flex
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+description: Provides an easy to use ruby API to search elasticsearch with ActiveRecord-like
+  chainable and mergeables scopes.
+email: dd.nexus@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- LICENSE
+- README.md
+- VERSION
+- flex-scopes.gemspec
+- lib/flex-scopes.rb
+- lib/flex/result/scope.rb
+- lib/flex/scope.rb
+- lib/flex/scope/filter_methods.rb
+- lib/flex/scope/queries.yml
+- lib/flex/scope/query_methods.rb
+- lib/flex/scope/utils.rb
+- lib/flex/scope/vars_methods.rb
+- lib/flex/scopes.rb
+homepage: http://github.com/ddnexus/flex-scopes
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: ActiveRecord-like chainable scopes and finders for Flex.
+test_files: []