restful_query-rails3 0.4

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+tmp*
+pkg*
+.specification
+_site*

data/History.txt

@@ -0,0 +1,29 @@
+== 0.3.1 2010-02-16
+
+* Parser takes a :map_columns option which maps aliases column names
+* The parser now strips all conditions with blank values. If you actually want
+to compare on a blank value, use the convertable value ':blank'
+
+== 0.3.0 2009-08-10
+
+* Vast improvements/enhancements
+  * Added Sequel::Dataset extension: restful_query - works like the can_query named_scope
+  * Added IN and NOT IN to Condition operators - value can be split on delimiter option
+  * Changed the default behavior to storing conditions as an array of condition hashes
+  * Added ability to pass an array of :conditions to the parser, see tests for format.
+  * Added English/Human names to condition operators
+  * Added list of CONVERTABLE_VALUES which are prefixed w/ : and are converted to their true ruby counterparts (nil, null, true, etc)
+  * Added operators for IS and IS NOT
+  * Added neq/!= operator to conditions
+  * Added a clear_default_sort! action that deletes the default before switching
+
+== 0.2.0 2009-03-20
+
+* 1 major enhancement:
+  * Now includes interface for sorting.
+  * Better documentation on the way.
+
+== 0.0.1 2009-01-11
+
+* 1 major enhancement:
+  * Initial release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Aaron Quint, Quirkey NYC, LLC
+
+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,64 @@
+= restful_query
+
+http://github.com/quirkey/restful_query
+
+== DESCRIPTION:
+
+RestfulQuery provides a RESTful interface for easily and safely querying ActiveRecord data. 
+
+== USAGE:
+
+=== Rails/ActiveRecord:
+  
+  # as a gem, in environment.rb
+  config.gem 'restful_query'
+  
+or install the plugin.
+In your model:
+
+  class Post < ActiveRecord::Base
+    can_query
+  end
+
+In your controller:
+  
+  class PostsController < ApplicationController
+    # ...
+    def index
+      @posts = Post.restful_query(params[:query])
+    end
+    # ...
+  end
+
+Now you can query your model via the URL:
+
+  /posts?query[name][like]=jon&query[_sort]=created_at-desc
+
+=== Sequel
+
+Theres also a Sequel extension that works very similar to ActiveRecord::Base.can_query:
+
+  require 'sequel/extensions/restful_query'
+  
+  DB[:posts].restful_query({'name' => {'like' => 'jon'}, '_sort' => 'created_at-desc'})
+  <Sequel::SQLite::Dataset: "SELECT * FROM `posts` WHERE (name LIKE %jon%) ORDER BY `created_at` DESC">
+
+=== More!
+
+Please see the project homepage for detailed usage and info:
+
+http://code.quirkey.com/restful_query
+
+== INSTALL:
+
+To install as a gem:
+
+  sudo gem install restful_query
+    
+To install as a rails plugin
+  
+  ./script/plugin install git://github.com/quirkey/restful_query.git
+  
+== LICENSE:
+
+Free for use under the terms of the MIT License - see LICENSE for details

data/Rakefile

@@ -0,0 +1,30 @@
+%w[rubygems rake rake/clean rake/testtask fileutils].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/restful_query'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = %q{restful_query}
+    s.version = RestfulQuery::VERSION
+    s.authors = ["Aaron Quint"]
+    s.summary = 'Simple ActiveRecord and Sequel queries from a RESTful and safe interface'
+    s.description   = %q{RestfulQuery provides a simple interface in front of a complex parser to parse specially formatted query hashes into complex SQL queries. It includes ActiveRecord and Sequel extensions.}
+    s.rubyforge_project = %q{quirkey}
+    s.add_runtime_dependency(%q<activesupport>, [">= 2.2.0"])
+    s.add_runtime_dependency(%q<chronic>, [">= 0.2.3"])
+    s.add_development_dependency(%q<Shoulda>, [">= 1.2.0"])
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+task :default => :test

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.expand_path(File.dirname(__FILE__)), 'rails', 'init.rb')

data/lib/restful_query/can_query.rb

@@ -0,0 +1,38 @@
+module RestfulQuery
+  module CanQuery
+
+    def self.included(klass)
+      klass.extend MacroMethods
+    end
+
+    module MacroMethods
+      def can_query(options = {})
+        @include       = options.delete(:include) || []
+        @query_options = options
+        @can_query     = true
+        module_eval do
+          def self.restful_query_parser(query_hash, options = {})
+            RestfulQuery::Parser.new(query_hash, @query_options.merge(options))
+          end
+
+          scope_meth = self.respond_to?(:named_scope) ? :named_scope : :scope
+
+          send(scope_meth, :restful_query, lambda {|query_hash|
+            parser = self.restful_query_parser(query_hash)
+            query_hash = {}
+            query_hash[:conditions] = parser.to_conditions_array if parser.has_conditions?
+            query_hash[:include]    = @include if @include && !@include.empty?
+            query_hash[:order]      = parser.sort_sql if parser.has_sort?
+            logger.info 'Rest query:' + query_hash.inspect
+            query_hash
+          })
+        end
+      end
+
+      def can_query?
+        @can_query
+      end
+    end
+
+  end
+end

data/lib/restful_query/condition.rb

@@ -0,0 +1,110 @@
+module RestfulQuery
+  class InvalidOperator < Error; end;
+  
+  class Condition
+    attr_reader :column, :value, :operator, :options
+    
+    OPERATOR_MAPPING = {
+      'lt'    => '<',
+      'gt'    => '>',
+      'gteq'  => '>=',
+      'lteq'  => '<=',
+      'eq'    => '=',
+      'neq'   => '!=',
+      'is'    => 'IS',
+      'not'   => 'IS NOT',
+      'like'  => 'LIKE',
+      'in'    => 'IN',
+      'notin' => 'NOT IN'
+    }.freeze
+    
+    CONVERTABLE_VALUES = {
+      ':true'  => true,
+      ':false' => false,
+      ':nil'   => nil,
+      ':null'  => nil,
+      ':blank' => '',
+      ':empty' => ''
+    }.freeze
+    
+    ENGLISH_OPERATOR_MAPPING = {
+      'Less than'                => 'lt',
+      'Greater than'             => 'gt',
+      'Less than or equal to'    => 'lteq',
+      'Greater than or equal to' => 'gteq',
+      'Equal to'                 => 'eq',
+      'Not equal to'             => 'neq',
+      'Is'                       => 'is',
+      'Is not'                   => 'not',
+      'Like'                     => 'like',
+      'In'                       => 'in',
+      'Not in'                   => 'notin'
+    }.freeze
+    
+    
+    def initialize(column, value, operator = '=', options = {})
+      @options = {}
+      self.options  = options if options.is_a?(Hash)
+      self.column   = column
+      self.operator = operator
+      self.value    = value
+    end
+    
+    def map_operator(operator_to_look_up, reverse = false)
+      mapping = reverse ?  OPERATOR_MAPPING.dup.invert : OPERATOR_MAPPING.dup
+      return operator_to_look_up if mapping.values.include?(operator_to_look_up)
+      found = mapping[operator_to_look_up.to_s]
+    end
+ 
+    def operator=(operator)
+      @operator = map_operator(operator)
+      raise(RestfulQuery::InvalidOperator, "#{@operator} is not a valid operator") unless @operator
+    end
+      
+    def column=(column)
+      @column = column.to_s
+    end
+    
+    def value=(value)
+      @value = parse_value(value)
+    end
+    
+    def options=(options)
+      options.each {|k, v| @options[k.to_sym] = v }
+    end
+    
+    def to_hash
+      {column => {map_operator(operator, true) => value}}
+    end
+    
+    def to_condition_array
+      ["#{column} #{operator} #{placeholder}", value]
+    end
+    
+    def placeholder
+      if ['IN', 'NOT IN'].include?(operator)
+        '(?)'
+      else
+        '?'
+      end
+    end
+    
+    protected
+    def parse_value(value)
+      if operator == 'LIKE' 
+        "%#{value}%"
+      elsif ['IN', 'NOT IN'].include?(operator) && !value.is_a?(Array)
+        value.split(options[:delimiter] || ',')
+      elsif options[:integer]
+        value.to_i
+      elsif options[:chronic]
+        Chronic.parse(value.to_s)
+      elsif value =~ /^\:/ && CONVERTABLE_VALUES.has_key?(value)
+        CONVERTABLE_VALUES[value]
+      else
+        value
+      end
+    end
+    
+  end
+end

data/lib/restful_query/parser.rb

@@ -0,0 +1,166 @@
+module RestfulQuery
+  class Parser
+    attr_reader :query, :exclude_columns, :map_columns, :integer_columns, :options
+
+    def initialize(query, options = {})
+      @options         = options || {}
+      @exclude_columns = columns_from_options(:exclude, options)
+      @integer_columns = columns_from_options(:integer, options)
+      @map_columns     = options[:map_columns] || {}
+      @default_sort    = options[:default_sort] ? [Sort.parse(options[:default_sort])] : []
+      @single_sort     = options[:single_sort] || false
+      @query           = (query || {}).dup
+      @default_join    = @query.delete(:join) || :and
+      extract_sorts_from_conditions
+      map_conditions
+    end
+
+    def conditions
+      conditions_hash.values.flatten
+    end
+    
+    def has_conditions?
+      !conditions.empty?
+    end
+
+    def conditions_for(column)
+      conditions_hash[column.to_s]
+    end
+
+    def to_conditions_array(join = nil)
+      join ||= @default_join
+      join_string = (join == :or) ? ' OR ' : ' AND '
+      conditions_string = []
+      conditions_values = []
+      conditions.each do |c| 
+        ca = c.to_condition_array
+        conditions_string << ca[0]
+        conditions_values << ca[1]
+      end
+      conditions_values.unshift(conditions_string.join(join_string))
+    end
+    
+    def to_query_hash
+      hash = @query
+      hash['_sort'] = sorts.collect {|s| s.to_s } unless sorts.empty?
+      hash
+    end
+            
+    def sort_sql
+      @sorts.collect {|s| s.to_sql }.join(', ')
+    end
+    
+    def has_sort?
+      !sorts.empty?
+    end
+    
+    def sorts
+      @sorts ||= []
+    end
+    
+    def sorted_columns
+      sorts.collect {|s| s.column }
+    end
+    
+    def sorted_by?(column_name)
+      column = map_column(column_name)
+      sorted_columns.include?(column.to_s)
+    end
+    
+    def sort(column_name)
+      column = map_column(column_name)
+      sorts.detect {|s| s && s.column == column }
+    end
+    
+    def set_sort(column_name, direction)
+      column = map_column(column_name)
+      if new_sort = self.sort(column_name)
+        if direction.nil?
+          self.sorts.reject! {|s| s.column == column.to_s }
+        else
+          new_sort.direction = direction
+        end
+      else
+        new_sort = Sort.new(column, direction)
+        self.sorts << new_sort
+      end
+      new_sort
+    end
+    
+    def clear_default_sort!
+      @sorts.reject! {|s| s == @default_sort.first }
+    end
+
+    protected
+    def add_condition_for(column, condition)
+      conditions_hash[column.to_s] ||= []
+      conditions_hash[column.to_s] << condition
+    end
+
+    def conditions_hash
+      @conditions_hash ||= {}
+    end
+
+    def chronic_columns
+      if chronic = options[:chronic]
+        chronic.is_a?(Array) ? chronic.collect {|c| c.to_s } : ['created_at', 'updated_at']
+      else
+        []
+      end
+    end
+    
+    def extract_sorts_from_conditions
+      @sorts = sorts_from_hash(@query.delete('_sort'))
+      @sorts = @default_sort if @sorts.empty?
+    end
+
+    def map_conditions
+      conditions = query.delete(:conditions) || query
+      if conditions.is_a?(Hash)
+        conditions_array = []
+        conditions.each do |column, hash_conditions|
+          if hash_conditions.is_a?(Hash)
+            hash_conditions.each do |operator, value|
+              conditions_array << {'column' => column, 'operator' => operator, 'value' => value}
+            end
+          else
+            conditions_array << {'column' => column, 'value' => hash_conditions}
+          end
+        end
+        conditions = conditions_array
+      end
+      # with a normalized array of conditions
+      conditions.each do |condition|
+        column, operator, value = condition['column'], condition['operator'] || 'eq', condition['value']
+        unless exclude_columns.include?(column.to_s) || value == ''
+          condition_options = {}
+          condition_options[:chronic] = true if chronic_columns.include?(column.to_s)
+          condition_options[:integer] = true if integer_columns.include?(column.to_s)
+          condition_options.merge!(condition['options'] || {})
+          column_name = map_column(column)
+          add_condition_for(column, Condition.new(column_name, value, operator, condition_options))
+        end
+      end
+    end
+     
+    def sorts_from_hash(sorts)
+      sort_conditions = [sorts].flatten.compact
+      sort_conditions.collect do |c| 
+        s = Sort.parse(c)
+        s.column = map_column(s.column)
+        s
+      end
+    end 
+    
+    def columns_from_options(column_type, options)
+      option = "#{column_type}_columns".to_sym
+      options[option] ? [options.delete(option)].flatten.collect {|c| c.to_s } : []
+    end
+    
+    def map_column(column_name)
+      map_columns[column_name.to_s] || column_name.to_s
+    end
+    
+    
+  end
+end

data/lib/restful_query/sort.rb

@@ -0,0 +1,72 @@
+module RestfulQuery
+  class InvalidDirection < Error; end
+  
+  class Sort
+    include Comparable
+    
+    attr_reader :column, :direction
+    
+    DIRECTIONS = {
+      'up' => 'ASC',
+      'asc' => 'ASC',
+      'ASC' => 'ASC',
+      'down' => 'DESC',
+      'desc' => 'DESC',
+      'DESC' => 'DESC'
+    }.freeze
+    
+    
+    def initialize(column, direction)
+      self.column    = column
+      self.direction = direction
+    end
+    
+    def self.parse(sort_string, split_on = /\-|\ /)
+      return unless sort_string
+      column, direction = sort_string.split(split_on)
+      new(column, direction)
+    end
+    
+    def column=(column)
+      @column = column.to_s
+    end
+    
+    def direction=(direction)
+      @direction = DIRECTIONS[direction.to_s]
+      raise(InvalidDirection, "'#{direction}' is not a valid order direction") unless @direction
+    end
+    
+    def reverse_direction
+      direction == 'ASC' ? 'DESC' : 'ASC'
+    end
+    
+    def ==(other)
+      return false unless other.is_a?(Sort)
+      column == other.column && direction == other.direction
+    end
+    
+    # Makes a roundabout for directions nil -> desc -> asc -> nil
+    def self.next_direction(current_direction)
+      case current_direction.to_s.downcase
+      when 'desc'
+        'asc'
+      when 'asc'
+        nil
+      else
+        'desc'
+      end
+    end
+    
+    def next_direction
+      self.class.next_direction(direction)
+    end
+    
+    def to_s(join = '-')
+      "#{column}#{join}#{direction.downcase}"
+    end
+            
+    def to_sql
+      "#{column} #{direction}"
+    end
+  end
+end

data/lib/restful_query.rb

@@ -0,0 +1,23 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'active_support'
+begin
+  require 'chronic'
+rescue LoadError
+  warn 'In order to use the time parsing functionalities you must install the Chronic gem: sudo gem install chronic'
+end
+
+module RestfulQuery
+  VERSION = '0.3.1'
+
+  class Error < RuntimeError; end
+end
+
+%w{condition sort parser can_query}.each do |lib|
+  require File.join("restful_query","#{lib}.rb")
+end
+
+if defined?(ActiveRecord) 
+  ActiveRecord::Base.send(:include, RestfulQuery::CanQuery)
+end

data/lib/sequel/extensions/restful_query.rb

@@ -0,0 +1,25 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'restful_query.rb')
+
+module RestfulQuery
+  class Sort
+    
+    def to_sequel
+      column.to_sym.send(direction.downcase)
+    end
+    
+  end
+end
+
+module Sequel
+  class Dataset
+        
+    def restful_query(query_hash, options = {})
+      parser = RestfulQuery::Parser.new(query_hash, options = {})
+      collection = self
+      collection = collection.filter(*parser.to_conditions_array) if parser.has_conditions?
+      collection = collection.order(*parser.sorts.collect {|s| s.to_sequel }) if parser.has_sort?
+      collection
+    end
+  end
+  
+end

data/rails/init.rb

@@ -0,0 +1,3 @@
+require File.join(File.expand_path(File.dirname(__FILE__)),'..','lib','restful_query.rb')
+
+ActiveRecord::Base.send(:include, RestfulQuery::CanQuery)

data/restful_query-rails3.gemspec

@@ -0,0 +1,72 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{restful_query-rails3}
+  s.version = "0.4"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Aaron Quint"]
+  s.date = %q{2011-02-16}
+  s.description = %q{Rails3 Version of RestfulQuery, provides a simple interface in front of a complex parser to parse specially formatted query hashes into complex SQL queries. It includes ActiveRecord and Sequel extensions.}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "init.rb",
+     "restful_query-rails3.gemspec",
+     "lib/restful_query.rb",
+     "lib/restful_query/can_query.rb",
+     "lib/restful_query/condition.rb",
+     "lib/restful_query/parser.rb",
+     "lib/restful_query/sort.rb",
+     "lib/sequel/extensions/restful_query.rb",
+     "rails/init.rb",
+     "tasks/restful_query_tasks.rake",
+     "test/test_helper.rb",
+     "test/test_restful_query_can_query.rb",
+     "test/test_restful_query_condition.rb",
+     "test/test_restful_query_parser.rb",
+     "test/test_restful_query_sort.rb"
+  ]
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{quirkey}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Simple ActiveRecord and Sequel queries from a RESTful and safe interface}
+  s.test_files = [
+    "test/test_helper.rb",
+     "test/test_restful_query_can_query.rb",
+     "test/test_restful_query_condition.rb",
+     "test/test_restful_query_parser.rb",
+     "test/test_restful_query_sort.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.2.0"])
+      s.add_runtime_dependency(%q<chronic>, [">= 0.2.3"])
+      s.add_development_dependency(%q<Shoulda>, [">= 1.2.0"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 2.2.0"])
+      s.add_dependency(%q<chronic>, [">= 0.2.3"])
+      s.add_dependency(%q<Shoulda>, [">= 1.2.0"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 2.2.0"])
+    s.add_dependency(%q<chronic>, [">= 0.2.3"])
+    s.add_dependency(%q<Shoulda>, [">= 1.2.0"])
+  end
+end
+

data/tasks/restful_query_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :restful_query do
+#   # Task goes here
+# end