parascope 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 20fc5771d922f27cb3562954c138dd4d9069f01a
+  data.tar.gz: 2da5ec9511b1cdea10f7a7e84aaa6023c358733c
+SHA512:
+  metadata.gz: af2fce7745657960a666ae9d160b6fced85be97a3698f8b6cd1ed0d8f5b14d694e349222c011752071501e77f86a8ca62b415c2c22c4e5d75d3fc5648460a571
+  data.tar.gz: ab35b12aa2b8a822dd53eb113867b63fc6cd1c00685021108273c724e4569dd78267b58b4d8da395a5c7c3db8157b951a91a6efc7d4e8b2f2636bccd5c732533

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.ruby-gemset
+.ruby-version

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.0
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Artem Kuzko
+
+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,173 @@
+# Parascope
+
+[![Build Status](https://secure.travis-ci.org/akuzko/parascope.png)](http://travis-ci.org/akuzko/parascope)
+
+Because `periscope` is already taken.
+
+--
+
+This gem provides a `Parascope::Query` class with a declarative and convenient API
+to build scopes (ActiveRecord relations or arbitrary objects) dynamically, based
+on parameters passed to query object on initialization.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'parascope'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install parascope
+
+## Usage
+
+Despite the fact `parsacope` 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
+generic scope object. However, ActiveRecord examples should illustrate gem's usage
+in the best way.
+
+### API
+
+`parascope` provides `Parascope::Query` class, descendants of which should declare
+scope manipulations using `query_by`, `sift_by` and other class methods bellow.
+
+#### Class Methods
+
+- `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
+  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.
+
+- `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
+  match criteria in the same way as in `query_by` method. Just like `query_by` method,
+  values of specified fields are yielded to the block. Such `sift_by` definitions
+  may be nested in any depth.
+
+- `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
+  not be called if query is initialized with a given scope.
+
+- `defaults(hash)` method is used to declare default query params that are reverse
+  merged with params passed on query initialization. When used in `sift_by` block,
+  hashes are merged altogether.
+
+- `guard(&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.
+
+#### Instance Methods
+
+- `initialize(params, scope: nil, **attributes)` initializes a query with `params`,
+  an optional scope (that if passed, is used instead of `base_scope`). All additionally
+  passed options are accessible via reader methods in query blocks and elsewhere.
+
+- `params` returns a parameters passed in initialization. Is a `Hashie::Mash` instance,
+  thus, values can be accessible via reader methods.
+
+- `[](key)` delegates to query `params` for slightly easier values access.
+
+- `scope` "current" scope of query object. For an initialized query object corresponds
+  to base scope. Primary usage is to call this method in `query_by` blocks and return
+  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
+  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.
+
+### Usage example with ActiveRecord Relation as a scope
+
+```ruby
+class UserQuery < Parascope::Query
+  defaults only_active: true
+
+  base_scope { company.users }
+
+  query_by :only_active do
+    scope.active
+  end
+
+  query_by :birthdate do |date|
+    scope.by_birtdate(date)
+  end
+
+  query_by :name do |name|
+    scope.where("CONCAT(first_name, ' ', last_name) LIKE ?", "%#{name}%")
+  end
+
+  sift_by :sort_column, :sort_direction do |scol, sdir|
+    guard { sdir.to_s.downcase.in?(%w(asc desc)) }
+
+    base_scope { |scope| scope.order(scol => sdir) }
+
+    query_by(:sort_direction, sort_column: 'name') do |sdir|
+      scope.reorder("CONCAT(first_name, ' ', last_name) #{sdir}")
+    end
+  end
+
+  sift_by :with_projects do
+    base_scope { |scope| scope.joins(:projects) }
+
+    query_by :project_name do |name|
+      scope.where(projects: {name: name})
+    end
+  end
+
+  def users
+    @users ||= resolved_scope
+  end
+
+  def project_users
+    @project_users ||= resolved_scope(with_projects: true)
+  end
+end
+
+params = {name: 'John', sort_column: 'name', sort_direction: 'DESC', project_name: 'ExampleApp'}
+
+query = UserQuery.new(params, company: some_company)
+
+query.project_users # => this is the same as:
+# some_company.users
+#   .active
+#   .joins(:projects)
+#   .where("CONCAT(first_name, ' ', last_name) LIKE ?", "%John%")
+#   .where(projects: {name: 'ExampleApp'})
+#   .order("CONCAT(first_name, ' ', last_name) DESC")
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/akuzko/parascope.
+
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "parascope"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require 'ostruct'
+
+class Query < Parascope::Query
+  defaults barbak: 'barbak'
+
+  base_scope { OpenStruct.new }
+
+  query_by :foo do |foo|
+    guard { foo == 'foo' }
+
+    scope.tap{ scope.foo = foo }
+  end
+
+  query_by bar: 'bar' do
+    scope.tap{ scope.bar = 'bar' }
+  end
+
+  sift_by baz: 'baz' do |baz|
+    defaults bakbar: 'bakbar'
+
+    guard { upcase(baz) == 'BAZ' }
+
+    base_scope { |scope| scope.tap{ scope.baz = 'baz' } }
+
+    query_by :bak do |bak|
+      scope.tap{ scope.bak = bak }
+    end
+
+    query_by :barbak do |barbak|
+      scope.tap{ scope.barbak = barbak }
+    end
+
+    sift_by :nested_baz do |nested_baz|
+      query_by :bakbar do |bakbar|
+        scope.tap{ scope.bakbar = [baz, nested_baz, bakbar].join('-') }
+      end
+    end
+  end
+
+  def upcase(str)
+    str.upcase
+  end
+end
+
+q = Query.new(foo: 'foo', bar: 'bar', baz: 'baz', bak: 'bak', nested_baz: 'nb')
+
+require "pry"
+Pry.start
+
+# require "irb"
+# IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/parascope.rb

@@ -0,0 +1,5 @@
+require "parascope/version"
+
+module Parascope
+  autoload :Query, "parascope/query"
+end

data/lib/parascope/query.rb

@@ -0,0 +1,144 @@
+require "hashie/mash"
+
+module Parascope
+  class Query
+    autoload :ApiMethods, "parascope/query/api_methods"
+    autoload :ApiBlock, "parascope/query/api_block"
+
+    extend Forwardable
+    extend ApiMethods
+
+    UndefinedScopeError = Class.new(StandardError)
+    UnpermittedError = Class.new(ArgumentError)
+
+    attr_reader :params
+    def_delegator :params, :[]
+
+    def self.inherited(subclass)
+      subclass.query_blocks.replace query_blocks.dup
+      subclass.sift_blocks.replace sift_blocks.dup
+      subclass.guard_blocks.replace guard_blocks.dup
+      subclass.base_scope(&base_scope)
+      subclass.defaults defaults
+    end
+
+    def initialize(params, scope: nil, **attrs)
+      @params = Hashie::Mash.new(klass.defaults).merge(params || {})
+      @scope  = scope unless scope.nil?
+      @attrs  = attrs
+      define_attr_readers
+    end
+
+    def scope
+      @scope ||= base_scope
+    end
+
+    def base_scope
+      scope = klass.ancestors
+        .select{ |klass| klass < Query }
+        .reverse
+        .map(&:base_scope)
+        .compact
+        .reduce(nil){ |scope, block| instance_exec(scope, &block) }
+
+      if scope.nil?
+        fail UndefinedScopeError, "failed to build scope. Have you missed base_scope definition?"
+      end
+
+      scope
+    end
+
+    def resolved_scope(params = nil)
+      return sifted_instance.resolved_scope! if params.nil?
+
+      clone_with_params(params).resolved_scope
+    end
+
+    def klass
+      sifted? ? singleton_class : self.class
+    end
+
+    protected
+
+    attr_writer :scope, :params
+    attr_accessor :block
+    attr_reader :attrs
+
+    def sifted_instance
+      block = klass.sift_blocks.find{ |block| block.fits?(params) }
+
+      block ? sifted_instance_for(block) : self
+    end
+
+    def resolved_scope!
+      guard_all
+      klass.query_blocks.sort{ |a, b| a.index <=> b.index }.reduce(scope) do |scope, block|
+        clone_with_scope(scope, block).apply_block!.scope
+      end
+    end
+
+    def apply_block!
+      if block && block.fits?(params)
+        scope  = instance_exec(*block.values_for(params), &block.block)
+        @scope = scope unless scope.nil?
+      end
+      self
+    end
+
+    def sifted!(block, query)
+      @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)
+      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
+    end
+
+    def clone_with_scope(scope, block)
+      clone.tap do |query|
+        query.scope = scope
+        query.block = block
+      end
+    end
+
+    def clone_with_params(other_params)
+      clone.tap do |query|
+        query.params = params.merge(other_params)
+      end
+    end
+
+    def clone_with_sifter(block)
+      dup.tap do |query|
+        query.sifted!(block, self)
+      end
+    end
+
+    def sifted?
+      !!@sifted
+    end
+
+    def sifted_instance_for(block)
+      clone_with_sifter(block).sifted_instance
+    end
+
+    def define_attr_readers
+      @attrs.each do |name, value|
+        define_singleton_method(name){ value }
+      end
+    end
+  end
+end

data/lib/parascope/query/api_block.rb

@@ -0,0 +1,23 @@
+module Parascope
+  class Query::ApiBlock < Struct.new(:presence_fields, :value_fields, :block, :index)
+    def fits?(params)
+      values_for(params).all?{ |value| present?(value) }
+    end
+
+    def values_for(params)
+      params.values_at(*presence_fields) + valued_values_for(params)
+    end
+
+    def present?(value)
+      value.respond_to?(:empty?) ? !value.empty? : !!value
+    end
+
+    private
+
+    def valued_values_for(params)
+      value_fields.map do |field, required_value|
+        params[field] == required_value && required_value
+      end
+    end
+  end
+end

data/lib/parascope/query/api_methods.rb

@@ -0,0 +1,41 @@
+module Parascope
+  module Query::ApiMethods
+    def base_scope(&block)
+      return @base_scope unless block_given?
+
+      @base_scope = block
+    end
+
+    def defaults(params = nil)
+      @defaults ||= {}
+
+      return @defaults if params.nil?
+
+      @defaults = @defaults.merge(params)
+    end
+
+    def sift_by(*presence_fields, **value_fields, &block)
+      sift_blocks.push Query::ApiBlock.new(presence_fields, value_fields, block)
+    end
+
+    def query_by(*presence_fields, index: 0, **value_fields, &block)
+      query_blocks.push Query::ApiBlock.new(presence_fields, value_fields, block, index)
+    end
+
+    def guard(&block)
+      guard_blocks.push block
+    end
+
+    def sift_blocks
+      @sift_blocks ||= []
+    end
+
+    def query_blocks
+      @query_blocks ||= []
+    end
+
+    def guard_blocks
+      @guard_blocks ||= []
+    end
+  end
+end

data/lib/parascope/version.rb

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

data/parascope.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'parascope/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "parascope"
+  spec.version       = Parascope::VERSION
+  spec.authors       = ["Artem Kuzko"]
+  spec.email         = ["a.kuzko@gmail.com"]
+
+  spec.summary       = %q{Builds a params-sifted scope}
+  spec.description   = %q{Parascope::Query class provides a way to dynamically
+    apply scopes or ActiveRecord query methods based on passed params with a
+    declarative and convenient API}
+  spec.homepage      = "https://github.com/akuzko/parascope"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = '>= 2.1.0'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "hashie"
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-nav"
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: parascope
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Artem Kuzko
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-05-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |-
+  Parascope::Query class provides a way to dynamically
+      apply scopes or ActiveRecord query methods based on passed params with a
+      declarative and convenient API
+email:
+- a.kuzko@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/parascope.rb
+- lib/parascope/query.rb
+- lib/parascope/query/api_block.rb
+- lib/parascope/query/api_methods.rb
+- lib/parascope/version.rb
+- parascope.gemspec
+homepage: https://github.com/akuzko/parascope
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Builds a params-sifted scope
+test_files: []