constrainable 0.3.0

data/README.markdown

@@ -0,0 +1,72 @@
+# Constrainable
+
+Simple filtering for ActiveRecord. Sanitizes simple and readable query parameters -great for building APIs & HTML filters.
+
+## Straight to the point. Examples:
+
+Let's asume we have a model called Post, defined as:
+    Post(id: integer, title: string, body: string, author_id: integer, category: string, created_at: datetime, updated_at: datetime)
+
+In the simplest possible case you can define a few attributes and start filtering:
+
+    class Post < ActiveRecord::Base
+
+      constrainable do
+        fields :id, :author_id
+      end
+
+    end
+
+    # Examle request:
+    #   GET /posts?where[id][not_eq]=1&where[author_id][eq]=2
+    # Params:
+    #   "where" => { "id" => { "not_eq" => "1" }, "author_id" => { "eq" => "2" } }
+
+    Post.constrain(params[:where])
+    # => SELECT posts.* FROM posts WHERE id != 1 AND author_id = 2
+
+By default, only *eq* and *not_eq* operations are enabled, but there are plenty more:
+
+    class Post < ActiveRecord::Base
+
+      constrainable do
+        fields :id, :author_id, :with => [:in, :not_in, :gt, :gteq, :lt, :lteq]
+        fields :created_at, :with => [:between]
+      end
+
+    end
+
+    # Example request (various notations are accepted):
+    #   GET /posts?
+    #     where[id][not_in]=1|2|3|4&
+    #     where[author_id][in][]=1&
+    #     where[author_id][in][]=2&
+    #     where[created_at][between]=2011-01-01...2011-02-01
+
+Want to *alias* a column? Try this:
+
+    class Post < ActiveRecord::Base
+
+      constrainable do
+        timestamp :created, :using => :created_at, :with => [:lt, :lte, :between]
+      end
+
+    end
+    # Example request:
+    #   GET /posts?where[created][lt]=2011-01-01
+
+What about associations?
+
+    class Post < ActiveRecord::Base
+      belongs_to :author
+
+      constrainable do
+        string :author_name, :using => lambda { Author.arel_table[:name] }, :with => [:matches], :scope => lambda { includes(:author) }
+      end
+    end
+    # Example request:
+    #   GET /posts?where[author][matches]=%tom%
+
+    Post.constrain(params[:where])
+    # => SELECT posts.* FROM posts LEFT OUTER JOIN authors ON authors.id = posts.author_id WHERE authors.name LIKE '%tom%'
+

data/lib/bsm/constrainable/field/base.rb

@@ -0,0 +1,59 @@
+# Abstract field type
+class Bsm::Constrainable::Field::Base
+  DEFAULT_OPERATORS = [:eq, :not_eq, :gt, :gteq, :lt, :lteq, :between].freeze
+
+  class_inheritable_accessor :operators, :defaults, :instance_reader => false, :instance_writer => false
+  self.operators = DEFAULT_OPERATORS.dup
+  self.defaults  = [:eq, :not_eq]
+
+  # Returns the field type/kind, e.g. <tt>:string</tt> or <tt>:integer</tt>
+  def self.kind
+    @kind ||= name.demodulize.underscore.to_sym
+  end
+
+  attr_reader :name, :operators, :attribute, :scope
+
+  # Accepts a name and options. Valid options are:
+  # * <tt>:using</tt> - a Symbol or a Proc pointing to a DB column, optional (uses name by default)
+  # * <tt>:with</tt> - a list of operators to use
+  # * <tt>:scope</tt> - a Proc containing additonal scopes
+  #
+  # Examples:
+  #
+  #   Field::Integer.new :id
+  #   Field::Integer.new :uid, :using => :id
+  #   Field::Integer.new :uid, :using => proc { Model.scoped.table[:col_name] }
+  #   Field::String.new :name, :with => [:matches]
+  #   Field::String.new :author, :with => [:matches], :using => proc { Author.scoped.table[:name] }, :scope => proc { includes(:author) }
+  #
+  def initialize(name, options = {})
+    @name      = name.to_s
+    @attribute = options[:using] || name
+    @operators = Set.new(self.class.operators & Array.wrap(options[:with]))
+    @operators = Set.new(self.class.defaults) if @operators.empty?
+    @scope     = options[:scope]
+  end
+
+  # Merge params into a relation
+  def merge(relation, params)
+    params.slice(*operators).each do |operator, value|
+      operation = Bsm::Constrainable::Operation.new(operator, value, relation, self)
+      next if operation.clause.nil?
+
+      relation = relation.instance_eval(&scope) if scope
+      relation = relation.where(operation.clause)
+    end
+    relation
+  end
+
+  def convert(value)
+    value.is_a?(Array) ? value.map {|v| convert(v) } : _convert(value)
+  end
+
+  protected
+
+    def _convert(value)
+      value.to_s
+    end
+
+end

data/lib/bsm/constrainable/field/common.rb

@@ -0,0 +1,46 @@
+module Bsm::Constrainable::Field
+  class Number < Base
+    self.operators += [:in, :not_in]
+
+    protected
+
+    def _convert(v)
+      Float(v) rescue nil
+    end
+  end
+
+  class Integer < Number
+    protected
+
+    def _convert(v)
+      result = super
+      result ? result.to_i : nil
+    end
+  end
+
+  class Decimal < Number
+  end
+
+  class String < Base
+    self.operators = [:eq, :not_eq]
+  end
+
+  class Timestamp < Base
+    protected
+
+    def _convert(v)
+      v.to_time(:utc) rescue nil
+    end
+  end
+
+  class Datetime < Timestamp
+  end
+
+  class Date < Base
+    protected
+
+    def _convert(v)
+      v.to_date rescue nil
+    end
+  end
+end

data/lib/bsm/constrainable/field.rb

@@ -0,0 +1,20 @@
+module Bsm::Constrainable::Field
+  extend Bsm::Constrainable::Registry
+
+  autoload :Base,     'bsm/constrainable/field/base'
+  autoload :Number,   'bsm/constrainable/field/common'
+  autoload :Integer,  'bsm/constrainable/field/common'
+  autoload :Decimal,  'bsm/constrainable/field/common'
+  autoload :String,   'bsm/constrainable/field/common'
+  autoload :Timestamp,'bsm/constrainable/field/common'
+  autoload :Datetime, 'bsm/constrainable/field/common'
+  autoload :Date,     'bsm/constrainable/field/common'
+
+  register self::Number
+  register self::Integer
+  register self::Decimal
+  register self::String
+  register self::Timestamp
+  register self::Datetime
+  register self::Date
+end

data/lib/bsm/constrainable/filter_set.rb

@@ -0,0 +1,51 @@
+class Bsm::Constrainable::FilterSet < Hash
+  include ::Bsm::Constrainable::Util
+
+  attr_reader :schema
+
+  def initialize(schema, params = {})
+    @schema = schema
+
+    normalized_hash(params).slice(*schema.keys).each do |name, part|
+      update name => part.symbolize_keys if part.is_a?(Hash)
+    end
+  end
+
+  def merge(relation)
+    each do |name, part|
+      schema[name].each do |field|
+        relation = field.merge(relation, part)
+      end
+    end
+    relation
+  end
+
+  def respond_to?(sym, *)
+    name, operator = sym.to_s.sub(NAME_OP, ''), $1
+    super || (operator.nil? && schema.key?(name)) || valid_operator?(name, operator)
+  end
+
+  private
+    NAME_OP = /\[(\w+)\]$/.freeze
+
+    def method_missing(sym, *args)
+      name, operator = sym.to_s.sub(NAME_OP, ''), $1
+
+      if (operator.nil? && schema.key?(name))
+        self[name]
+      elsif valid_operator?(name, operator)
+        self[name].try(:[], operator.to_sym)
+      else
+        super
+      end
+    end
+
+    def valid_operator?(name, operator)
+      return false unless operator.present? && schema.key?(name.to_s)
+
+      schema[name].any? do |field|
+        field.operators.include?(operator.to_sym)
+      end
+    end
+
+end

data/lib/bsm/constrainable/model.rb

@@ -0,0 +1,39 @@
+# Includable module, for ActiveRecord::Base
+module Bsm::Constrainable::Model
+  extend ActiveSupport::Concern
+
+  included do
+    class_inheritable_accessor :_constrainable
+    self._constrainable = {}
+  end
+
+  module ClassMethods
+
+    # Constraint definition for a model. Example:
+    #
+    #   class Post < ActiveRecord::Base
+    #
+    #     constrainable do
+    #       # Add your default constraints
+    #     end
+    #
+    #     constrainable :custom do
+    #       # Add your custom constraints
+    #     end
+    #
+    #   end
+    #
+    def constrainable(name = nil, &block)
+      name = name.present? ? name.to_sym : :default
+      _constrainable[name] ||= Bsm::Constrainable::Schema.new(self)
+      _constrainable[name.to_sym].instance_eval(&block) if block
+      _constrainable[name]
+    end
+
+    # Delegator to Relation#constrain
+    def constrain(*args)
+      relation.constrain(*args)
+    end
+
+  end
+end

data/lib/bsm/constrainable/operation/base.rb

@@ -0,0 +1,55 @@
+class Bsm::Constrainable::Operation::Base
+  extend ActiveSupport::Memoizable
+
+  def self.kind
+    name.demodulize.underscore.to_sym
+  end
+
+  attr_reader :value, :field, :relation
+
+  def initialize(value, relation, field)
+    @value    = value
+    @relation = relation
+    @field    = field
+  end
+
+  def parsed
+    value.to_s
+  end
+
+  def valid?
+    !invalid?
+  end
+
+  def invalid?
+    wrap = Array.wrap(normalized)
+    wrap.empty? || wrap.any?(&:nil?)
+  end
+
+  def clause
+    valid? ? _clause : nil
+  end
+  memoize :clause
+
+  protected
+
+    def _clause
+      attribute.send self.class.kind, normalized
+    end
+
+    def normalized
+      field.convert(parsed)
+    end
+    memoize :normalized
+
+    def attribute
+      case field.attribute
+      when Proc
+        field.attribute.call(relation)
+      else
+        relation.table[field.attribute]
+      end
+    end
+    memoize :attribute
+
+end

data/lib/bsm/constrainable/operation/between.rb

@@ -0,0 +1,21 @@
+module Bsm::Constrainable::Operation
+  class Between < Base
+
+    def parsed
+      result = case value
+      when /^ *(.+?) *\.{2,} *(.+?) *$/
+        [$1, $2]
+      else
+        value
+      end
+      result.is_a?(Array) && result.size == 2 ? result.map(&:to_s) : nil
+    end
+
+    protected
+
+      def _clause
+        attribute.gteq(normalized.first).and(attribute.lteq(normalized.last))
+      end
+
+  end
+end

data/lib/bsm/constrainable/operation/collection.rb

@@ -0,0 +1,9 @@
+module Bsm::Constrainable::Operation
+  class Collection < Base
+
+    def parsed
+      Bsm::Constrainable::Util.normalized_array(value)
+    end
+
+  end
+end

data/lib/bsm/constrainable/operation/common.rb

@@ -0,0 +1,16 @@
+module Bsm::Constrainable::Operation
+  class Eq < Base
+  end
+  class NotEq < Base
+  end
+  class Gt < Base
+  end
+  class Gteq < Base
+  end
+  class Lt < Base
+  end
+  class Lteq < Base
+  end
+  class Matches < Base
+  end
+end

data/lib/bsm/constrainable/operation/in.rb

@@ -0,0 +1,4 @@
+module Bsm::Constrainable::Operation
+  class In < Collection
+  end
+end

data/lib/bsm/constrainable/operation/not_in.rb

@@ -0,0 +1,4 @@
+module Bsm::Constrainable::Operation
+  class NotIn < Collection
+  end
+end

data/lib/bsm/constrainable/operation.rb

@@ -0,0 +1,27 @@
+module Bsm::Constrainable::Operation
+  extend Bsm::Constrainable::Registry
+
+  autoload :Base, 'bsm/constrainable/operation/base'
+  autoload :Collection, 'bsm/constrainable/operation/collection'
+  autoload :Eq,      'bsm/constrainable/operation/common'
+  autoload :NotEq,   'bsm/constrainable/operation/common'
+  autoload :Gt,      'bsm/constrainable/operation/common'
+  autoload :Lt,      'bsm/constrainable/operation/common'
+  autoload :Gteq,    'bsm/constrainable/operation/common'
+  autoload :Lteq,    'bsm/constrainable/operation/common'
+  autoload :Matches, 'bsm/constrainable/operation/common'
+  autoload :In,      'bsm/constrainable/operation/in'
+  autoload :NotIn,   'bsm/constrainable/operation/not_in'
+  autoload :Between, 'bsm/constrainable/operation/between'
+
+  register self::Eq
+  register self::NotEq
+  register self::In
+  register self::NotIn
+  register self::Gt
+  register self::Lt
+  register self::Gteq
+  register self::Lteq
+  register self::Matches
+  register self::Between
+end

data/lib/bsm/constrainable/registry.rb

@@ -0,0 +1,25 @@
+module Bsm::Constrainable::Registry
+
+  # Returns the current registry Hash
+  def registry
+    @registry ||= {}
+  end
+
+  # Register a class
+  def register(klass)
+    raise ArgumentError, "Already registered kind: #{klass.kind}" if registered?(klass.kind)
+    registry[klass.kind] = klass
+  end
+
+  # Create a new object of a certain kind.
+  def new(kind, *args)
+    raise ArgumentError, "Invalid kind #{kind}" unless registered?(kind)
+    registry[kind.to_sym].new(*args)
+  end
+
+  # Returns true if kind was already registered, else false
+  def registered?(kind)
+    registry.key?(kind.to_sym)
+  end
+
+end

data/lib/bsm/constrainable/relation.rb

@@ -0,0 +1,28 @@
+# Extension for ActiveRecord::Relation
+module Bsm::Constrainable::Relation
+
+  # Apply contraints. Example:
+  #
+  #   Post.constrain("created_at" => { "lt" => "2011-01-01" }})
+  #
+  #   # Use "custom" constraints
+  #   Post.constrain(:custom, "created_at" => { "lt" => "2011-01-01" }})
+  #
+  #   # Combine it with relations & scopes
+  #   Post.archived.includes(:author).constrain(params[:where]).paginate :page => 1
+  #
+  def constrain(*args)
+    scope    = args.first.is_a?(Symbol) ? args.shift : nil
+    filters  = args.last
+
+    case filters
+    when Bsm::Constrainable::FilterSet
+      filters.merge(self)
+    when Hash
+      klass.constrainable(scope).filter(filters).merge(self)
+    else
+      self
+    end
+  end
+
+end

data/lib/bsm/constrainable/schema.rb

