parascope 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6caa45deb0d23160ab7595714e4517eed4306e10
-  data.tar.gz: e407dc5cb9e132c3c814ce43ad94ea64a1c57fb4
+  metadata.gz: 3066d6e82e5f23716dd07cea4c449017e70bbd9d
+  data.tar.gz: 56028229436dde9aeb953c6d2a8c3422481a92a4
 SHA512:
-  metadata.gz: 6af3bf60ea924a9b8326f962424f08ce71b0623fdc5c6277109e0eee70077ccd368ca1b2193a2a5410dda1fc2f619232fcbd8039f18caee79c2e60d1effc3126
-  data.tar.gz: baedb425a6571abd713856e34bd3859a75d4c38a2146ccaa96efc56ca9b56924f9c70f13bfb7c713cdaba3848132852c613f5f316d47d33e19988e2c64219904
+  metadata.gz: 3067309bd1f430f5aa295a76302b4cd16e23cfdc2a35ec0fccaa14f1a71df6d07663e6adbc38a90222de450c5d35df67b54f48391deb9e90580f2a0728029b93
+  data.tar.gz: 6ac678b8533decc7fabc77179d534f06e1e1c63060025572875bdfb23ca268ca90d1f36060f74f2061999044328d38f470eba184cedbae2c26a0cfc3d67682ff

data/README.md

@@ -163,9 +163,10 @@ sifter :paginated do
 end
 ```
 
-- `guard(&block)` defines a guard instance method block (see instance methods
+- `guard(message = nil, &block)` defines a guard instance method block (see instance methods
   bellow). All such blocks are executed before query object resolves scope via
-  `resolve_scope` method.
+  `resolve_scope` method. Optional `message` may be supplied to provide more informative
+  error message.
 
 *Examples:*
 
@@ -173,12 +174,39 @@ end
 sift_by(:sort_col, :sort_dir) do |scol, sdir|
   # will raise Parascope::GuardViolationError on scope resolution if
   # params[:sort_dir] is not 'asc' or 'desc'
-  guard { sdir.downcase.in?(%w(asc desc)) }
+  guard(':sort_dir should be "asc" or "desc"') do
+    sdir.downcase.in?(%w(asc desc))
+  end
 
   base_scope { |scope| scope.order(scol => sdir) }
 end
 ```
 
+- `raise_on_guard_violation(value)` allows to specify whether or not exception should be raised
+  whenever any guard block is violated during scope resolution. When set to `false`, in case
+  of any violation, `resolved_scope` will return `nil`, and query will have `violation` property
+  set with value corresponding to the message of violated block. Default option value is `true`.
+
+*Examples:*
+
+```ruby
+raise_on_guard_violation false
+
+sift_by(:sort_col, :sort_dir) do |scol, sdir|
+  guard(':sort_dir should be "asc" or "desc"') do
+    sdir.downcase.in?(%w(asc desc))
+  end
+
+  base_scope { |scope| scope.order(scol => sdir) }
+end
+```
+
+```ruby
+query = UsersQuery.new(sort_col: 'id', sort_dir: 'there')
+query.resolved_scope # => nil
+query.violation # => ":sort_dir should be \"asc\" or \"desc\""
+```
+
 - `build(scope: nil, **attributes)` initializes a query with empty params. Handy when
   query depends only passed attributes and internal logic. Also useful in specs.
 

data/bin/console

@@ -6,12 +6,14 @@ require "parascope"
 require 'ostruct'
 
 class Query < Parascope::Query
+  raise_on_guard_violation false
+
   defaults barbak: 'barbak'
 
   base_scope { OpenStruct.new }
 
   query_by :foo do |foo|
-    guard { foo == 'foo' }
+    guard('wrong value for :foo param. try "foo"') { foo == 'foo' }
 
     scope.tap{ scope.foo = foo }
   end

data/lib/parascope.rb

@@ -5,4 +5,6 @@ module Parascope
   GuardViolationError = Class.new(ArgumentError)
 
   autoload :Query, "parascope/query"
+
+  Query.raise_on_guard_violation true
 end

data/lib/parascope/query.rb

@@ -7,9 +7,10 @@ module Parascope
 
     extend ApiMethods
 
-    attr_reader :params
+    attr_reader :params, :violation
 
     def self.inherited(subclass)
+      subclass.raise_on_guard_violation raise_on_guard_violation?
       subclass.query_blocks.replace query_blocks.dup
       subclass.sift_blocks.replace sift_blocks.dup
       subclass.guard_blocks.replace guard_blocks.dup
@@ -21,6 +22,14 @@ module Parascope
       new({}, **attrs)
     end
 
+    def self.raise_on_guard_violation(value)
+      @raise_on_guard_violation = !!value
+    end
+
+    def self.raise_on_guard_violation?
+      @raise_on_guard_violation
+    end
+
     def initialize(params, scope: nil, dataset: nil, **attrs)
       @params = Hashie::Mash.new(klass.defaults).merge(params || {})
       @scope  = scope || dataset unless scope.nil? && dataset.nil?
@@ -51,10 +60,14 @@ module Parascope
     alias_method :base_dataset, :base_scope
 
     def resolved_scope(*args)
+      @violation = nil
       arg_params = args.pop if args.last.is_a?(Hash)
       return sifted_instance.resolved_scope! if arg_params.nil? && args.empty?
 
       clone_with_params(trues(args).merge(arg_params || {})).resolved_scope
+    rescue GuardViolationError => error
+      @violation = error.message
+      raise if self.class.raise_on_guard_violation?
     end
     alias_method :resolved_dataset, :resolved_scope
     alias_method :resolve, :resolved_scope
@@ -138,13 +151,15 @@ module Parascope
     private
 
     def guard_all
-      klass.guard_blocks.each{ |block| guard(&block) }
+      klass.guard_blocks.each{ |message, block| guard(message, &block) }
     end
 
-    def guard(&block)
-      unless instance_exec(&block)
-        fail GuardViolationError, "guard block violated on #{block.source_location.join(':')}"
-      end
+    def guard(message = nil, &block)
+      return if instance_exec(&block)
+
+      violation = message || "guard block violated on #{block.source_location.join(':')}"
+
+      fail GuardViolationError, violation
     end
 
     def sifted_instance_for(blocks)

data/lib/parascope/query/api_methods.rb

@@ -55,8 +55,8 @@ module Parascope
     alias_method :sifter!, :sift_by!
     alias_method :query!, :query_by!
 
-    def guard(&block)
-      guard_blocks.push block
+    def guard(message = nil, &block)
+      guard_blocks.push([message, block])
     end
 
     def sift_blocks

data/lib/parascope/version.rb

@@ -1,3 +1,3 @@
 module Parascope
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parascope
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-13 00:00:00.000000000 Z
+date: 2019-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie