convenient_grouper 0.1.6

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OTlmMjVmYzk2YmQwYTk5NTc3NTk4YzM5NWM4NDZmMmY3YjcxZjI4MA==
+  data.tar.gz: !binary |-
+    MmYxYjAxOWE0MzM4ODhiMTIwYTJlM2M0MGEyN2JmNjE3ZTQzMTZjZA==
+SHA512:
+  metadata.gz: !binary |-
+    NmE5MDBhYjRjYTY5ZjYxZGY5YTU0N2Y2OTJlMGM1NjcwMWU1OTRjYWM5NmQ4
+    Y2Y5NjEwZjk3OThmNWQ3Y2FlYWQ1YTYxNzhlMjQzOWZkY2E0MGUxNzliYWM0
+    OTE0MDZkYzRjZmQ4ODNiYjRhNDAxN2RiZTUxOTcxMjliNzkxMjU=
+  data.tar.gz: !binary |-
+    Y2E1OWJkNThkNzNlM2FkODU2MjAxNmE2YWNjMzI3ZTIxYzVhNGQwYjBhNzA5
+    ZjYyN2Y2MzI1ZjI0NTVhZjIwNjc0MzdiMDg2MjkzNTY1NmVlNzI5MTZlOTFh
+    Mzg2MjI2MzMwZmE2NTJiMzdlYTEzNjc4ZmNmMmFjMzNkMjY4Njc=

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.swp

data/.ruby-gemset

@@ -0,0 +1 @@
+convenient_grouper

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.2.0
+env: RAKE_ENV=test RAILS_ENV=test
+before_install:
+  - 'gem install bundler'
+script:
+  - 'bundle exec rspec'
+notifications:
+  email:
+    recipients:
+      - humzashah+travis@gmail.com
+    on_success: never
+    on_failure: always

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 TODO: Write your name
+
+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,121 @@
+# ConvenientGrouper
+
+This gem simplifies grouping records. The primary intention is to make group-aggregation-methods easier.
+
+To use, add the following to your Gemfile.
+
+```ruby
+gem 'convenient_grouper'
+```
+
+After `bundle install`, you can provide the grouping details as a hash with the column as the hash's key.
+
+### Usage:
+
+```ruby
+ModelName.group(grouping_hash, options)
+```
+
+First argument to method is a grouping hash:
+
+```ruby
+grouping_hash = {
+  column_name: {
+    group_name_one: a_range_or_array, # group if column value within range/array
+    group_name_two: a_specific_value, # group if column value equals
+
+    # comparison operators: !=, <, <=, >, >=
+    # work best for values whose to_s does not yield spaces
+    group_name_four: "!= #{some_value_one}",
+    group_name_five: "> #{some_value_two}",
+    group_name_six: "<= #{some_value_three}",
+
+    # default group
+    nil => some_string # default value is 'others'
+  }
+}
+```
+
+Second argument is an optional hash:
+
+```ruby
+options = {
+  restrict: boolean # restrict query to grouped conditions. defaults to false.
+}
+```
+
+If you pass only one non-hash argument, you will be using `ActiveRecord`'s own `group` method.
+
+### Example 1
+
+Getting profits for different dates and date-ranges from a `Sale` model:
+
+```ruby
+Sale.group({
+  date_of_sale: {
+    Jan: Date.new(2015, 1)..Date.new(2015, 1, 31),
+    date: Date.new(2014, 4, 5),
+    dates: [Date.new(2014, 1, 2), Date.new(2014, 2, 1)],
+    unspecified: nil
+  }
+}).sum(:profit)
+#=> {"Jan" => 1550, "date" => 50, "dates" => 100, "unspecified" => 25, "others" => 50000}
+```
+
+### Example 2
+
+Counting employees in various age-groups:
+
+```ruby
+Employee.group({
+  age: {
+    young_adults: 18..25,
+    adults: 25..35,
+    seniors: ">= 60",
+    nil => 'mature_adults'
+  }
+}).count
+#=> {"young_adults" => 13, "adults" => 15, "seniors" => 4, "mature_adults" => 5}
+```
+
+### Example 3
+
+Grouping events that are occurring after a particular date:
+
+```ruby
+date = Date.new(2015, 6, 22)
+Event.group(date: {
+  not_on_date: ">= #{date}"
+})
+```
+
+### Example 4
+
+Restricting your query to the conditions specified in your `group` clause:
+
+```ruby
+range = 13..19
+Relative.group({
+  age: {teens: range}
+}, restrict: true) # == Employee.where(age: range).group(hash)
+```
+
+### Heads-Up
+
+A heads-up for specifying the extra options such as `restrict`:
+
+Ruby will interpret the following as a single hash-argument:
+
+```ruby
+Relative.group(age: {teens: 13..19}, restrict: true) # wrong
+```
+
+Therefore you will need appropriate curly braces:
+
+```ruby
+Relative.group({age: {teens: 13..19}}, {restrict: true}) # right
+```
+
+### Bug Reports
+
+Things seemingly work well for the most usual use-cases. Nonetheless, bug-reports are welcomed.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "convenient_grouper"
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install

data/convenient_grouper.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'convenient_grouper/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "convenient_grouper"
+  spec.version       = ConvenientGrouper::VERSION
+  spec.authors       = ["Syed Humza Shah"]
+  spec.email         = ["humzashah+github@gmail.com"]
+
+  spec.summary       = "Use Ruby hashes to group database table rows through ActiveRecord."
+  spec.homepage      = "https://github.com/humzashah/convenient_grouper"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 1.9.3'
+
+  spec.add_development_dependency "bundler", ">= 1.8"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "activerecord", ">= 4.0"
+  spec.add_development_dependency "rspec"
+end

data/lib/convenient_grouper.rb

@@ -0,0 +1,45 @@
+require "active_record"
+require "convenient_grouper/hash_converter"
+require "convenient_grouper/version"
+
+module ConvenientGrouper
+  module_function
+
+  def preliminaries(hash_arg, opts)
+    hc = get_hash_converter(hash_arg, opts)
+
+    {
+      groups: get_groups(hc, hash_arg),
+      restrictions: get_restrictions(hc)
+    }
+  end
+
+  private
+  module_function
+
+  def get_hash_converter(hash_arg, opts)
+    return unless hash_arg.is_a?(Hash)
+    ConvenientGrouper::HashConverter.new(hash_arg, opts)
+  end
+
+  def get_groups(hc, hash_arg)
+    hc.try(:groups) || hash_arg
+  end
+
+  def get_restrictions(hc)
+    hc.try(:restrictions) || ""
+  end
+end
+
+ActiveRecord::Relation.class_eval do
+  define_method :group do |hash_arg, opts={}|
+    if hash_arg.is_a?(Hash)
+      hash = ConvenientGrouper.preliminaries(hash_arg, opts)
+      groups = hash[:groups]
+      restrictions = hash[:restrictions]
+      super(groups).where(restrictions)
+    else
+      super(hash_arg)
+    end
+  end
+end

data/lib/convenient_grouper/error.rb

@@ -0,0 +1,4 @@
+module ConvenientGrouper
+  class Error < StandardError
+  end
+end

data/lib/convenient_grouper/hash_converter.rb

@@ -0,0 +1,144 @@
+require_relative "error"
+require_relative "regex"
+
+module ConvenientGrouper
+  class HashConverter
+    attr_reader :groups, :restrictions
+
+    module Default
+      GROUP = 'others'
+
+      OPTIONS = {
+        restrict: false
+      }
+    end
+
+    private
+
+    def initialize(hash_arg, options=Default::OPTIONS)
+      @hash = hash_arg
+      validate_hash
+
+      @options = options
+      validate_options
+
+      @restrict = (@options[:restrict] == true)
+
+      create_groups
+      create_restrictions
+    end
+
+    def validate_hash
+      raise_error("Incompatible hash: #{@hash}.") unless matches_conditions?
+    end
+
+    def validate_options
+      valid_keys = Default::OPTIONS.keys
+      invalid_keys = @options.keys - valid_keys
+      return if valid = invalid_keys.empty?
+
+      valid_keys_str = valid_keys.join(', ')
+      invalid_keys_str = invalid_keys.join(', ')
+      raise_error "You provided invalid options: #{invalid_keys_str}. Supported options include: #{valid_keys_str}."
+    end
+
+    def matches_conditions?
+      @hash.is_a?(Hash) &&
+      (@hash.each_key.count == 1) &&
+      @hash.each_value.all? { |v| v.is_a?(Hash) }
+    end
+
+    def create_groups
+      @groups = "CASE #{[*cases, default_group].compact.join(' ')} END"
+    end
+
+    def create_restrictions
+      @restrictions =
+        if @restrict
+          parse_hash do |column, _, value|
+            column_value_matcher(column, value)
+          end.join(' OR ')
+        end || ""
+    end
+
+    def cases
+      parse_hash do |column, group, value|
+        "WHEN #{column_value_matcher(column, value)} THEN '#{group}'"
+      end
+    end
+
+    def parse_hash
+      @hash.each_with_object([]) do |(column, values_hash), array|
+        values_hash.each do |group, value|
+          array << yield(column, group, value) if group
+        end
+      end
+    end
+
+    def column_value_matcher(column, value)
+      "(#{column} #{lookup_str(value)})"
+    end
+
+    def default_group
+      hash = @hash.values.first
+      group = hash[nil] || Default::GROUP
+      "ELSE '#{group}'"
+    end
+
+    def lookup_str(value)
+      case value
+      when Range
+        range_str(value)
+      when Array
+        array_str(value)
+      when lambda { |x| Regex.matches?(x) }
+        value
+      when Numeric, String
+        value_str(value)
+      when NilClass
+        'IS NULL'
+      else
+        raise_error("Unsupported type #{value.class.name} for #{value}.")
+      end
+    end
+
+    def range_str(range)
+      validate_range(range)
+
+      min = insert_val(range.min)
+      max = insert_val(range.max)
+
+      "BETWEEN #{min} AND #{max}"
+    end
+
+    def validate_range(range)
+      min = range.min
+      max = range.max
+
+      valid = min && max && (min < max)
+      raise_error("Improper range: #{range}.") unless valid
+    end
+
+    def array_str(array)
+      mapped_str = array.map { |v| insert_val(v) }.join(', ')
+      "IN (#{mapped_str})"
+    end
+
+    def value_str(value)
+      "= #{insert_val(value)}"
+    end
+
+    def insert_val(value)
+      if value.is_a?(Numeric)
+        value
+      else
+        "'#{value.to_s}'"
+      end
+    end
+
+    def raise_error(msg)
+      raise Error.new(msg)
+    end
+
+  end
+end

data/lib/convenient_grouper/regex.rb

@@ -0,0 +1,20 @@
+module ConvenientGrouper
+  module Regex
+
+    module Expression
+      COMPARISON = /^[<, >]={0,1}\s.+$/ # e.g. '> 1' and '<= 4'
+      INEQUALITY = /!=.+/ # e.g. "!= 4" and "!= 'one'"
+      NOT_NULL = /^IS NOT NULL$/i
+    end
+
+    ALL_EXPRESSIONS = Expression.constants.map { |symbol| Expression.const_get(symbol) }
+
+    module_function
+    def matches?(value)
+      value.is_a?(String) &&
+      ALL_EXPRESSIONS.any? do |expression|
+        expression.match(value.strip)
+      end
+    end
+  end
+end

data/lib/convenient_grouper/version.rb

@@ -0,0 +1,3 @@
+module ConvenientGrouper
+  VERSION = "0.1.6"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: convenient_grouper
+version: !ruby/object:Gem::Version
+  version: 0.1.6
+platform: ruby
+authors:
+- Syed Humza Shah
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: 
+email:
+- humzashah+github@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .ruby-gemset
+- .ruby-version
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- convenient_grouper.gemspec
+- lib/convenient_grouper.rb
+- lib/convenient_grouper/error.rb
+- lib/convenient_grouper/hash_converter.rb
+- lib/convenient_grouper/regex.rb
+- lib/convenient_grouper/version.rb
+homepage: https://github.com/humzashah/convenient_grouper
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: Use Ruby hashes to group database table rows through ActiveRecord.
+test_files: []