@@ -0,0 +1,84 @@
+# Schema definition.
+class Bsm::Constrainable::Schema < Hash
+  Field = ::Bsm::Constrainable::Field
+
+  def initialize(klass)
+    @klass = klass
+    super()
+  end
+
+  # Define multiple constrainable columns. Expects 1-n column names (must be
+  # real columns) and an options Hash. Examples:
+  #
+  #   fields :id
+  #   fields :id, :author_id
+  #   fields :id, :author_id, :with => [:in, :not_in]
+  #
+  def fields(*names)
+    options = names.extract_options!
+    names.map(&:to_s).each do |name|
+      column = @klass.columns_hash[name]
+      raise ArgumentError, "Invalid field #{name}" unless column
+      raise ArgumentError, "Invalid field type #{column.type}" unless Field.registered?(column.type)
+      match name, options.merge(:as => column.type)
+    end
+  end
+
+  # Define constrainable names (don't have to be real columns). Expects 1-n
+  # names and an options Hash. Options, must specify the type via <tt>:as</tt>.
+  # Examples:
+  #
+  #   # One match
+  #   match :id, :as => :number
+  #
+  #   # Multiple matches
+  #   match :id, :author_id, :as => :integer, :with => [:in, :not_in]
+  #
+  #   # Use a specific column
+  #   match :created, :using => :created_at, :as => :timestamp, :with => [:lt, :between]
+  #
+  #   # Complex example, using an attribute from another table, and ensure it's included (LEFT OUTER JOIN)
+  #   match :author, :using => proc { Author.scope.table[:name] }, :scope => { includes(:author) }, :as => :string, :with => [:eq, :matches]
+  #
+  # There are also several short-cutrs available. Examples:
+  #
+  #   timestamp :created, :using => :created_at, :with => [:lt, :between]
+  #   number    :id, :author_id
+  #   string    :title, :with => [:eq, :matches]
+  #
+  def match(*names)
+    options = names.extract_options!
+    kind    = options.delete(:as)
+    names.map(&:to_s).each do |name|
+      self[name] ||= []
+      self[name] << Field.new(kind, name, options)
+    end
+  end
+  alias_method :field, :match
+
+  # Creates a FilterSet object for given params. Filter-sets can be used to
+  # constrain relations as well as e.g. in forms. Example:
+  #
+  #   filters = Post.constrainable.filter(params[:where])
+  #   Post.archived.constrain(filters).limit(100)
+  #
+  def filter(params = nil)
+    Bsm::Constrainable::FilterSet.new self, params
+  end
+
+  def respond_to?(sym)
+    super || Field.registered?(sym)
+  end
+
+  protected
+
+    def method_missing(sym, *args)
+      if Field.registered?(sym)
+        opts = args.extract_options!.merge(:as => sym)
+        match(*(args << opts))
+      else
+        super
+      end
+    end
+
+end

data/lib/bsm/constrainable/util.rb

@@ -0,0 +1,15 @@
+module Bsm::Constrainable::Util
+  extend self
+
+  def normalized_hash(hash)
+    hash.is_a?(Hash) ? hash.stringify_keys : {}
+  end
+
+  def normalized_array(array)
+    array = array.keys if array.is_a?(Hash)
+    Array.wrap(array).map do |item|
+      item.to_s.split('|')
+    end.flatten.reject(&:blank?).uniq
+  end
+
+end

data/lib/bsm/constrainable.rb

@@ -0,0 +1,22 @@
+require "active_support/core_ext"
+
+module Bsm # @private
+  module Constrainable # @private
+    autoload :Util,       "bsm/constrainable/util"
+    autoload :Model,      "bsm/constrainable/model"
+    autoload :Relation,   "bsm/constrainable/relation"
+    autoload :Schema,     "bsm/constrainable/schema"
+    autoload :Registry,   "bsm/constrainable/registry"
+    autoload :Field,      "bsm/constrainable/field"
+    autoload :Operation,  "bsm/constrainable/operation"
+    autoload :FilterSet,  "bsm/constrainable/filter_set"
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include Bsm::Constrainable::Model
+end
+
+ActiveRecord::Relation.class_eval do
+  include Bsm::Constrainable::Relation
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification 
+name: constrainable
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- Dimitrij Denissenko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-01 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: abstract
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id003
+description: Sanitizes simple and readable query parameters -great for building APIs & HTML filters
+email: dimitrij@blacksquaremedia.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.markdown
+- lib/bsm/constrainable/field/common.rb
+- lib/bsm/constrainable/field/base.rb
+- lib/bsm/constrainable/field.rb
+- lib/bsm/constrainable/filter_set.rb
+- lib/bsm/constrainable/relation.rb
+- lib/bsm/constrainable/registry.rb
+- lib/bsm/constrainable/schema.rb
+- lib/bsm/constrainable/util.rb
+- lib/bsm/constrainable/operation.rb
+- lib/bsm/constrainable/model.rb
+- lib/bsm/constrainable/operation/common.rb
+- lib/bsm/constrainable/operation/in.rb
+- lib/bsm/constrainable/operation/base.rb
+- lib/bsm/constrainable/operation/between.rb
+- lib/bsm/constrainable/operation/collection.rb
+- lib/bsm/constrainable/operation/not_in.rb
+- lib/bsm/constrainable.rb
+has_rdoc: true
+homepage: https://github.com/bsm/constrainable
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Simple filtering for ActiveRecord
+test_files: []
+