scoring_rules 0.0.1

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in scoring_rules.gemspec
+gemspec

data/README.textile

@@ -0,0 +1,80 @@
+h1. scoring_rules
+
+A small library that provides a simple DSL for creating scoring rules (for rankings, rating and similar uses).
+
+Does scoring_rules helps your daily work with Rails? So, "please recommend me":http://workingwithrails.com/recommendation/new/person/9370-lucas-h-ngaro on Working With Rails. Thanks for your kindness! :)
+
+h2. Why?
+
+This kind of feature could by implemented without a DSL, but this really helps to build a transparent representation of business rules that is self-contained and easier to modify. Also, even if not a primary goal, this way of representation is easier for non-tech people to understand.
+
+h2. How?
+
+First, install the gem:
+
+<pre>
+$ [sudo] gem install scoring_rules
+</pre>
+
+Then, add it as a dependency in your code using your favorite way (a simple require or mechanisms like the Bundler gem).
+
+The gem will provide you a module to mixin into your classes.
+
+<pre>
+class User
+  include ScoringRules
+
+  scoring_rules do |rule|
+    rule.add_points    10, :if => lambda {self.age >= 18} # adds 10
+    rule.remove_points  5, :if => :can_remove? # removes 5
+    rule.add_points     5, :unless => lambda {self.is_new_user?} # does nothing
+    rule.add_points     1, :each => :followers # adds 300
+  end
+
+  def followers
+    r = OpenStruct.new
+    r.count = 300
+    r
+  end
+
+  def can_remove?
+    true
+  end
+
+  def age
+    20
+  end
+
+  def is_new_user?
+    true
+  end
+end
+</pre>
+
+Each rule requires one condition, expressed through :if, :unless or :each. For now you can't supply more than one condition per rule (it was a goal, but proved unnecessary).
+
+And to calculate the score, it's really simple:
+
+<pre>
+> user = User.get_me_some_user_from_somewhere
+> user.calculate_score
+=> 305
+</pre>
+
+h2. Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+h2. Contributors
+
+Be a contributor! :)
+
+h3. Copyright
+
+Copyright (c) 2010 Lucas Húngaro. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec

data/lib/scoring_rules.rb

@@ -0,0 +1,27 @@
+require "scoring_rules/metaid"
+require "scoring_rules/ruleset"
+require "scoring_rules/rule"
+require "scoring_rules/condition"
+
+module ScoringRules
+  module ClassMethods
+    def scoring_rules
+      raise(ArgumentError, "You must supply a block with the rules") unless block_given?
+      self.ruleset = Ruleset.new
+      yield self.ruleset
+    end
+  end
+
+  module InstanceMethods
+    def calculate_score
+      self.class.ruleset.evaluate(self)
+    end
+  end
+
+  def self.included(receiver)
+    receiver.extend         ClassMethods
+    receiver.send :include, InstanceMethods
+
+    receiver.meta_eval { attr_accessor :ruleset }
+  end
+end

data/lib/scoring_rules/condition.rb

@@ -0,0 +1,32 @@
+class Condition
+  def initialize(type, method)
+    @type = type
+    @method = method
+  end
+
+  def evaluate(instance)
+    case @type
+      when :if
+        dispatch_pre_condition(instance)
+      when :unless
+        (dispatch_pre_condition(instance) - 1) * -1
+      when :each
+        dispatch_collection(instance)
+    end
+  end
+
+  private
+  def dispatch_pre_condition(instance)
+    result = 0
+    if @method.is_a?(Symbol)
+      result = instance.send(@method) ? 1 : 0
+    elsif @method.is_a?(Proc)
+      result = instance.instance_exec(&@method) ? 1 : 0
+    end
+    result
+  end
+
+  def dispatch_collection(instance)
+    result = instance.send(@method).count
+  end
+end

data/lib/scoring_rules/metaid.rb

@@ -0,0 +1,17 @@
+# Code by why_the_lucky_stiff
+
+class Object
+  # The hidden singleton lurks behind everyone
+  def metaclass; class << self; self; end; end
+  def meta_eval &blk; metaclass.instance_eval &blk; end
+
+  # Adds methods to a metaclass
+  def meta_def name, &blk
+    meta_eval { define_method name, &blk }
+  end
+
+  # Defines an instance method within a class
+  def class_def name, &blk
+    class_eval { define_method name, &blk }
+  end
+end

data/lib/scoring_rules/rule.rb

@@ -0,0 +1,12 @@
+class Rule
+  attr_accessor :points
+
+  def initialize(points, condition)
+    @points = points
+    @condition = condition
+  end
+
+  def evaluate(instance)
+    @condition.evaluate(instance) * @points
+  end
+end

data/lib/scoring_rules/ruleset.rb

@@ -0,0 +1,48 @@
+class Ruleset
+  def initialize
+    @rules = []
+  end
+
+  def add_points(points, criteria)
+    add_rule create_rule(points, criteria)
+  end
+
+  def remove_points(points, criteria)
+    add_rule create_rule(points, criteria, :multiplier => -1)
+  end
+
+  def evaluate(instance)
+    @rules.inject(0) do |memo, rule|
+      memo += rule.evaluate(instance)
+    end
+  end
+
+  private
+    def create_rule(points, criteria, options = {})
+      options[:multiplier] = 1 unless options[:multiplier]
+      validade_conditions(criteria)
+      condition = build_condition_from_criteria(criteria)
+      rule = Rule.new(points * options[:multiplier], condition)
+    end
+
+    def build_condition_from_criteria(criteria)
+      condition_data = criteria.shift
+      Condition.new(condition_data[0], condition_data[1])
+    end
+
+    def validade_conditions(criteria)
+      valid_keys = [:if, :unless, :each]
+      keys = criteria.keys
+
+      raise(ArgumentError, "Each rule should have a condition") if keys.size == 0
+
+      unknown_keys = keys - [valid_keys].flatten
+      raise(ArgumentError, "Unknown key(s): #{unknown_keys.join(", ")}") unless unknown_keys.empty?
+
+      raise(ArgumentError, "Each rule should have only one condition") if keys.size > 1
+    end
+
+    def add_rule(rule)
+      @rules << rule
+    end
+end

data/lib/scoring_rules/version.rb

@@ -0,0 +1,3 @@
+module ScoringRules
+  VERSION = "0.0.1"
+end

data/scoring_rules.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "scoring_rules/version"
+
+Gem::Specification.new do |s|
+  s.name        = "scoring_rules"
+  s.version     = ScoringRules::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Lucas Húngaro"]
+  s.email       = ["lucashungaro@gmail.com"]
+  s.homepage    = "http://rubygems.org/gems/scoring_rules"
+  s.summary     = %q{A small library that provides a simple DSL for creating scoring rules (for rankings, rating and similar uses).}
+  s.description = %q{A small library that provides a simple DSL for creating scoring rules (for rankings, rating and similar uses).}
+
+  s.rubyforge_project = "scoring_rules"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+  s.add_development_dependency(%q<mocha>, [">= 0.9.8"])
+end

data/spec/fixtures/my_model.rb

@@ -0,0 +1,19 @@
+class MyModel
+  def followers
+    r = OpenStruct.new
+    r.count = 300
+    r
+  end
+
+  def can_remove?
+    true
+  end
+
+  def age
+    20
+  end
+
+  def is_new_user?
+    true
+  end
+end

data/spec/fixtures/rulesets.rb

@@ -0,0 +1,33 @@
+VALID_RULESET = <<-CODE
+scoring_rules do |rule|
+  rule.add_points    10, :if => lambda {self.age >= 18}
+  rule.remove_points  5, :if => :can_remove?
+  rule.add_points     5, :unless => lambda {self.is_new_user?}
+  rule.add_points     1, :each => :followers
+end
+CODE
+
+INVALID_RULESET_EMPTY = <<-CODE
+scoring_rules
+CODE
+
+INVALID_RULESET_MANY_CONDITIONS = <<-CODE
+scoring_rules do |rule|
+  rule.add_points 10, :if => lambda {self.age >= 18}, :unless => lambda {true}
+  rule.remove_points 5, :if => :can_remove?
+end
+CODE
+
+INVALID_RULESET_NO_CONDITIONS = <<-CODE
+scoring_rules do |rule|
+  rule.add_points 10
+  rule.remove_points 5, :if => :can_remove?
+end
+CODE
+
+INVALID_RULESET_NON_EXISTENT_CONDITIONS = <<-CODE
+scoring_rules do |rule|
+  rule.add_points 10, :crazy => lambda {true}
+  rule.remove_points 5, :if => :can_remove?
+end
+CODE

data/spec/scoring_rules_spec.rb

@@ -0,0 +1,49 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require File.expand_path(File.dirname(__FILE__) + '/fixtures/my_model')
+require File.expand_path(File.dirname(__FILE__) + '/fixtures/rulesets')
+
+describe ScoringRules do
+  before(:each) do
+    MyModel.send(:include, ScoringRules)
+  end
+  
+  after(:each) do
+    # reload the file to undefine the rule set
+    load File.expand_path(File.dirname(__FILE__) + '/fixtures/my_model.rb')    
+  end
+  
+  context "contract" do   
+    specify "rule set needs a block with its rules" do
+      doing {
+        MyModel.class_eval {eval INVALID_RULESET_EMPTY}
+      }.should raise_exception(ArgumentError)      
+    end
+     
+    specify "every rule should accept only one condition" do
+      doing {
+        MyModel.class_eval {eval INVALID_RULESET_MANY_CONDITIONS}
+      }.should raise_exception(ArgumentError)
+    end
+    
+    specify "every rule should have a condition" do
+      doing {
+        MyModel.class_eval {eval INVALID_RULESET_NO_CONDITIONS}
+      }.should raise_exception(ArgumentError)
+    end
+    
+    specify "only accepted conditions are :if, :unless and :each" do
+      doing {
+        MyModel.class_eval {eval INVALID_RULESET_NON_EXISTENT_CONDITIONS}
+      }.should raise_exception(ArgumentError)
+    end
+  end
+  
+  context "functionality" do
+    it "should correctly calculate the object score according to the rule set" do
+      MyModel.class_eval {eval VALID_RULESET}
+      obj = MyModel.new
+      
+      obj.calculate_score.should == 305
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'scoring_rules'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end
+
+alias doing lambda

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification 
+name: scoring_rules
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- "Lucas H\xC3\xBAngaro"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-08 00:00:00 -02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 43
+        segments: 
+        - 0
+        - 9
+        - 8
+        version: 0.9.8
+  type: :development
+  version_requirements: *id002
+description: A small library that provides a simple DSL for creating scoring rules (for rankings, rating and similar uses).
+email: 
+- lucashungaro@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.textile
+- Rakefile
+- lib/scoring_rules.rb
+- lib/scoring_rules/condition.rb
+- lib/scoring_rules/metaid.rb
+- lib/scoring_rules/rule.rb
+- lib/scoring_rules/ruleset.rb
+- lib/scoring_rules/version.rb
+- scoring_rules.gemspec
+- spec/fixtures/my_model.rb
+- spec/fixtures/rulesets.rb
+- spec/scoring_rules_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://rubygems.org/gems/scoring_rules
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: scoring_rules
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A small library that provides a simple DSL for creating scoring rules (for rankings, rating and similar uses).
+test_files: 
+- spec/fixtures/my_model.rb
+- spec/fixtures/rulesets.rb
+- spec/scoring_rules_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb