ruy 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1892173ce87ec0352f8eb0058be130276ac3992d
-  data.tar.gz: 56e8ecb959603b387278c3c7b771eace0cd797dd
+  metadata.gz: a3f59c87798c8d6d5aa92ca7639e4605f60c36c6
+  data.tar.gz: 4d51c3dd0c5e0a9d7c4a8175caf38eccb19e7763
 SHA512:
-  metadata.gz: bdc7bc60c215ca1514262f9b9ff0cce49208590e9fc5597440698a68678c40be21bd740b3539504409f137d433affe2e88ba09df9166f72f3b84e1d4b7cb88bc
-  data.tar.gz: 889a05b473558941b51c3eb4c3ffdd07eb786aef86b2dc8043bb4d51813b9608079f5795285beba19362bec7dd9f830ef8b907e9d69774bfbb4364d8587a6bf2
+  metadata.gz: 71e65bfa1ace338acdcefafbe9a234e5c415bdc1b8075c330fe4831e8f6cebfbd3f70a435656266c7604338c0180692f39af888d1bf7df6f64088233446b550b
+  data.tar.gz: 8c8bb8c7db01b3254d83f53fd44a41dd9257fd2544929dc513360a27ad5805d38676e4568a9d868b6946efe525c7db4f0d101128463eab98a40cfe22f624f0f2

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Moove-iT
+
+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,197 @@
+# ruy
+
+Ruy is a library for defining a set of conditions and evaluating them against a context.
+
+``` ruby
+# discount_day.rb
+gifter = Ruy::RuleSet.new
+
+gifter.eq :friday, :day_of_week
+
+gifter.outcome 8 do
+  greater_than_or_equal 300, :amount
+end
+
+gifter.outcome 7 do
+  greater_than_or_equal 100, :amount
+end
+
+gifter.outcome 3
+
+gifter.fallback 0
+```
+
+RuleSets are evaluated against a context (the `Hash` being passed to `#call`) and return the first outcome that matches.
+
+``` ruby
+gifter.call(day_of_week: :friday, amount: 314)
+
+# => 8
+```
+
+``` ruby
+gifter.call(day_of_week: :friday, amount: 256)
+
+# => 7
+```
+
+If no outcome matches, the default one is returned.
+``` ruby
+gifter.call(day_of_week: :friday, amount: 99)
+
+# => 3
+```
+
+If conditions are not met, the fallback value is returned.
+``` ruby
+gifter.call(day_of_week: :monday, amount: 124)
+
+# => 0
+```
+
+## Key concepts
+
+Ruy at its core is about evaluating a set of conditions against a context in order to return a result.
+
+### Conditions
+
+A condition evaluates the state of the context.
+
+Available conditions:
+
+ - all *All of the nested conditions must suffice*
+ - any *At least one of its nested conditions must suffice*
+ - assert *A context value must be truish*
+ - between *Evaluates that a context value must belong to a specified range*
+ - cond *At least one slice of two nested conditions must suffice*
+ - day_of_week *Evaluates that a Date/DateTime/Time weekday is matched*
+ - eq *Tests a context value for equality*
+ - except *Evaluates that a context value is not equal to a specified value*
+ - greater_than *Tests that context value is greater than something*
+ - greater_than_or_equal *Tests that context value is greater than or equal to something*
+ - in *A context value must belong to a specified list of values*
+ - in_cyclic_order *TBD*
+ - include *The context attribute must include a specified value*
+ - less_than_or_equal *Tests that context value is less than or equal to something*
+ - less_than *Tests that context value is less than something*
+
+Conditions can be nested. In such case, for the nesting condition to be met, the nested conditions must
+also be met.
+
+``` ruby
+between 0, 1_000, :amount do
+  eq :friday, :day_of_week
+end
+```
+
+is equivalent to:
+
+``` ruby
+all do
+  between 0, 1_000, :amount
+  eq :friday, :day_of_week
+end
+```
+
+### Rulsets
+
+A ruleset is a set of conditions that must suffice and returns a value resulting from either an
+outcome or a fallback.
+
+### Contexts
+
+A context is a `Hash` from which values are fetched in order to evaluate a ruleset.
+
+### Lazy values
+
+Rulesets can define lazy values. The context must provide a proc which is evaluted only once the first time the value is needed. The result returned by the proc is memoized and used to evaluate subsequent conditions.
+
+
+``` ruby
+# premium_discount_day.rb
+gifter = Ruy::RuleSet.new
+
+gifter.let :amounts_average # an expensive calculation
+
+gifter.eq :friday, :week_of_day
+
+gifter.greater_than_or_equal 10_000, :amounts_average
+
+gifter.outcome true
+```
+
+``` ruby
+gifter.call(day_of_week: :friday, amounts_average: -> { Stats::Amounts.compute_average })
+```
+### Outcomes
+
+An outcome is the result of a successful ruleset evaluation. An outcome can also have nested
+conditions, in such case, if the conditions meet, the outcome value is returned.
+
+A RuleSet can have multiple outcomes, the first matching one is returned.
+
+### Time Zone awareness
+
+When it comes to matching times in different time zones, Ruy is bundled with a built in `tz` block that will enable specific matchers to make time zone-aware comparisons.
+
+```ruby
+ruleset = Ruy::RuleSet.new
+
+ruleset.tz 'America/New_York' do
+  eq '2015-01-01T00:00:00', :timestamp
+end
+
+ruleset.outcome 'Happy New Year, NYC!'
+```
+
+For example, if the timestamp provided in the context is a Ruby Time object in UTC (zero offset from UTC), `eq` as child of a `tz` block will take the time zone passed as argument to the block (`America/New_York`) to calculate the current offset and make the comparison.
+
+String time patterns follow the Ruy's well-formed time pattern structure as follows:
+
+`YYYY-MM-DDTHH:MM:SS[z<IANA Time Zone Database identifier>]`
+
+Where the time zone identifier is optional, but if you specify it, will take precedence over the block's identifier. In case you don't specify it, Ruy will get the time zone from the `tz` block's argument. If neither the block nor the pettern specify it, UTC will be used.
+
+#### Days of week matcher
+
+Inside any `tz` block, there's a matcher to look for a specific day of the week in the time zone of the block.
+
+```ruby
+ruleset = Ruy::RuleSet.new
+
+ruleset.any do
+  tz 'America/New_York' do
+      day_of_week :saturday, :timestamp
+  end
+
+  tz 'America/New_York' do
+      day_of_week 0, :timestamp # Sunday
+  end
+end
+
+ruleset.outcome 'Have a nice weekend, NYC!'
+```
+
+This matcher supports both the `Symbol` and number syntax in the range `(0..6)` starting on Sunday.
+
+The day of week matcher will try to parse timestamps using the ISO8601 format unless the context passes a Time object.
+
+#### Nested blocks support
+
+You cannot use matchers inside nested blocks in a `tz` block expecting them to work as if they were immediate children of `tz`.
+
+A possible workaround for this is to use `tz` blocks inside the nested block in question:
+
+```ruby
+ruleset = Ruy::RuleSet.new
+any do
+  tz 'America/New_York' { eq '2015-01-01T00:00:00', :timestamp }
+  tz 'America/New_York' { eq '2015-01-01T02:00:00zUTC', :timestamp }
+end
+
+ruleset.outcome 'Happy New Year, NYC!'
+```
+
+Support for time zone awareness in nested blocks inside `tz` blocks is planned. This workaround could stop working in future versions; use it at your own risk.
+
+Ruy depends on [TZInfo](http://tzinfo.github.io/ "TZ Info website") to calculate offsets using IANA's Time Zone Database. Check their website for information about time zone identifiers.

data/lib/ruy.rb

@@ -1,7 +1,8 @@
+require_relative 'ruy/utils'
+require_relative 'ruy/dsl'
 require_relative 'ruy/rule'
 require_relative 'ruy/rule_set'
 require_relative 'ruy/conditions'
 require_relative 'ruy/context'
-require_relative 'ruy/variable_context'
 require_relative 'ruy/outcome'
 require_relative 'ruy/time_pattern'

data/lib/ruy/conditions.rb

@@ -2,13 +2,15 @@ require_relative 'conditions/all'
 require_relative 'conditions/any'
 require_relative 'conditions/assert'
 require_relative 'conditions/between'
+require_relative 'conditions/in_cyclic_order'
 require_relative 'conditions/cond'
 require_relative 'conditions/day_of_week'
 require_relative 'conditions/eq'
 require_relative 'conditions/except'
+require_relative 'conditions/greater_than'
 require_relative 'conditions/greater_than_or_equal'
+require_relative 'conditions/in'
 require_relative 'conditions/include'
-require_relative 'conditions/included'
 require_relative 'conditions/less_than'
 require_relative 'conditions/less_than_or_equal'
 require_relative 'conditions/tz'

data/lib/ruy/conditions/all.rb

@@ -3,9 +3,9 @@ module Ruy
 
     # Expects that all rules will succeed.
     class All < Ruy::Rule
-      def call(var_ctx)
+      def call(ctx)
         @conditions.all? do |condition|
-          condition.call(var_ctx)
+          condition.call(ctx)
         end
       end
     end

data/lib/ruy/conditions/any.rb

@@ -3,9 +3,9 @@ module Ruy
 
     # Expects that at least one of the rules will succeed.
     class Any < Ruy::Rule
-      def call(var_ctx)
+      def call(ctx)
         @conditions.any? do |condition|
-          condition.call(var_ctx)
+          condition.call(ctx)
         end
       end
 

data/lib/ruy/conditions/assert.rb

@@ -11,8 +11,8 @@ module Ruy
         @attr = attr
       end
 
-      def call(var_ctx)
-        var_ctx.resolve(@attr)
+      def call(ctx)
+        ctx.resolve(@attr)
       end
 
       def ==(o)

data/lib/ruy/conditions/between.rb

@@ -7,21 +7,22 @@ module Ruy
     class Between < Ruy::Rule
       attr_reader :attr, :from, :to
 
-      # @param attr Name of the attribute that will be evaluated
       # @param from Range lower bound
       # @param to Range upper bound
+      # @param attr Name of the attribute that will be evaluated
+      #
       # @yield a block in the context of the current rule
-      def initialize(attr, from, to, &block)
+      def initialize(from, to, attr, &block)
         super
-        @attr = attr
         @from = from
         @to = to
+        @attr = attr
         instance_exec(&block) if block_given?
       end
 
-      def call(var_ctx)
-        value = var_ctx.resolve(@attr)
-        @from <= value && value <= @to && super
+      def call(ctx)
+        value = ctx.resolve(@attr)
+        @from <= value && @to >= value && super
       end
 
       def ==(o)

data/lib/ruy/conditions/cond.rb

@@ -8,14 +8,14 @@ module Ruy
     #
     # Cond is handy for mocking if/else if/else constructs.
     class Cond < Ruy::Rule
-      def call(var_ctx)
+      def call(ctx)
         clauses = @conditions.each_slice(2)
 
         clauses.any? do |rule_1, rule_2|
-          result = rule_1.call(var_ctx)
+          result = rule_1.call(ctx)
 
           if rule_2
-            result && rule_2.call(var_ctx)
+            result && rule_2.call(ctx)
           else
             result
           end

data/lib/ruy/conditions/day_of_week.rb

@@ -4,25 +4,24 @@ require 'tzinfo'
 module Ruy
   module Conditions
 
-    # Expects that a Time object's date corresponds to a specified day of the week
+    # Expects that a Time object's date corresponds to a specified day of the week.
     class DayOfWeek < Ruy::Rule
       DAYS_INTO_WEEK = %w(sunday monday tuesday wednesday thursday friday saturday)
       attr_reader :attr, :value, :tz_identifier
 
-      # @param attr
       # @param value
+      # @param attr
       # @param tz_identifier
-      def initialize(attr, value, tz_identifier = 'UTC')
+      def initialize(value, attr, tz_identifier = 'UTC')
         super
-        @attr = attr
         @value = value
+        @attr = attr
         @tz_identifier = tz_identifier
         @tz = TZInfo::Timezone.get(tz_identifier)
       end
 
-      # @param [Ruy::VariableContext] var_ctx
-      def call(var_ctx)
-        resolved = var_ctx.resolve(@attr)
+      def call(ctx)
+        resolved = ctx.resolve(@attr)
         cmp = @tz.utc_to_local(resolved.to_time.utc)
 
         if @value.is_a?(Fixnum)
@@ -32,7 +31,6 @@ module Ruy
         end
       end
 
-      # @param o
       def ==(o)
         o.kind_of?(DayOfWeek) &&
           attr == o.attr &&

data/lib/ruy/conditions/eq.rb

@@ -2,20 +2,19 @@ module Ruy
   module Conditions
 
     # Expects that a context attribute will be equal to a given value.
-    #
     class Eq < Ruy::Rule
       attr_reader :attr, :value
 
-      # @param attr Context attribute's name
       # @param value Expected value
-      def initialize(attr, value)
+      # @param attr Context attribute's name
+      def initialize(value, attr)
         super
-        @attr = attr
         @value = value
+        @attr = attr
       end
 
-      def call(var_ctx)
-        var_ctx.resolve(@attr) == @value
+      def call(ctx)
+        @value == ctx.resolve(@attr)
       end
 
       def ==(o)

data/lib/ruy/conditions/except.rb

@@ -9,25 +9,25 @@ module Ruy
     class Except < Ruy::Rule
       attr_reader :attr, :value
 
-      # @param attr Context attribute's name
       # @param value Non-expected value
+      # @param attr Context attribute's name
       # @yield a block in the context of the current rule
-      def initialize(attr = nil, value = nil, &block)
+      def initialize(value = nil, attr = nil, &block)
         super
-        @attr = attr
         @value = value
+        @attr = attr
         instance_exec(&block) if block_given?
       end
 
-      def call(var_ctx)
+      def call(ctx)
         result = true
 
         if @attr
-          result &&= var_ctx.resolve(@attr) != @value
+          result &&= ctx.resolve(@attr) != @value
         end
 
         if self.conditions.any?
-          result &&= !super(var_ctx)
+          result &&= !super(ctx)
         end
 
         result

data/lib/ruy/conditions/greater_than.rb

@@ -0,0 +1,30 @@
+module Ruy
+  module Conditions
+
+    # Expects that a context attribute will be greater than the given value.
+    class GreaterThan < Ruy::Rule
+      attr_reader :attr, :value
+
+      # @param value
+      # @param attr Context attribute's name
+      # @yield a block in the context of the current rule
+      def initialize(value, attr, &block)
+        super
+        @value = value
+        @attr = attr
+        instance_exec(&block) if block_given?
+      end
+
+      def call(var_ctx)
+        @value < var_ctx.resolve(@attr) && super
+      end
+
+      def ==(o)
+        o.kind_of?(GreaterThan) &&
+          attr == o.attr &&
+          value == o.value &&
+          self.conditions == o.conditions
+      end
+    end
+  end
+end