rules 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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,79 @@
+AR Rules
+=========
+
+A Ruby gem engine that allows you to add customizable business rules to any ActiveRecord model. Rules integrates with ActiveAdmin to make it trivial to allow admin users to create rules on the fly for your models.
+
+Installation
+------------
+Add it to your Gemfile:
+
+```ruby
+gem "rules", :github => 'azach/rules'
+```
+
+Update your schema:
+
+```ruby
+rake rules:install:migrations
+rake db:migrate
+```
+
+to create the required tables to store your rules.
+
+Setting Up Rules
+------------
+To use rules on a model, include ```Rules::HasRules```. You can also optionally define any attributes that are available for that model using ```has_rule_attributes```.
+
+This will allow the user to build rules against this attribute. For example, you may want to allow users to build rules against the email address in the order. In this case, your model would look like:
+
+```ruby
+class Order < ActiveRecord::Base
+  include Rules::HasRules
+
+  has_rule_attributes({
+    customer_email: {
+      name: "customer email address"
+    }
+  })
+end
+```
+
+To evaluate a set of a rules, use the ```rules_pass?``` method on the instance. You may also pass the values of the attributes that you allowed users to define rules against at this point.
+
+For example:
+
+```ruby
+order = Order.new
+order.email_address = "morbo@example.com"
+order.evaluate(customer_email: order.email_address)
+```
+
+Defining Rules
+------------
+Rules are meant to be defined by business users using an admin interface. For this reason, the gem provides integration with ActiveAdmin to make this easier.
+
+There are two helper methods you can use, one for your show action and one for your form.
+
+For the show action:
+
+```ruby
+show_rules
+```
+
+For the form action:
+
+```ruby
+f.has_rules
+```
+
+This will give you something like:
+
+![ActiveAdmin form for editing rules](https://github.com/azach/rules/raw/master/spec/dummy/app/assets/images/edit_example.png)
+
+Default Constants
+------------
+TODO
+
+Default Evaluators
+------------
+TODO

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Rules'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'spec'
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = false
+end
+
+
+task :default => :spec

data/db/migrate/20120831163952_create_rules.rb

@@ -0,0 +1,11 @@
+class CreateRules < ActiveRecord::Migration
+  def change
+    create_table :rules_rules do |t|
+      t.belongs_to :rule_set
+      t.string :evaluator
+      t.text :parameters
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20120831173835_create_rule_sets.rb

@@ -0,0 +1,10 @@
+class CreateRuleSets < ActiveRecord::Migration
+  def change
+    create_table :rules_rule_sets do |t|
+      t.belongs_to :source, polymorphic: true
+      t.string :evaluation_logic
+
+      t.timestamps
+    end
+  end
+end

data/lib/rules.rb

@@ -0,0 +1,18 @@
+require 'rules/engine'
+require 'rules/evaluators'
+require 'rules/evaluators/definitions'
+require 'rules/has_rules'
+require 'rules/parameters'
+require 'rules/parameters/constant_definitions'
+require 'rules/rule'
+require 'rules/rule_set'
+
+module Rules
+  def self.evaluators
+    @evaluators ||= Evaluators.list
+  end
+
+  def self.constants
+  	@constants ||= Parameters.constants
+  end
+end

data/lib/rules/engine.rb

@@ -0,0 +1,11 @@
+module Rules
+  class Engine < ::Rails::Engine
+    isolate_namespace Rules
+
+    initializer :active_admin do
+      if defined? ActiveAdmin
+        require 'rules/extensions/active_admin/dsl'
+      end
+    end
+  end
+end

data/lib/rules/evaluators.rb

@@ -0,0 +1,18 @@
+module Rules
+  module Evaluators
+    require 'rules/evaluators/evaluator'
+
+    @@list ||= {}
+
+    def self.list
+      @@list
+    end
+
+    def self.define_evaluator(key, &block)
+      raise 'Evaluator already exists' if @@list[key]
+      evaluator = Evaluator.new(key)
+      evaluator.instance_eval(&block) if block_given?
+      @@list[key] = evaluator
+    end
+  end
+end

data/lib/rules/evaluators/definitions.rb

@@ -0,0 +1,73 @@
+module Rules
+  module Evaluators
+    define_evaluator :equals do
+      self.evaluation_method = ->(lhs, rhs) { lhs == rhs }
+      self.requires_rhs = true
+    end
+
+    define_evaluator :not_equals do
+      self.evaluation_method = ->(lhs, rhs) { lhs != rhs }
+      self.name = 'does not equal'
+      self.requires_rhs = true
+    end
+
+    define_evaluator :contains do
+      self.evaluation_method = ->(lhs, rhs) { lhs.include?(rhs) }
+      self.name = 'contains'
+      self.requires_rhs = true
+    end
+
+    define_evaluator :not_contains do
+      self.evaluation_method = ->(lhs, rhs) { !lhs.include?(rhs) }
+      self.name = 'does not contain'
+    end
+
+    define_evaluator :nil do
+      self.evaluation_method = ->(lhs) { lhs.nil? }
+      self.name = 'exists'
+      self.requires_rhs = false
+    end
+
+    define_evaluator :not_nil do
+      self.evaluation_method = ->(lhs) { !lhs.nil? }
+      self.name = 'does not exist'
+      self.requires_rhs = false
+    end
+
+    define_evaluator :matches do
+      self.evaluation_method = ->(lhs, rhs) { !!(lhs =~ Regexp.new(rhs)) }
+      self.name = 'matches'
+      self.requires_rhs = true
+    end
+
+    define_evaluator :not_matches do
+      self.evaluation_method = ->(lhs, rhs) { !(lhs =~ Regexp.new(rhs)) }
+      self.name = 'does not match'
+      self.requires_rhs = true
+    end
+
+    define_evaluator :less_than do
+      self.evaluation_method = ->(lhs, rhs) { lhs < rhs }
+      self.name = 'less than'
+      self.requires_rhs = true
+    end
+
+    define_evaluator :less_than_or_equal_to do
+      self.evaluation_method = ->(lhs, rhs) { lhs <= rhs }
+      self.name = 'less than or equal to'
+      self.requires_rhs = true
+    end
+
+    define_evaluator :greater_than do
+      self.evaluation_method = ->(lhs, rhs) { lhs > rhs }
+      self.name = 'greater than'
+      self.requires_rhs = true
+    end
+
+    define_evaluator :greater_than_or_equal_to do
+      self.evaluation_method = ->(lhs, rhs) { lhs >= rhs }
+      self.name = 'greater than or equal to'
+      self.requires_rhs = true
+    end
+  end
+end

data/lib/rules/evaluators/evaluator.rb

@@ -0,0 +1,25 @@
+module Rules
+  module Evaluators
+    class Evaluator
+      attr_accessor :evaluation_method, :requires_rhs, :name
+
+      def initialize(key)
+        @name = key.to_s
+        @requires_rhs = true
+      end
+
+      def evaluate(lhs, rhs = nil)
+        raise 'Unknown evaluation method' unless evaluation_method
+        requires_rhs? ? evaluation_method.call(lhs, rhs) : evaluation_method.call(lhs)
+      end
+
+      def requires_rhs?
+        @requires_rhs
+      end
+
+      def to_s
+        @name
+      end
+    end
+  end
+end

data/lib/rules/extensions/active_admin/dsl.rb

@@ -0,0 +1,31 @@
+ActiveAdmin::FormBuilder.class_eval do
+  def has_rules
+    self.inputs 'Rules' do
+      self.semantic_fields_for :rule_set do |rules_rule_set_form|
+        rules_rule_set_form.has_many :rules do |rules_rule_form|
+          rules_rule_form.input :lhs_parameter, :label => 'Left hand side', collection: rules_parameter_collection(rules_rule_form.object.rule_set)
+          rules_rule_form.input :evaluator, :as => :select, :collection => Rules.evaluators.map {|key, evaluator| [evaluator.name, key] }.sort_by {|name, key| name }
+          rules_rule_form.input :rhs_parameter, :label => 'Right hand side'
+        end
+        rules_rule_set_form.input :evaluation_logic, :as => :select, :label => 'Must match', collection: [['All Rules', 'all'], ['Any Rules', 'any']]
+      end
+    end
+  end
+
+  def rules_parameter_collection(rule_set)
+    @rules_parameter_collection ||= Rules.constants.merge(rule_set.try(:attributes) || {}).map {|key, const| [const.name, key] }
+  end
+end
+
+ActiveAdmin::Views::Pages::Show.class_eval do
+  def show_rules
+    panel "Rules" do
+      div resource.rule_set.evaluation_logic == 'any' ? 'Must match any rule' : 'Must match all rules'
+      table_for resource.rule_set.rules do |rule|
+        column('Left hand side') { |rule| rule.lhs_parameter_object.to_s.titleize }
+        column('Condition') { |rule| rule.get_evaluator }
+        column('Right hand side') { |rule| rule.rhs_parameter_value.to_s }
+      end
+    end
+  end
+end

data/lib/rules/has_rules.rb

@@ -0,0 +1,24 @@
+module Rules
+  module HasRules
+    def self.included(base)
+      base.instance_eval do
+        has_one :rule_set, class_name: 'Rules::RuleSet', as: :source, dependent: :destroy
+
+        attr_accessible :rule_set_attributes
+        accepts_nested_attributes_for :rule_set, allow_destroy: true
+
+        def has_rule_attributes(attributes = {})
+          Rules::RuleSet.set_attributes_for(self, attributes)
+        end
+      end
+    end
+
+    def rule_set
+      super || Rules::RuleSet.new
+    end
+
+    def rules_pass?(options = {})
+      rule_set.nil? || rule_set.evaluate(options)
+    end
+  end
+end

data/lib/rules/parameters.rb

@@ -0,0 +1,20 @@
+module Rules
+  module Parameters
+    require 'rules/parameters/parameter'
+    require 'rules/parameters/attribute'
+    require 'rules/parameters/constant'
+
+    @@constants ||= {}
+
+    def self.constants
+      @@constants
+    end
+
+    def self.define_constant(key, &block)
+      raise "Constant #{key} already exists" if @@constants[key]
+      constant = Constant.new(key)
+      constant.instance_eval(&block) if block_given?
+      @@constants[key] = constant
+    end
+  end
+end

data/lib/rules/parameters/attribute.rb

@@ -0,0 +1,16 @@
+require 'rules/parameters/parameter'
+
+module Rules::Parameters
+  class Attribute < Parameter
+    attr_reader :key
+
+    def initialize(options = {})
+      @name = options[:name]
+      @key  = options[:key].to_sym
+    end
+
+    def evaluate(attributes = {})
+      attributes.fetch(key)
+    end
+  end
+end

data/lib/rules/parameters/constant.rb

@@ -0,0 +1,25 @@
+require 'rules/parameters/parameter'
+
+module Rules::Parameters
+  class Constant < Parameter
+    attr_accessor :evaluation_method, :casting_method, :input_type
+
+    def initialize(key)
+      self.name = key.to_s
+    end
+
+    def evaluate(attributes = {})
+      raise 'Unknown evaluation method' unless evaluation_method
+      evaluation_method.call
+    end
+
+    def input_type
+      @input_type || :string
+    end
+
+    def cast(value)
+      return value unless casting_method
+      casting_method.call(value)
+    end
+  end
+end