parascope 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20fc5771d922f27cb3562954c138dd4d9069f01a
-  data.tar.gz: 2da5ec9511b1cdea10f7a7e84aaa6023c358733c
+  metadata.gz: d24fcd353f9b0a8dc2091b654e35c4f6b3f973c4
+  data.tar.gz: 23a9825594b4ab16faa6deb34b4da2b5232fdd8c
 SHA512:
-  metadata.gz: af2fce7745657960a666ae9d160b6fced85be97a3698f8b6cd1ed0d8f5b14d694e349222c011752071501e77f86a8ca62b415c2c22c4e5d75d3fc5648460a571
-  data.tar.gz: ab35b12aa2b8a822dd53eb113867b63fc6cd1c00685021108273c724e4569dd78267b58b4d8da395a5c7c3db8157b951a91a6efc7d4e8b2f2636bccd5c732533
+  metadata.gz: c27284dc7a29103d72502a5db3232eca92fb99341df633e0f77c7c905a269e85bdc75ecf4a45e8a5945b94e0dbb72a289aa76fe7b24f41341d64421fec547e44
+  data.tar.gz: f5ae369d56e2ae924a358e950e8196127c1c31bc8a9c13d833fe479a6dcf36489b678502f3cebfee398f04d5281625afbef2c92ace9b24e2f37cafacb35fce73

data/README.md

@@ -28,7 +28,7 @@ Or install it yourself as:
 
 ## Usage
 
-Despite the fact `parsacope` was intended to help building ActiveRecord relations
+Despite the fact `parascope` was intended to help building ActiveRecord relations
 via scopes or query methods, it's usage is not limited to ActiveRecord cases and
 may be used with any arbitrary classes and objects. In fact, the only gem's dependency
 is `hashie`, and for development and testing, `OpenStruct` instance is used as a
@@ -44,12 +44,21 @@ scope manipulations using `query_by`, `sift_by` and other class methods bellow.
 
 - `query_by(*presence_fields, **value_fields, &block)` declares a scope-generation query
   block that will be executed if, and only if all values of query params at the keys of
-  `presence_fields` are present in activesupport's definition of presence and all value
-  fields are present in query params as is. The block is executed in context of query
+  `presence_fields` are present in activesupport's definition of presence and all `value_fields`
+  are present in query params as is. The block is executed in context of query
   object. All values of specified params are yielded to the block. If the block
-  returns a non-nil value, it becomes a new scope for following processing. Of course,
-  there can be multiple `query_by` block definitions. Optionally, `:index` option
-  may be passed to control query blocks application order.
+  returns a non-nil value, it becomes a new scope for subsequent processing. Of course,
+  there can be multiple `query_by` block definitions. Methods accepts additional options:
+  - `:index` - allows to specify order of query block applications. By default all query
+    blocks have index of 0;
+  - `:if` - specifies condition according to which query should be applied. If Symbol
+    or String is passed, calls corresponding method. If Proc is passed, it is executed
+    in context of query object. Note that this is optional condition, and does not
+    overwrite original param-based condition for a query block that should always be met.
+  - `:unless` - the same as `:if` option, but with reversed boolean check.
+
+- `query(&block)` declares scope-generation block that is always executed. As `query_by`,
+  accepts `:index`, `:if` and `:unless` options.
 
 - `sift_by(*presence_fields, **value_fields, &block)` method is used to hoist sets of
   query definitions that should be applied if, and only if, all specified values
@@ -57,6 +66,9 @@ scope manipulations using `query_by`, `sift_by` and other class methods bellow.
   values of specified fields are yielded to the block. Such `sift_by` definitions
   may be nested in any depth.
 
+- `sifter` alias for `sift_by`. Results in a more readable construct when a single
+  presence field is passed. For example, `sifter(:paginated)`.
+
 - `base_scope(&block)` method is used to define a base scope as a starting point
   of scope-generating process. If this method is called from `sift_by` block,
   top-level base scope is yielded to the method block. Note that `base_scope` will
@@ -86,14 +98,16 @@ scope manipulations using `query_by`, `sift_by` and other class methods bellow.
   it's mutated version corresponding to passed `query_by` arguments.
 
 - `guard(&block)` executes a passed `block`. If this execution returns falsy value,
-  `UnpermittedError` is raised. You can use this method to ensure safety of param
+  `GuardViolationError` is raised. You can use this method to ensure safety of param
   values interpolation to a SQL string in a `query_by` block for example.
 
-- `resolved_scope(override_params = nil)` returns a resulting scope generated by
-  all queries and sifted queries that fit to query params applied to base scope.
-  Optionally, additional params may be passed to override the ones passed on
-  initialization. It's the main `Query` instance method that returns the sole
-  purpose of it's instances.
+- `resolved_scope(*presence_keys, override_params = {})` returns a resulting scope
+  generated by all queries and sifted queries that fit to query params applied to
+  base scope. Optionally, additional params may be passed to override the ones passed on
+  initialization. For convinience, you may pass list of keys that should be resolved
+  to `true` with params (for example, `resolved_scope(:with_projects)` instead of
+  `resolved_scope(with_projects: true)`). It's the main `Query` instance method that
+  returns the sole purpose of it's instances.
 
 ### Usage example with ActiveRecord Relation as a scope
 
@@ -120,12 +134,12 @@ class UserQuery < Parascope::Query
 
     base_scope { |scope| scope.order(scol => sdir) }
 
-    query_by(:sort_direction, sort_column: 'name') do |sdir|
+    query_by(sort_column: 'name') do
       scope.reorder("CONCAT(first_name, ' ', last_name) #{sdir}")
     end
   end
 
-  sift_by :with_projects do
+  sifter :with_projects do
     base_scope { |scope| scope.joins(:projects) }
 
     query_by :project_name do |name|
@@ -138,7 +152,7 @@ class UserQuery < Parascope::Query
   end
 
   def project_users
-    @project_users ||= resolved_scope(with_projects: true)
+    @project_users ||= resolved_scope(:with_projects)
   end
 end
 

data/bin/console

@@ -45,12 +45,23 @@ class Query < Parascope::Query
     end
   end
 
+  sift_by :other_baz do |other|
+    query { scope.tap{ scope.other_baz = other } }
+  end
+
+  query(if: :condition?) { scope.tap{ scope.by_instance_condition = true } }
+  query(unless: :bad_condition?) { scope.tap{ scope.not_bad_condition = true } }
+
+  def condition?
+    !!params[:condition]
+  end
+
   def upcase(str)
     str.upcase
   end
 end
 
-q = Query.new(foo: 'foo', bar: 'bar', baz: 'baz', bak: 'bak', nested_baz: 'nb')
+q = Query.new(foo: 'foo', bar: 'bar', baz: 'baz', bak: 'bak', nested_baz: 'nb', other_baz: 'ob')
 
 require "pry"
 Pry.start

data/lib/parascope/query.rb

@@ -9,7 +9,9 @@ module Parascope
     extend ApiMethods
 
     UndefinedScopeError = Class.new(StandardError)
-    UnpermittedError = Class.new(ArgumentError)
+    GuardViolationError = Class.new(ArgumentError)
+    # for backward-compatability
+    UnpermittedError = GuardViolationError
 
     attr_reader :params
     def_delegator :params, :[]
@@ -25,7 +27,8 @@ module Parascope
     def initialize(params, scope: nil, **attrs)
       @params = Hashie::Mash.new(klass.defaults).merge(params || {})
       @scope  = scope unless scope.nil?
-      @attrs  = attrs
+      @attrs  = attrs.freeze
+      @base_params = @params
       define_attr_readers
     end
 
@@ -48,10 +51,11 @@ module Parascope
       scope
     end
 
-    def resolved_scope(params = nil)
-      return sifted_instance.resolved_scope! if params.nil?
+    def resolved_scope(*args)
+      arg_params = args.pop if args.last.is_a?(Hash)
+      return sifted_instance.resolved_scope! if arg_params.nil? && args.empty?
 
-      clone_with_params(params).resolved_scope
+      clone_with_params(trues(args).merge(arg_params || {})).resolved_scope
     end
 
     def klass
@@ -65,9 +69,9 @@ module Parascope
     attr_reader :attrs
 
     def sifted_instance
-      block = klass.sift_blocks.find{ |block| block.fits?(params) }
+      blocks = klass.sift_blocks.select{ |block| block.fits?(self) }
 
-      block ? sifted_instance_for(block) : self
+      blocks.size > 0 ? sifted_instance_for(blocks) : self
     end
 
     def resolved_scope!
@@ -78,37 +82,31 @@ module Parascope
     end
 
     def apply_block!
-      if block && block.fits?(params)
+      if block && block.fits?(self)
         scope  = instance_exec(*block.values_for(params), &block.block)
         @scope = scope unless scope.nil?
       end
       self
     end
 
-    def sifted!(block, query)
+    def sifted!(query, blocks)
       @attrs = query.attrs
       define_attr_readers
       singleton_class.query_blocks.replace query.klass.query_blocks.dup
       singleton_class.guard_blocks.replace query.klass.guard_blocks.dup
       singleton_class.base_scope(&query.klass.base_scope)
-      singleton_class.instance_exec(*block.values_for(params), &block.block)
+      blocks.each do |block|
+        singleton_class.instance_exec(*block.values_for(params), &block.block)
+      end
       params.replace(singleton_class.defaults.merge(params))
       @sifted = true
     end
 
-    private
-
-    def guard_all
-      klass.guard_blocks.each{ |block| guard(&block) }
-    end
-
-    def guard(&block)
-      unless instance_exec(&block)
-        fail UnpermittedError, "processing is not allowed by guard block\non #{block.source_location.join(':')}"
-      end
+    def sifted?
+      !!@sifted
     end
 
-    def clone_with_scope(scope, block)
+    def clone_with_scope(scope, block = nil)
       clone.tap do |query|
         query.scope = scope
         query.block = block
@@ -116,28 +114,45 @@ module Parascope
     end
 
     def clone_with_params(other_params)
-      clone.tap do |query|
-        query.params = params.merge(other_params)
+      dup.tap do |query|
+        query.params = @base_params.merge(other_params)
+        query.remove_instance_variable('@sifted') if query.instance_variable_defined?('@sifted')
+        query.remove_instance_variable('@scope') if query.instance_variable_defined?('@scope')
+        query.define_attr_readers
       end
     end
 
-    def clone_with_sifter(block)
+    def clone_sifted_with(blocks)
       dup.tap do |query|
-        query.sifted!(block, self)
+        query.sifted!(self, blocks)
       end
     end
 
-    def sifted?
-      !!@sifted
+    def define_attr_readers
+      @attrs.each do |name, value|
+        define_singleton_method(name){ value }
+      end
     end
 
-    def sifted_instance_for(block)
-      clone_with_sifter(block).sifted_instance
+    private
+
+    def guard_all
+      klass.guard_blocks.each{ |block| guard(&block) }
     end
 
-    def define_attr_readers
-      @attrs.each do |name, value|
-        define_singleton_method(name){ value }
+    def guard(&block)
+      unless instance_exec(&block)
+        fail GuardViolationError, "guard block violated on #{block.source_location.join(':')}"
+      end
+    end
+
+    def sifted_instance_for(blocks)
+      clone_sifted_with(blocks).sifted_instance
+    end
+
+    def trues(keys)
+      keys.each_with_object({}) do |key, hash|
+        hash[key] = true
       end
     end
   end

data/lib/parascope/query/api_block.rb

@@ -1,7 +1,22 @@
 module Parascope
-  class Query::ApiBlock < Struct.new(:presence_fields, :value_fields, :block, :index)
-    def fits?(params)
-      values_for(params).all?{ |value| present?(value) }
+  class Query::ApiBlock
+    OPTION_KEYS = %i[index if unless].freeze
+    private_constant :OPTION_KEYS
+
+    attr_reader :presence_fields, :value_fields, :block, :options
+
+    def initialize(presence_fields:, value_fields:, block:)
+      @options = extract_options!(value_fields)
+
+      @presence_fields, @value_fields, @block =
+        presence_fields, value_fields, block
+    end
+
+    def fits?(query)
+      return false unless conditions_met_by?(query)
+
+      (presence_fields.size == 0 && value_fields.size == 0) ||
+        values_for(query.params).all?{ |value| present?(value) }
     end
 
     def values_for(params)
@@ -12,12 +27,41 @@ module Parascope
       value.respond_to?(:empty?) ? !value.empty? : !!value
     end
 
+    def index
+      options[:index] || 0
+    end
+
     private
 
+    def extract_options!(fields)
+      fields.keys.each_with_object({}) do |key, options|
+        options[key] = fields.delete(key) if OPTION_KEYS.include?(key)
+      end
+    end
+
     def valued_values_for(params)
       value_fields.map do |field, required_value|
         params[field] == required_value && required_value
       end
     end
+
+    def conditions_met_by?(query)
+      condition_met?(query, :if) && condition_met?(query, :unless)
+    end
+
+    def condition_met?(query, key)
+      return true unless options.key?(key)
+
+      condition = options[key]
+
+      value =
+        case condition
+        when String, Symbol then query.send(condition)
+        when Proc then query.instance_exec(&condition)
+        else condition
+        end
+
+      key == :if ? value : !value
+    end
   end
 end

data/lib/parascope/query/api_methods.rb

@@ -15,13 +15,24 @@ module Parascope
     end
 
     def sift_by(*presence_fields, **value_fields, &block)
-      sift_blocks.push Query::ApiBlock.new(presence_fields, value_fields, block)
+      sift_blocks.push Query::ApiBlock.new(
+        presence_fields: presence_fields,
+        value_fields:    value_fields,
+        block:           block
+      )
     end
 
-    def query_by(*presence_fields, index: 0, **value_fields, &block)
-      query_blocks.push Query::ApiBlock.new(presence_fields, value_fields, block, index)
+    def query_by(*presence_fields, **value_fields, &block)
+      query_blocks.push Query::ApiBlock.new(
+        presence_fields: presence_fields,
+        value_fields:    value_fields,
+        block:           block
+      )
     end
 
+    alias_method :sifter, :sift_by
+    alias_method :query, :query_by
+
     def guard(&block)
       guard_blocks.push block
     end

data/lib/parascope/version.rb

@@ -1,3 +1,3 @@
 module Parascope
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parascope
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-09 00:00:00.000000000 Z
+date: 2016-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie