hash-to-conditions 0.3.3

data/lib/ext/array.rb

@@ -0,0 +1,10 @@
+require 'helpers/array_helper'
+
+class Array
+
+  # Extends Array with a convenience method to HashToConditions::ArrayHelper
+  def to_condition
+    HashToConditions::ArrayHelper.new(self).to_condition
+  end
+end
+

data/lib/ext/hash.rb

@@ -0,0 +1,10 @@
+require 'helpers/hash_helper'
+
+class Hash
+
+  # Extends Hash with a convenience method to HashToConditions::HashHelper
+   def to_conditions
+    HashToConditions::HashHelper.new(self).to_conditions
+  end
+end
+

data/lib/ext/string.rb

@@ -0,0 +1,10 @@
+require 'helpers/string_helper'
+
+class String
+
+  # Extends String with a convenience method to HashToConditions::StringHelper
+  def to_operator
+    HashToConditions::StringHelper.new(self).to_operator
+  end
+end
+

data/lib/hash_to_conditions.rb

@@ -0,0 +1,121 @@
+require 'ext/array'
+require 'ext/hash'
+require 'ext/string'
+
+# The HashToConditions gem provides an easy way to build ActiveRecord Array conditions
+# directly from a Hash.
+#
+# A simple example:
+#  > {'age.gt' => 18}.to_conditions => ['(age>?)', 18] 
+#
+# The *age* field is marked up with the *.gt* operator tag, which is processed by the
+# +to_conditions+ method in order to produce the result Array condition.
+#
+# More practical conditions can be constructed through the use of operator tags in combination
+# with the *AND* and *OR* boolean operators.
+#
+# Below is a list of supported tags:
+#
+# <table style=\"border-collapse:collapse; border: 1px solid \#999\">
+# <tr>
+# <th style=\"border: 1px solid \#999; width: 80px\">Tag</th>
+# <th style=\"border: 1px solid \#999; width: 150px\">SQL equivalent</th>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.eq</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">=</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.ne</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\<\></td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.gt</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\></td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.ge</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\>=</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.lt</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\<</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.le</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\<=</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.like</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">LIKE</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.null</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">IS NULL</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.nnull</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">IS NOT NULL</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.in</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">IN</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">.between</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">BETWEEN</td>
+# </tr>
+# </table>
+#
+# Examples:
+#
+#  > h = {'AND' => {'name.eq' => 'Ruby', 'version.ge' => 1.9}}
+#  > h.to_conditions => ['(name=? AND version>=?)', 'Ruby', 1.9] 
+#
+#  > h = {'OR' => {'name.like' => 'Lou%', 'age.gt' => 18}}
+#  > h.to_conditions => ['(name LIKE ? OR age>?)', 'Lou%', 18] 
+#
+# Hash keys are not limited to String. Symbol keys are also supported so :'name.eq' is also valid.
+#
+# == Implicit Tags
+#
+# *.eq* and *.like* are implicit tags. Implicit means the tag can be omitted so the following are
+# equivalent:
+#
+#  > {'name.like' => 'Lou%'}.to_conditions => ['(name LIKE ?)', 'Lou%']
+#  > {'name' => 'Lou%'}.to_conditions => ['(name LIKE ?)', 'Lou%']
+#
+# Similarly,
+#
+#  > {'name.eq' => 'Ruby', 'version.eq' => 1.9}.to_conditions => ["(name=? AND version=?)", "Ruby", 1.9]
+#  > {'name' => 'Ruby', 'version' => 1.9}.to_conditions => ["(name=? AND version=?)", "Ruby", 1.9]
+#
+# Note the *AND* boolean operator is omitted in the hashes above. It also is an implicit
+# operator, except when used as a nested condition.
+#
+# Having these as implicits seem natural and can help save a few extra key-strokes.
+#
+# == Nested Conditions
+#
+# Nested conditions allow more complex queries to be constructed.
+#
+# For example:
+#
+#  > nested_h = {'name' => 'Lou%', 'age.gt' => 18}
+#  > h = {'OR' => {'AND' => nested_h, 'salary.between' => '50k, 100k'}}
+#  > h.to_conditions => ['((name LIKE ? AND age>?) OR salary BETWEEN ? AND ?)', 'Lou%', 18, '50k', '100k'] 
+#
+# However, one can easily get into trouble nesting with hashes. It is easy to create many nestings or
+# a cyclic one. Therefore nesting is limited to a maximum of 42 within a root hash. An
+# exception with *nested_too_deep_or_cyclic* message is raised when this limit is exceeded.
+#
+# <br />
+# ---
+# Copyright (c) 2013 Long On, released under the MIT license
+
+module HashToConditions
+
+class HashToConditions
+end
+
+end

data/lib/helpers/array_helper.rb

@@ -0,0 +1,69 @@
+module HashToConditions
+
+# This helper class takes a Hash key-value pair (an Array) and return the expanded form condition.
+#
+# For example:
+#  > helper = ArrayHelper.new(['age.gt', 18])
+#  > helper.to_condition => ['age>?', 18] 
+
+class ArrayHelper
+
+  # Returns an expanded form condition or a Hash if it is a nested condition.
+  #
+  # An exception is raised when specific validation fails. Possible exception messages are:
+  #
+  # * '*bad_key_value_pair*' - array must have exactly two (2) elements
+  # * '*field_cannot_be_empty*' - a field name must be specified
+  # * '*unknown_operator*' - operator tag is not supported
+  def to_condition
+    raise "bad_key_value_pair" unless @array.length == 2
+
+    parts = @array.first.to_s.split('.')
+    raise "field_cannot_be_empty" if parts.empty?
+
+    field = parts[0].strip
+    operator = parts[1]
+    value = @array.last
+
+    if ['AND', 'OR'].index(field.upcase)
+      # handle nested condition
+      return {field.upcase => value}
+    end
+
+    unless operator
+      # handle implicit .eq ({'name' => 'value'}) or .like ({'name' => 'value%'})
+      operator = value.to_s.index('%') ? 'like' : 'eq'
+    end
+    operator = operator.downcase
+    mapped = operator.to_operator
+    raise "unknown_operator" unless mapped
+
+    # handle .null or .nnull, suppress value
+    return  [field + mapped] if operator.index('null')
+
+    # handle .in (?) or .between ? and ?
+    if ['in', 'between'].index(operator)
+      values = value.to_s.split(',').collect { | ea | ea.strip }
+      if 'in' == operator
+        result = [field + mapped, values]
+      else
+        # between
+        result = [field + mapped, values[0], values[1]]
+      end
+      return result
+    end
+
+    [field + mapped, value]
+  end
+
+
+  protected
+
+   # Creates a new instance
+   def initialize(array)
+      @array = array
+    end
+end
+
+end
+

data/lib/helpers/hash_helper.rb

@@ -0,0 +1,85 @@
+module HashToConditions
+
+# This class performs the bulk of the work. It takes a Hash and return the fully
+# expanded Array condition.
+#
+# For example:
+#  > helper = HashHelper.new({'age.gt' => 18})
+#  > helper.to_conditions => ['(age>?)', 18] 
+#
+# Boolean *AND* and *OR* can be used to join multiple conditions.
+#
+# Examples:
+#
+#  > helper = HashHelper.new({'AND' => {'name' => 'Lou%', 'age.gt' => 18}})
+#  > helper.to_conditions => ['(name LIKE ? AND age>?)', 'Lou%', 18] 
+#
+#  > helper = HashHelper.new({'name.like' => 'Lou%', 'age.gt' => 18}) - boolean AND is implicit here
+#  > helper.to_conditions => ['(name LIKE ? AND age>?)', 'Lou%', 18] 
+#
+#  > helper = HashHelper.new({'OR' => {'name.like' => 'Lou%', 'age.gt' => 18}})
+#  > helper.to_conditions => ['(name LIKE ? OR age>?)', 'Lou%', 18] 
+#
+# Nested conditions are also supported:
+#
+#  > nested_h = {'name' => 'Lou%', 'age.gt' => 18}
+#  > helper = HashHelper.new({'OR' => {'AND' => nested_h, 'salary.between' => '50k, 100k'}})
+#  > helper.to_conditions => ['((name LIKE ? AND age>?) OR salary BETWEEN ? AND ?)', 'Lou%', 18, '50k', '100k'] 
+#
+
+class HashHelper
+
+  # Returns a fully expaned condition array
+  #
+  def to_conditions
+    raise "empty_condition" if @hash.empty?
+    result_s = ''
+    result_a = []
+    join_s = @hash.first.first
+    if ['AND', 'OR'].index(join_s.upcase)
+      parse(@hash.first.last, join_s.upcase, result_s, result_a)
+    else
+      parse(@hash, 'AND', result_s, result_a)
+    end
+    result_a.unshift(result_s)
+    result_a
+  end
+
+
+  protected
+
+    # Performs the translation. Parse @hash, construct the condition @result_s string using boolean
+    # operator @join_s. Collect @result_s and condition values in @result_a. An exception is raised,
+    # *nested_too_deep_or_cyclic*, when nesting exceeds 42 recursive calls.
+    def parse(hash, join_s, result_s, result_a, nest_lev=0)
+      raise "nested_too_deep_or_cyclic" unless nest_lev < 42
+
+      result_s << '('
+      count = hash.length
+      hash.each_pair { | pair |
+        arr = pair.to_condition
+        if arr.kind_of?(Hash)
+          # handle nested condition
+          parse(arr.first.last, arr.first.first, result_s, result_a, 1+nest_lev)
+        else
+          result_s << arr.shift
+          result_a.concat(arr)
+        end
+        count -= 1
+        if count > 0
+          result_s << ' '
+          result_s << join_s
+          result_s << ' '
+        end
+      }
+      result_s << ')'
+    end
+
+   # Creates a new instance
+    def initialize(hash)
+      @hash = hash
+    end
+end
+
+end
+

data/lib/helpers/string_helper.rb

@@ -0,0 +1,93 @@
+module HashToConditions
+
+# This helper class takes an operator tag and convert it to an equivalent SQL operator.
+#
+# For example:
+#  > helper = StringHelper.new('null')
+#  > helper.to_operator => ' IS NULL'
+#
+# Supported operator tags:
+#
+# <table style=\"border-collapse:collapse; border: 1px solid \#999\">
+# <tr>
+# <th style=\"border: 1px solid \#999; width: 80px\">Tag</th>
+# <th style=\"border: 1px solid \#999; width: 100px\">Output</th>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">eq</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">=</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">ne</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\<\></td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">gt</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\></td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">ge</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\>=</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">lt</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\<</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">le</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">\<=</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">like</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">LIKE</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">null</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">IS NULL</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">nnull</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">IS NOT NULL</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">in</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">IN</td>
+# </tr>
+# <tr>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">between</td>
+# <td style=\"border: 1px solid \#999; padding-left: 4px\">BETWEEN</td>
+# </tr>
+# </table>
+
+class StringHelper
+  @@operators = {
+        'eq' => '=?',
+        'ne' => '<>?',
+        'gt' => '>?',
+        'ge' => '>=?',
+        'lt' => '<?',
+        'le' => '<=?',
+        'like' => ' LIKE ?',
+        'null' => ' IS NULL',
+        'nnull' => ' IS NOT NULL',
+        'in' => ' IN (?)',
+        'between' => ' BETWEEN ? AND ?'
+      }
+
+
+  # Returns a matching SQL operator for @string, or nil if none found.
+  def to_operator
+    @@operators[@string.downcase]
+  end
+
+
+  protected
+
+    # Creates a new instance
+    def initialize(string)
+      @string = string
+    end
+end
+
+end
+

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: hash-to-conditions
+version: !ruby/object:Gem::Version
+  version: 0.3.3
+  prerelease: 
+platform: ruby
+authors:
+- Long On
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-31 00:00:00.000000000 Z
+dependencies: []
+description: The HashToConditions gem provides an easy way to build ActiveRecord Array
+  conditions directly from a Hash.
+email: on.long.on@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/hash_to_conditions.rb
+- lib/helpers/string_helper.rb
+- lib/helpers/array_helper.rb
+- lib/helpers/hash_helper.rb
+- lib/ext/array.rb
+- lib/ext/string.rb
+- lib/ext/hash.rb
+homepage: https://rubygems.org/gems/hash-to-conditions
+licenses: []
+post_install_message: 
+rdoc_options: []
+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: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Converts a Hash to ActiveRecord Array conditions
+test_files: []