torm 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28b08b8646e0f7e2e8345d914abc082a018c9d50
-  data.tar.gz: f0a53d0a8ac7b90010733cadfb0d7f82f43d0efb
+  metadata.gz: cf7d146ecc3d6ebd40de586588fefc52a94d4552
+  data.tar.gz: c861e3383026631ec4c2e293555e16c30963bb5f
 SHA512:
-  metadata.gz: faabf0c69a4bf2efb60baf50307b6e67661145c9ddc25a0dfd6ac282508e9e529e18a41ada804a8b9a847a3fab149d296190c57661a57a9b325e855fceca61e7
-  data.tar.gz: acaa6b02d117fd38a6765d122170172346decf05634f3dffaea74818aef871ba559477b5617ef1b31a5594dad3b9e447eaab7a377e8b340820a60d72fbb94719
+  metadata.gz: d55a9a923f5fb23af03694b42e01c6bad1c295f4e0529be376832c71b6e9054ab2d4816c4cf99fbe22dfb729ea832c745b74a23e1909da904eee0e493606eb72
+  data.tar.gz: 43d60da6351014ab2576d994c60333e17749883801fa1aaadc8078166860120abadbc7e45254a649b8130933f23ff747ced466fab8f744a883575af2da4bde93

data/README.md

@@ -18,22 +18,36 @@ Or install it yourself as:
 
     $ gem install torm
 
-## Usage
+## Example in a (Rails) app context
+
+Load the rules engine, define defaults so new rules get saved.
 
 ```ruby
-# Setup a new engine
+# Set a custom rules file before accessing the default rules engine.
+Torm.default_rules_file = Rails.root.join('tmp/my_rules.json').to_s
+
+# Torm.set_defaults will load an engine if a rules file exists, otherwise you get an empty engine.
+# Add rules, then after the block it will automatically save the rules file when new rules were changed.
+Torm.set_defaults do |engine|
+  # Add a new rule named 'Happy', with a 'default' policy value of true
+  engine.add_rules 'Happy', true, :default do |rule|
+    # Add a variant on the 'Happy' rule: we're not happy when it rains
+    rule.variant false, :default, rain: true
+    # Another variant. Due to the abundance of rain, in Great Britain the law dictates you're still happy when it rains.
+    rule.variant true, :law, rain: true, country: 'GB'
+  end
+end
+
+# Torm.instance holds the default engine used by Torm.set_defaults, so we can use it for making decisions.
+Torm.instance.decide('Happy', country: 'NL')                # => true
+Torm.instance.decide('Happy', country: 'NL', rain: true)    # => false
+Torm.instance.decide('Happy', country: 'GB', rain: true)    # => true
+
+
+# If you need more rules engines, instantiate a non-global engine when you need one.
 engine = Torm::RulesEngine.new
-
-# Define a bunch of rules: name, value/range, priority, conditions
-# Each rule should at least have a default value without any conditions.
-# Default priorities: :law > :coc > :experiment > :default
-engine.add_rule 'FSK level', 1..18, :default
-engine.add_rule 'FSK level', { maximum: 16 }, :coc, country: 'FR'
-engine.add_rule 'FSK level', { minimum: 12 }, :default, sexy: true
-
-# Let the engine decide which rules apply and how they intersect
-engine.decide('FSK level', country: 'NL')              # => {minimum: 1, maximum: 18}
-engine.decide('FSK level', country: 'FR', sexy: true)  # => {minimum: 12, maximum: 16}
+engine.add_rule 'Happy', true, :default
+engine.decide('Happy', country: 'NL') # => true
 ```
 
 ## How rules are evaluated

data/lib/torm.rb

@@ -14,15 +14,19 @@ module Torm
 
     attr_accessor :instance, :default_rules_file
 
+    # @return [Torm::RulesEngine] Singleton RulesEngine
     def instance
       @instance ||= RulesEngine.load || RulesEngine.new
     end
 
+    # @return [String] Path where the default rules can be stored
     def default_rules_file
       @default_rules_file ||= File.expand_path('tmp/rules.json')
     end
 
     # Load an engine with the current rules, yield it (to add rules) and then save it if rules were added.
+    #
+    # @yield [Torm::RulesEngine]
     def set_defaults(engine: instance)
       yield engine
       engine.save if engine.dirty?

data/lib/torm/rules_engine.rb

@@ -1,21 +1,22 @@
 module Torm
- class RulesEngine
+  class RulesEngine
     # Policies (priorities) in order of important -> least important.
     DEFAULT_POLICIES = [:law, :coc, :experiment, :default].freeze
 
-    attr_reader :rules
-    attr_accessor :verbose, :policies, :conditions_whitelist
-    attr_accessor :dirty
+    attr_reader :rules, :conditions_whitelist
+    attr_accessor :policies
+    attr_accessor :dirty, :rules_file
 
-    def initialize(rules: {}, conditions_whitelist: {}, dirty: false, policies: DEFAULT_POLICIES.dup, verbose: false)
+    def initialize(rules: {}, dirty: false, policies: DEFAULT_POLICIES.dup, rules_file: Torm.default_rules_file)
       @rules                = rules
-      @conditions_whitelist = conditions_whitelist
       @dirty                = dirty
       @policies             = policies
-      @verbose              = verbose
+      @rules_file           = rules_file
+      @conditions_whitelist = {}
     end
 
     # Have any rules been added since the last save or load?
+    # @return [true, false]
     def dirty?
       @dirty
     end
@@ -38,15 +39,42 @@ module Torm
       self
     end
 
+    # Simple helper class to add the block DSL to add_rules
+    class RuleVariationHelper
+      def initialize(engine, name)
+        @engine = engine
+        @name = name
+      end
+
+      def variation(value, policy, **conditions)
+        @engine.add_rule(@name, value, policy, conditions)
+      end
+    end
+
+    def add_rules(name, value, policy)
+      # Add the default rule
+      add_rule(name, value, policy)
+
+      rule_variation = RuleVariationHelper.new(self, name)
+      yield rule_variation if block_given?
+
+      self
+    end
+
+    # Evaluate a rule and return its result. Depending on the rule, different values are returned.
+    #
+    # @raise [RuntimeError] Raise when the rule is not defined.
     def decide(name, environment={})
       raise "Unknown rule: #{name.inspect}" unless rules.has_key?(name)
       environment          = Torm.symbolize_keys(environment)
       decision_environment = Torm.slice(environment, *conditions_whitelist_for(name))
       answer               = make_decision(name, decision_environment)
-      #Rails.logger.debug "DECISION: #{answer.inspect} (#{name.inspect} -> #{environment.inspect})"
       answer
     end
 
+    # Return a hash with all rules and policies, useful for serialisation.
+    #
+    # @return [Hash]
     def as_hash
       {
         policies: policies,
@@ -54,6 +82,9 @@ module Torm
       }
     end
 
+    # Serialise the data from +as_hash+.
+    #
+    # @return [String]
     def to_json
       MultiJson.dump(as_hash)
     end
@@ -80,26 +111,23 @@ module Torm
       engine
     end
 
-    # Where we store the rules file.
-    def self.rules_file
-      Rails.root.join('tmp', 'rules.json').to_s
-    end
-
     # Load rules from a file and create a new engine for it.
     # Note: this does *not* replace the Torm::RulesEngine.instance, you have to do this yourself if required.
     #
     # @return [Torm::RulesEngine] A new engine with the loaded rules
     def self.load(rules_file: Torm.default_rules_file)
       if File.exist?(rules_file)
-        json = File.read(rules_file)
-        self.from_json(json)
+        json              = File.read(rules_file)
+        engine            = self.from_json(json)
+        engine.rules_file = rules_file
+        engine
       else
         nil
       end
     end
 
-    # Save the current rules to a file.
-    def save(rules_file: self.class.rules_file)
+    # Save the current rules to the file.
+    def save
       Torm.atomic_save(rules_file, to_json + "\n")
       @dirty = false
       nil
@@ -107,7 +135,6 @@ module Torm
 
     private
 
-    # TODO: Refactor once useful
     def make_decision(name, environment={})
       # Fetch all rules for this decision. Duplicate to allow us to manipulate the Array with #reject!
       relevant_rules = rules_for(name).dup
@@ -175,13 +202,5 @@ module Torm
     def rules_for(name)
       rules[name] ||= []
     end
-
-    def puts(message)
-      Kernel.puts(message) if verbose
-    end
-
-    def pp(object)
-      Kernel.pp(object) if verbose
-    end
   end
 end

data/lib/torm/version.rb

@@ -1,3 +1,3 @@
 module Torm
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/test/torm/rules_engine_test.rb

@@ -3,7 +3,7 @@ require 'minitest_helper'
 describe Torm::RulesEngine do
   let(:engine) { Torm::RulesEngine.new }
 
-  describe '.decide' do
+  describe '#add_rule and #decide' do
     describe 'basic decision making' do
       before(:each) do
         engine.add_rule 'show unsubscribe link', false, :default
@@ -100,6 +100,21 @@ describe Torm::RulesEngine do
         engine.decide('FSK level', country: 'FR', sexy: true).must_equal({ minimum: 12, maximum: 16 })
       end
     end
+
+    describe '#add_rules block syntax with #variation' do
+      it 'should just work' do
+        engine.add_rules 'Happy', true, :default do |rule|
+          # Nobody likes rain...
+          rule.variation false, :default, rain: true
+          # ...except for the Brits :-)
+          rule.variation true, :law, rain: true, country: 'GB'
+        end
+
+        assert engine.decide('Happy')
+        assert !engine.decide('Happy', rain: true)
+        assert engine.decide('Happy', rain: true, country: 'GB')
+      end
+    end
   end
 
   describe '#to_json' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: torm
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Wes Oldenbeuving