query_string_interface 0.1.0

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+gemspec
+
+gem "rake", "0.8.7"
+gem "i18n"
+
+platforms :mri_18 do
+  gem "ruby-debug"
+end
+
+platforms :mri_19 do
+  gem "ruby-debug19", :require => 'ruby-debug' if RUBY_VERSION < "1.9.3"
+  gem 'simplecov', :require => false
+end
+

data/Gemfile.lock

@@ -0,0 +1,61 @@
+PATH
+  remote: .
+  specs:
+    query_string_interface (0.1.0)
+      activesupport (>= 3.0.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.1.0)
+      multi_json (~> 1.0)
+    archive-tar-minitar (0.5.2)
+    columnize (0.3.4)
+    diff-lcs (1.1.3)
+    i18n (0.6.0)
+    linecache (0.46)
+      rbx-require-relative (> 0.0.4)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    multi_json (1.0.3)
+    rake (0.8.7)
+    rbx-require-relative (0.0.5)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+    simplecov (0.5.3)
+      multi_json (~> 1.0.3)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  i18n
+  query_string_interface!
+  rake (= 0.8.7)
+  rspec (>= 2.6.0)
+  ruby-debug
+  ruby-debug19
+  simplecov

data/MIT_LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Vicente Mundim
+
+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.rdoc

@@ -0,0 +1,44 @@
+= Overview
+
+== About QueryStringInterace
+
+This gem extracts params given as a hash to structured data, that can be used when creating queries
+
+== Repository
+
+http://github.com/vicentemundim/query_string_interface
+
+= Installing
+
+This is a gem, so you can install it by:
+
+  sudo gem install query_string_interface
+
+Or, if you are using rails, put this in your Gemfile:
+
+  gem 'query_string_interface'
+
+= Usage
+
+To use it, just extend QueryStringInterface in your document model:
+
+  class Document
+    include Mongoid::Document
+    extend QueryInterfaceString
+
+    # ... add fields here
+  end
+
+Then, you can use some class methods with your ORM syntax:
+
+  def self.filter_by(params)
+    where(filtering_options(params)).order_by(*sorting_options(params))
+  end
+
+= ORM Adapters
+
+http://github.com/vicentemundim/mongoid_query_string_interface
+
+= Credits
+
+Vicente Mundim: vicente.mundim at gmail dot com

data/lib/query_string_interface.rb

@@ -0,0 +1,69 @@
+require "active_support/json"
+require "active_support/core_ext/hash/indifferent_access"
+
+module QueryStringInterface
+  NORMAL_CONDITIONAL_OPERATORS = [:exists, :gte, :gt, :lte, :lt, :ne, :size, :near, :within]
+  ARRAY_CONDITIONAL_OPERATORS = [:all, :in, :nin]
+  CONDITIONAL_OPERATORS = ARRAY_CONDITIONAL_OPERATORS + NORMAL_CONDITIONAL_OPERATORS
+  SORTING_OPERATORS = [:asc, :desc]
+  OR_OPERATOR = :or
+
+  OPERATORS = CONDITIONAL_OPERATORS + SORTING_OPERATORS + [OR_OPERATOR]
+
+
+  ATTRIBUTE_REGEX = /^(.*)\.(#{(OPERATORS).join('|')})$/
+  OPERATOR_REGEX = /^.*\.(#{CONDITIONAL_OPERATORS.join('|')})$/
+
+  ORDER_BY_PARAMETER = :order_by
+  PAGINATION_PARAMTERS = [:per_page, :page]
+  FRAMEWORK_PARAMETERS = [:controller, :action, :format]
+  CONTROL_PARAMETERS = [:disable_default_filters]
+  RESERVED_PARAMETERS = FRAMEWORK_PARAMETERS + PAGINATION_PARAMTERS + [ORDER_BY_PARAMETER] + CONTROL_PARAMETERS
+
+  def default_filtering_options
+    {}
+  end
+
+  def default_sorting_options
+    []
+  end
+
+  def default_pagination_options
+    { :per_page => 12, :page => 1 }
+  end
+
+  def sorting_attributes_to_replace
+    {}
+  end
+
+  def filtering_attributes_to_replace
+    {}
+  end
+
+  def pagination_options(options={})
+    default_pagination_options.with_indifferent_access.merge(options)
+  end
+
+  def filtering_options(options={})
+    QueryStringInterface::FilterCollection.new(
+      only_filtering(options),
+      options.has_key?(:disable_default_filters) ? {} : default_filtering_options,
+      filtering_attributes_to_replace
+    ).parse
+  end
+
+  def sorting_options(options={})
+    QueryStringInterface::SortingFilters.new(options, default_sorting_options, sorting_attributes_to_replace).parse
+  end
+
+  def only_filtering(options={})
+    options.with_indifferent_access.except(*RESERVED_PARAMETERS)
+  end
+end
+
+require "query_string_interface/version"
+require "query_string_interface/helpers"
+require "query_string_interface/parsers"
+require "query_string_interface/filter"
+require "query_string_interface/filter_collection"
+require "query_string_interface/sorting_filters"

data/lib/query_string_interface/filter.rb

@@ -0,0 +1,148 @@
+require 'cgi'
+require 'json'
+
+module QueryStringInterface
+  class Filter
+    include QueryStringInterface::Helpers
+
+    attr_reader :raw_attribute, :raw_value
+
+    PARSERS = [
+      QueryStringInterface::Parsers::ArrayParser.new,
+      QueryStringInterface::Parsers::DateTimeParser.new,
+      QueryStringInterface::Parsers::NumberParser.new,
+      QueryStringInterface::Parsers::RegexParser.new,
+      QueryStringInterface::Parsers::BooleanAndNilParser.new
+    ]
+
+    def initialize(raw_attribute, raw_value, attributes_to_replace={}, raw_params={})
+      @raw_attribute = raw_attribute
+      @raw_value = raw_value
+      @attributes_to_replace = attributes_to_replace
+      @raw_params = raw_params
+    end
+
+    def attribute
+      @attribute ||= replaced_attribute_name(parsed_attribute, @attributes_to_replace).to_s
+    end
+
+    def value
+      @value ||= expanded_value
+    end
+
+    def operator
+      @operator ||= operator_from(raw_attribute)
+    end
+
+    def or_attribute?
+      raw_attribute == 'or'
+    end
+
+    def include?(other_filter)
+      if or_attribute?
+        json_value.any? do |filters|
+          filters.filter_parsers.any? do |filter_parser|
+            filter_parser.attribute == other_filter.attribute &&
+              conditional_array_operators.include?(filter_parser.operator) &&
+              filter_parser.operator == other_filter.operator
+          end
+        end
+      end
+    end
+
+    def merge(other_filter)
+      if or_attribute?
+        @value = json_value.map do |filters|
+          filters.filter_parsers << other_filter
+          filters.parse
+        end
+      elsif conditional_array_operators.include?(other_filter.operator) && operator == other_filter.operator
+        @value = value.inject({}) do |result, filter|
+          filter_operation, filter_value = filter
+          filter_value = filter_value.concat(other_filter.value[filter_operation]) if other_filter.value[filter_operation]
+          result[filter_operation] = filter_value
+          result
+        end
+      else
+        @value = value.merge(other_filter.value)
+      end
+    end
+
+    private
+      def parsed_attribute
+        if raw_attribute.respond_to?(:key)
+          raw_attribute.key.to_s
+        elsif or_attribute?
+          '$or'
+        elsif raw_attribute =~ QueryStringInterface::ATTRIBUTE_REGEX
+          $1
+        else
+          raw_attribute
+        end
+      end
+
+      def expanded_value
+        if operator
+          if or_attribute?
+            parsed_json_value
+          else
+            { operator => replaced_attribute_value(parsed_attribute, parsed_value, @attributes_to_replace, @raw_params) }
+          end
+        else
+          replaced_attribute_value(parsed_attribute, parsed_value, @attributes_to_replace, @raw_params)
+        end
+      end
+
+      def parsed_value
+        if raw_value.is_a?(String)
+          PARSERS.each do |parser|
+            return parser.parse(unescaped_raw_value) if parser.parseable?(unescaped_raw_value, operator)
+          end
+
+          return nil
+        else
+          raw_value
+        end
+      end
+
+      def parsed_json_value
+        if unescaped_raw_value.is_a?(String)
+          json_value.map(&:parse)
+        else
+          unescaped_raw_value
+        end
+      end
+
+      def json_value
+        raw_or_data = ActiveSupport::JSON.decode(unescaped_raw_value)
+
+        raise "$or query filters must be given as an array of hashes" unless valid_or_filters?(raw_or_data)
+
+        raw_or_data.map do |filters|
+          FilterCollection.new(filters, {}, @attributes_to_replace, @raw_params)
+        end
+      end
+
+      def valid_or_filters?(raw_or_data)
+        raw_or_data.is_a?(Array) and raw_or_data.all? { |item| item.is_a?(Hash) }
+      end
+
+      def unescaped_raw_value
+        @unescaped_raw_value ||= raw_value.is_a?(String) ? CGI.unescape(raw_value) : raw_value
+      end
+
+      def conditional_array_operators
+        QueryStringInterface::ARRAY_CONDITIONAL_OPERATORS.map { |o| "$#{o}" }
+      end
+
+      def operator_from(attribute)
+        if attribute.respond_to?(:operator)
+          "$#{attribute.operator}"
+        elsif or_attribute?
+          '$or'
+        elsif attribute =~ QueryStringInterface::OPERATOR_REGEX
+          "$#{$1}"
+        end
+      end
+  end
+end

data/lib/query_string_interface/filter_collection.rb

@@ -0,0 +1,73 @@
+module QueryStringInterface
+  class FilterCollection
+    include QueryStringInterface::Helpers
+
+    attr_reader :filters, :default_filters
+
+    def initialize(filters, default_filters={}, attributes_to_replace={}, raw_filters=nil)
+      @filters = filters.with_indifferent_access
+      @default_filters = default_filters.with_indifferent_access
+      @attributes_to_replace = attributes_to_replace.with_indifferent_access
+      @raw_filters = raw_filters.nil? ? @filters : raw_filters.with_indifferent_access
+    end
+
+    def parse
+      result = default_filters.inject({}) do |result, item|
+        raw_attribute, raw_value = item
+        result[replaced_attribute_name(raw_attribute, @attributes_to_replace).to_s] = replaced_attribute_value(raw_attribute, raw_value, @attributes_to_replace, @raw_filters)
+        result
+      end
+      result.merge(parsed_filters)
+    end
+
+    def filter_parsers
+      @filter_parsers ||= filters.map do |raw_attribute, raw_value|
+        Filter.new(raw_attribute, raw_value, @attributes_to_replace, @raw_filters)
+      end
+    end
+
+    private
+
+      def parsed_filters
+        filter_parsers_hash.inject({}) do |result, item|
+          attribute, filter_parser = item
+
+          result[attribute] = filter_parser.value
+
+          result
+        end
+      end
+
+      def filter_parsers_hash
+        optimized_filter_parsers.inject({}) do |result, filter_parser|
+          if result.has_key?(filter_parser.attribute)
+            result[filter_parser.attribute].merge(filter_parser)
+          else
+            result[filter_parser.attribute] = filter_parser
+          end
+
+          result
+        end
+      end
+
+      def optimized_filter_parsers
+        if or_filter_parser
+          filter_parsers.inject([]) do |result, filter_parser|
+            if filter_parser != or_filter_parser && or_filter_parser.include?(filter_parser)
+              or_filter_parser.merge(filter_parser)
+            else
+              result << filter_parser
+            end
+
+            result
+          end
+        else
+          filter_parsers
+        end
+      end
+
+      def or_filter_parser
+        @or_filter_parser ||= filter_parsers.select { |filter_parser| filter_parser.or_attribute? }.first
+      end
+  end
+end

data/lib/query_string_interface/helpers.rb

@@ -0,0 +1,22 @@
+module QueryStringInterface
+  module Helpers
+    def hash_with_indifferent_access(params)
+      params.is_a?(HashWithIndifferentAccess) ? params : params.with_indifferent_access
+    end
+
+    def replace_attribute(attribute, hash_with_attributes_to_replace)
+      hash = hash_with_indifferent_access(hash_with_attributes_to_replace)
+      hash.has_key?(attribute) ? hash[attribute] : attribute
+    end
+
+    def replaced_attribute_name(attribute, hash_with_attributes_to_replace)
+      attribute = replace_attribute(attribute, hash_with_attributes_to_replace)
+      attribute.is_a?(Hash) ? attribute[:to] : attribute
+    end
+
+    def replaced_attribute_value(attribute, value, hash_with_attributes_to_replace, raw_params)
+      attribute = replace_attribute(attribute, hash_with_attributes_to_replace)
+      attribute.is_a?(Hash) ? attribute[:convert_value_to].call(value, raw_params) : value
+    end
+  end
+end

data/lib/query_string_interface/parsers.rb

@@ -0,0 +1,5 @@
+require "query_string_interface/parsers/date_time_parser"
+require "query_string_interface/parsers/number_parser"
+require "query_string_interface/parsers/array_parser"
+require "query_string_interface/parsers/regex_parser"
+require "query_string_interface/parsers/boolean_and_nil_parser"

data/lib/query_string_interface/parsers/array_parser.rb

@@ -0,0 +1,34 @@
+module QueryStringInterface
+  module Parsers
+    class ArrayParser
+      ARRAY_SEPARATOR = '|'
+
+      def parseable?(value, operator)
+        operator && conditional_operators.include?(operator)
+      end
+
+      def parse(value)
+        value.split(ARRAY_SEPARATOR).map(&:strip).map do |item|
+          parse_item(item)
+        end
+      end
+
+      private
+        def parse_item(item)
+          other_parsers.each do |parser|
+            return parser.parse(item) if parser.parseable?(item, '')
+          end
+        end
+
+        def other_parsers
+          @other_parsers ||= QueryStringInterface::Filter::PARSERS.reject do |parser|
+            parser.is_a?(ArrayParser)
+          end
+        end
+
+        def conditional_operators
+          @conditional_operators ||= QueryStringInterface::ARRAY_CONDITIONAL_OPERATORS.map { |o| "$#{o}" }
+        end
+    end
+  end
+end

data/lib/query_string_interface/parsers/boolean_and_nil_parser.rb

@@ -0,0 +1,28 @@
+module QueryStringInterface
+  module Parsers
+    class BooleanAndNilParser
+      def parseable?(value, operator)
+        !value.nil? && !value.empty?
+      end
+
+      def parse(value)
+        if boolean?(value)
+          value.strip == 'true'
+        elsif value.nil? or value.empty? or nil_value?(value)
+          nil
+        else
+          value
+        end
+      end
+
+      private
+        def boolean?(value)
+          value && ['true', 'false'].include?(value.strip)
+        end
+
+        def nil_value?(value)
+          value && ['nil', 'null'].include?(value.strip)
+        end
+    end
+  end
+end

data/lib/query_string_interface/parsers/date_time_parser.rb

@@ -0,0 +1,15 @@
+module QueryStringInterface
+  module Parsers
+    class DateTimeParser
+      DATE_REGEX = /^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{1,2}-\d{1,2}[T \t]+\d{1,2}:\d{2}:\d{2}(\.[0-9]*)?([ \t]*)(Z?|[-+]\d{2}?(:?\d{2})?))$/
+
+      def parseable?(value, operator)
+        DATE_REGEX.match(value)
+      end
+
+      def parse(value)
+        Time.parse(value)
+      end
+    end
+  end
+end

data/lib/query_string_interface/parsers/number_parser.rb

@@ -0,0 +1,26 @@
+module QueryStringInterface
+  module Parsers
+    class NumberParser
+      def parseable?(value, operator)
+        integer?(value) or float?(value)
+      end
+
+      def parse(value)
+        if integer?(value)
+          value.to_i
+        elsif float?(value)
+          value.to_f
+        end
+      end
+
+      private
+        def integer?(value)
+          value =~ /^\d+$/
+        end
+
+        def float?(value)
+          value =~ /^(\d+)(\.?\d*)$/
+        end
+    end
+  end
+end

data/lib/query_string_interface/parsers/regex_parser.rb

@@ -0,0 +1,15 @@
+module QueryStringInterface
+  module Parsers
+    class RegexParser
+      def parseable?(value, operator)
+        value =~ /^\/(.*)\/(i|m|x)?$/
+      end
+
+      def parse(value)
+        if value =~ /^\/(.*)\/(i|m|x)?$/
+          eval($&)
+        end
+      end
+    end
+  end
+end

data/lib/query_string_interface/sorting_filters.rb

@@ -0,0 +1,51 @@
+module QueryStringInterface
+  class SortingFilters
+    include QueryStringInterface::Helpers
+
+    SORTING_FIELD_REGEXP = /(.*)\.(#{QueryStringInterface::SORTING_OPERATORS.join('|')})/
+
+    def initialize(raw_filters, default_filters, attributes_to_replace={})
+      @raw_filters = raw_filters.with_indifferent_access
+      @default_filters = default_filters
+      @attributes_to_replace = attributes_to_replace
+    end
+
+    def parse
+      if @raw_filters.has_key?('order_by')
+        parse_filters(@raw_filters['order_by'])
+      else
+        parse_filters(@default_filters)
+      end
+    end
+
+    def parse_filters(filters)
+      filters = filters.split('|') if filters.is_a?(String)
+      filters.map do |filter|
+        replace(filter)
+      end
+    end
+
+    private
+      def replace(filter)
+        if filter.respond_to?(:key) && filter.respond_to?(:operator)
+          replaced_item_for filter.key, filter.operator
+        elsif filter.is_a?(String) or filter.is_a?(Symbol)
+          if match = matches?(filter)
+            replaced_item_for match[1], match[2]
+          else
+            replaced_item_for filter, :asc
+          end
+        elsif filter.is_a?(Hash)
+          replaced_item_for filter.keys.first, filter[filter.keys.first]
+        end
+      end
+
+      def replaced_item_for(key, value)
+        { replace_attribute(key, @attributes_to_replace).to_sym => value.to_sym }
+      end
+
+      def matches?(filter)
+        filter.match(SORTING_FIELD_REGEXP)
+      end
+  end
+end

data/lib/query_string_interface/version.rb

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

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification 
+name: query_string_interface
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Vicente Mundim
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-26 00:00:00 -03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.6.0
+  type: :development
+  version_requirements: *id002
+description: This gem extracts params given as a hash to structured data, that can be used when creating queries
+email: 
+- vicente.mundim@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/query_string_interface/filter.rb
+- lib/query_string_interface/filter_collection.rb
+- lib/query_string_interface/helpers.rb
+- lib/query_string_interface/parsers/array_parser.rb
+- lib/query_string_interface/parsers/boolean_and_nil_parser.rb
+- lib/query_string_interface/parsers/date_time_parser.rb
+- lib/query_string_interface/parsers/number_parser.rb
+- lib/query_string_interface/parsers/regex_parser.rb
+- lib/query_string_interface/parsers.rb
+- lib/query_string_interface/sorting_filters.rb
+- lib/query_string_interface/version.rb
+- lib/query_string_interface.rb
+- MIT_LICENSE
+- README.rdoc
+- Gemfile
+- Gemfile.lock
+has_rdoc: true
+homepage: ""
+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: query_string_interface
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Extracts query string params to a structured data, suitable to use for model queries
+test_files: []
+