rules 0.0.1 → 0.1.0

data/README.md

@@ -1,5 +1,6 @@
-AR Rules
+Rules
 =========
+[![build status](https://secure.travis-ci.org/azach/rules.png?branch=master)](https://secure.travis-ci.org/azach/rules) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/azach/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.
 
@@ -8,7 +9,7 @@ Installation
 Add it to your Gemfile:
 
 ```ruby
-gem "rules", :github => 'azach/rules'
+gem "rules"
 ```
 
 Update your schema:
@@ -33,6 +34,7 @@ class Order < ActiveRecord::Base
   has_rule_attributes({
     customer_email: {
       name: "customer email address"
+      type: :string   # see Rules::Parameters::Parameter::VALID_TYPES for a full list
     }
   })
 end
@@ -45,7 +47,7 @@ For example:
 ```ruby
 order = Order.new
 order.email_address = "morbo@example.com"
-order.evaluate(customer_email: order.email_address)
+order.rules_pass?(customer_email: order.email_address)
 ```
 
 Defining Rules
@@ -70,6 +72,41 @@ 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)
 
+However, rules are defined using keys and values, so you can easily use your own custom solution.
+
+```ruby
+rule = Rules::Rule.new(lhs_parameter_key: 'day_of_week', evaluator_key: 'equals', rhs_parameter_raw: 'Sunday')
+rule.lhs_parameter_value
+=> 'Sunday' # (or the current day of week)
+rule.evaluate
+=> true
+
+Order.has_rule_attributes(customer_email: { name: "Customer's email address" })
+order = Order.new
+rule_set = Rules::RuleSet.new(source: order)
+
+rule = Rules::Rule.new(rule_set: rule_set, lhs_parameter_key: 'customer_email', evaluator_key: 'matches', rhs_parameter_raw: 'example.com$')
+rule.lhs_parameter_value
+=> nil  # we didn't pass anything in
+rule.rhs_parameter_value
+=> /example.com$/  # this is a Regexp class
+rule.evaluate(customer_email: 'john@example.com')
+=> true
+rule.evaluate(customer_email: 'john@example.net')
+=> false
+```
+
+Configuration
+------------
+You can add an initializer to configure default options.
+
+```ruby
+Rules.configure do |config|
+  config.errors_are_false           = true  # return false if an evaluator raises an error (true by default)
+  config.missing_attributes_are_nil = true  # return nil when a value is not passed for an attribute parameter
+end
+```
+
 Default Constants
 ------------
 TODO

data/db/migrate/20120831163952_create_rules.rb

@@ -2,8 +2,7 @@ class CreateRules < ActiveRecord::Migration
   def change
     create_table :rules_rules do |t|
       t.belongs_to :rule_set
-      t.string :evaluator
-      t.text :parameters
+      t.text :expression
 
       t.timestamps
     end

data/lib/assets/javascripts/rules/active_admin.js

@@ -0,0 +1,21 @@
+$(function() {
+  $('.rules_rule_set select[name*="[lhs_parameter_key]"]').on('change', function(ev) {
+    var $rawInput;
+    var selectedType;
+
+    $rawInput = $(this).parent('li').siblings('[id*="rhs_parameter_raw_input"]').find('input');
+    selectedType = $(this).find(':selected').data('type');
+
+    $rawInput.get(0).type = selectedType;
+  });
+
+    $('.rules_rule_set select[name*="[evaluator_key]"]').on('change', function(ev) {
+    var $rhsInputs;
+    var requiresRHS;
+
+    $rawInputs = $(this).parent('li').siblings('[id*="rhs_parameter"]').find('input, select');
+    requiresRHS = $(this).find(':selected').data('requires-rhs');
+
+    $rawInputs.prop('disabled', !requiresRHS);
+  });
+});

data/lib/rules.rb

@@ -1,4 +1,7 @@
 require 'rules/engine'
+require 'rules/extensions/active_model/absence_validator'
+require 'rules/extensions/active_model/parameter_key_validator'
+require 'rules/config'
 require 'rules/evaluators'
 require 'rules/evaluators/definitions'
 require 'rules/has_rules'
@@ -8,6 +11,14 @@ require 'rules/rule'
 require 'rules/rule_set'
 
 module Rules
+  def self.config
+    @config ||= Config.instance
+  end
+
+  def self.configure
+    yield config
+  end
+
   def self.evaluators
     @evaluators ||= Evaluators.list
   end

data/lib/rules/config.rb

@@ -0,0 +1,20 @@
+require 'singleton'
+
+class Rules::Config
+  include Singleton
+
+  attr_accessor :errors_are_false, :missing_attributes_are_nil
+
+  def initialize
+    self.errors_are_false           = true
+    self.missing_attributes_are_nil = true
+  end
+
+  def missing_attributes_are_nil?
+    !!missing_attributes_are_nil
+  end
+
+  def errors_are_false?
+    !!errors_are_false
+  end
+end

data/lib/rules/engine.rb

@@ -5,6 +5,7 @@ module Rules
     initializer :active_admin do
       if defined? ActiveAdmin
         require 'rules/extensions/active_admin/dsl'
+        ActiveAdmin.application.javascripts << 'rules/active_admin.js'
       end
     end
   end

data/lib/rules/evaluators/definitions.rb

@@ -35,14 +35,16 @@ module Rules
     end
 
     define_evaluator :matches do
-      self.evaluation_method = ->(lhs, rhs) { !!(lhs =~ Regexp.new(rhs)) }
+      self.evaluation_method = ->(lhs, rhs) { !!(lhs =~ rhs) }
       self.name = 'matches'
+      self.type_for_rhs = :regexp
       self.requires_rhs = true
     end
 
     define_evaluator :not_matches do
-      self.evaluation_method = ->(lhs, rhs) { !(lhs =~ Regexp.new(rhs)) }
+      self.evaluation_method = ->(lhs, rhs) { !(lhs =~ rhs) }
       self.name = 'does not match'
+      self.type_for_rhs = :regexp
       self.requires_rhs = true
     end
 

data/lib/rules/evaluators/evaluator.rb

@@ -1,7 +1,7 @@
 module Rules
   module Evaluators
     class Evaluator
-      attr_accessor :evaluation_method, :requires_rhs, :name
+      attr_accessor :evaluation_method, :requires_rhs, :type_for_rhs, :name
 
       def initialize(key)
         @name = key.to_s
@@ -10,7 +10,13 @@ module Rules
 
       def evaluate(lhs, rhs = nil)
         raise 'Unknown evaluation method' unless evaluation_method
-        requires_rhs? ? evaluation_method.call(lhs, rhs) : evaluation_method.call(lhs)
+
+        begin
+          requires_rhs? ? evaluation_method.call(lhs, rhs) : evaluation_method.call(lhs)
+        rescue StandardError => ex
+          return false if Rules.config.errors_are_false?
+          raise ex
+        end
       end
 
       def requires_rhs?

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

@@ -1,31 +1,32 @@
-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
+ActiveAdmin::FormBuilder.class_eval do
+  def has_rules
+    inputs 'Rules' do
+      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_key, :label => 'Left hand side', collection: rules_parameter_collection(object.rule_set)
+          rules_rule_form.input :evaluator_key, :label => 'Evaluator', :as => :select, :collection => Rules.evaluators.map {|key, evaluator| [evaluator.name, key, {:'data-requires-rhs' => evaluator.requires_rhs?}] }.sort_by {|name, key| name }
+          rules_rule_form.input :rhs_parameter_raw, :label => 'Enter a value', :wrapper_html => { :class => "rules_rhs_parameter" }
+          rules_rule_form.input :rhs_parameter_key, :label => 'Or choose a value', collection: rules_parameter_collection(object.rule_set), :wrapper_html => { :class => "rules_rhs_parameter" }
+        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, {:'data-type' => const.try(:type) || 'string'}] }
+  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.to_s }
+        column('Condition') { |rule| rule.evaluator }
+        column('Right hand side') { |rule| rule.rhs_parameter.to_s }
+      end
+    end
+  end
+end

data/lib/rules/extensions/active_model/absence_validator.rb

@@ -0,0 +1,5 @@
+class AbsenceValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    record.errors.add attribute, (options[:message] || "must be blank") unless value.blank?
+  end
+end

data/lib/rules/extensions/active_model/parameter_key_validator.rb

@@ -0,0 +1,7 @@
+class ParameterKeyValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    unless record.valid_parameter_keys.include?(value)
+      record.errors.add attribute, (options[:message] || "is not a valid parameter")
+    end
+  end
+end

data/lib/rules/has_rules.rb

@@ -14,7 +14,7 @@ module Rules
     end
 
     def rule_set
-      super || Rules::RuleSet.new
+      super || self.build_rule_set
     end
 
     def rules_pass?(options = {})

data/lib/rules/parameters.rb

@@ -12,7 +12,7 @@ module Rules
 
     def self.define_constant(key, &block)
       raise "Constant #{key} already exists" if @@constants[key]
-      constant = Constant.new(key)
+      constant = Constant.new(key: key)
       constant.instance_eval(&block) if block_given?
       @@constants[key] = constant
     end

data/lib/rules/parameters/attribute.rb

@@ -2,15 +2,12 @@ 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)
+      if Rules.config.missing_attributes_are_nil?
+        attributes[key]
+      else
+        attributes.fetch(key)
+      end
     end
   end
 end

data/lib/rules/parameters/constant.rb

@@ -2,24 +2,11 @@ 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
+    attr_accessor :evaluation_method
 
     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

data/lib/rules/parameters/constant_definitions.rb

@@ -1,15 +1,14 @@
-module Rules
-  module Parameters
-    define_constant :today do
-      self.name = 'current date'
-      self.input_type = :date_select
-      self.evaluation_method = -> { Time.now.utc.to_date }
-      self.casting_method = ->(value) { value.is_a?(Date) ? value : Date.parse(value.to_s) }
-    end
-
-    define_constant :day_of_week do
-      self.name = 'day of week'
-      self.evaluation_method = -> { Date::DAYNAMES[Time.now.utc.to_date.wday] }
-    end
-  end
-end
+module Rules
+  module Parameters
+    define_constant :today do
+      self.name = 'current date'
+      self.type = :date
+      self.evaluation_method = -> { Time.now.utc.to_date }
+    end
+
+    define_constant :day_of_week do
+      self.name = 'day of week'
+      self.evaluation_method = -> { Date::DAYNAMES[Time.now.utc.to_date.wday] }
+    end
+  end
+end

data/lib/rules/parameters/parameter.rb

@@ -1,13 +1,39 @@
-module Rules::Parameters
-  class Parameter
-    attr_accessor :name
-
-    def cast(value)
-      value
-    end
-
-    def to_s
-      name
-    end
-  end
-end
+module Rules::Parameters
+  class Parameter
+    VALID_TYPES = [:date, :integer, :float, :boolean, :string, :regexp]
+
+    attr_accessor :name, :type, :key
+
+    def self.cast(value, type)
+      return value unless type
+      case type
+      when :date
+        Date.parse(value.to_s)
+      when :integer
+        value.to_i
+      when :float
+        value.to_f
+      when :boolean
+        value.to_s == 'true' ? true : false
+      when :string
+        value.to_s
+      when :regexp
+        Regexp.new(value.to_s)
+      else
+        raise "Don't know how to cast #{type}"
+      end
+    end
+
+    def initialize(options = {})
+      self.key  = options[:key].to_sym
+      self.name = options[:name] || options[:key].to_s.humanize
+      self.type = options[:type] if options[:type]
+
+      raise "Unknown type #{type}" if type && !VALID_TYPES.include?(type)
+    end
+
+    def to_s
+      name
+    end
+  end
+end

data/lib/rules/rule.rb

@@ -1,52 +1,85 @@
-require 'rules/evaluators'
-require 'rules/parameters'
-
-module Rules
-  class Rule < ActiveRecord::Base
-    attr_accessible :rule_set, :evaluator, :lhs_parameter, :rhs_parameter
-
-    belongs_to :rule_set, class_name: 'Rules::RuleSet'
-
-    validates :evaluator, presence: true, inclusion: {in: Evaluators.list.keys.map(&:to_s)}
-    validates :lhs_parameter, presence: true, inclusion: {in: ->(rule) { rule.valid_parameters }}
-    validates :rhs_parameter, presence: true, if: ->(rule) { rule.get_evaluator.try(:requires_rhs?) }
-    validates :rhs_parameter, inclusion: {in: [nil, ''], message: 'must be blank for this evaluation method'}, unless: ->(rule) { rule.get_evaluator.try(:requires_rhs?) }
-
-    store :parameters, :accessors => [:lhs_parameter, :rhs_parameter]
-
-    def evaluate(attributes = {})
-      lhv = lhs_parameter_value(attributes)
-      rhv = rhs_parameter_value if get_evaluator.requires_rhs?
-      get_evaluator.evaluate(lhv, rhv)
-    end
-
-    def get_evaluator
-      @get_evaluator ||= evaluator ? Evaluators.list[evaluator.to_sym] : nil
-    end
-
-    def lhs_parameter_value(attributes = {})
-      lhs_parameter_object.try(:evaluate, attributes)
-    end
-
-    def rhs_parameter_value
-      lhs_parameter_object ? lhs_parameter_object.cast(rhs_parameter) : rhs_parameter
-    end
-
-    def lhs_parameter_object
-      @lhs_parameter_object ||= if lhs_parameter
-        Parameters.constants[lhs_parameter.to_sym] \
-          || valid_attributes[lhs_parameter.to_sym]
-      else
-        nil
-      end
-    end
-
-    def valid_parameters
-      Parameters.constants.keys.map(&:to_s) + valid_attributes.keys.map(&:to_s)
-    end
-
-    def valid_attributes
-      rule_set ? rule_set.attributes : {}
-    end
-  end
-end
+require 'rules/evaluators'
+require 'rules/parameters'
+
+module Rules
+  class Rule < ActiveRecord::Base
+    attr_accessible :rule_set, :evaluator_key, :lhs_parameter_key, :rhs_parameter_key, :rhs_parameter_raw
+
+    belongs_to :rule_set, class_name: 'Rules::RuleSet'
+
+    validates :evaluator_key, presence: true, inclusion: {in: Evaluators.list.keys.map(&:to_s)}
+    validates :lhs_parameter_key, parameter_key: true
+    validates :rhs_parameter_key, parameter_key: true, if: :rhs_parameter_key
+    validates :rhs_parameter_key, presence: true, if: :requires_rhs?, unless: :rhs_parameter_raw
+    validates :rhs_parameter_key, absence: true, unless: :requires_rhs?
+    validates :rhs_parameter_raw, absence: true, unless: :requires_rhs?
+    validates :rhs_parameter_key, absence: true, if: :rhs_parameter_raw
+
+    store :expression, :accessors => [:evaluator_key, :lhs_parameter_key, :rhs_parameter_key, :rhs_parameter_raw]
+
+    def evaluate(attributes = {})
+      lhv = lhs_parameter_value(attributes)
+      rhv = rhs_parameter_value(attributes) if evaluator.requires_rhs?
+      evaluator.evaluate(lhv, rhv)
+    end
+
+    def evaluator
+      @evaluator ||= evaluator_key ? Evaluators.list[evaluator_key.to_sym] : nil
+    end
+
+    def lhs_parameter_key
+      key_from_store :lhs_parameter_key
+    end
+
+    def rhs_parameter_key
+      key_from_store :rhs_parameter_key
+    end
+
+    def evaluator_key
+      key_from_store :evaluator_key
+    end
+
+    def lhs_parameter_value(attributes = {})
+      lhs_parameter.try(:evaluate, attributes)
+    end
+
+    def rhs_parameter_value(attributes = {})
+      if rhs_parameter.respond_to?(:evaluate)
+        rhs_parameter.try(:evaluate, attributes)
+      else
+        rhv = Parameters::Parameter.cast(rhs_parameter_raw, lhs_parameter.try(:type))
+        Parameters::Parameter.cast(rhv, evaluator.try(:type_for_rhs))
+      end
+    end
+
+    def rhs_parameter
+      rhs_parameter_key ? parameter_from_key(rhs_parameter_key) : rhs_parameter_raw
+    end
+
+    def lhs_parameter
+      @lhs_parameter ||= lhs_parameter_key ? parameter_from_key(lhs_parameter_key) : nil
+    end
+
+    def valid_parameter_keys
+      Parameters.constants.keys.map(&:to_s) + valid_attributes.keys.map(&:to_s)
+    end
+
+    def valid_attributes
+      rule_set ? rule_set.attributes : {}
+    end
+
+    def requires_rhs?
+      evaluator ? evaluator.requires_rhs? : false
+    end
+
+    private
+
+    def key_from_store(key)
+      expression[key].blank? ? nil : expression[key]
+    end
+
+    def parameter_from_key(key)
+      Parameters.constants[key.to_sym] || valid_attributes[key.to_sym]
+    end
+  end
+end