ruy 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 062667c3bb0ac6a9796f8bbda6dded7918ec9b11
-  data.tar.gz: bd51df8ff61cab98c007849cf4a1079dc8f83956
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NGJkMjk0NDkxN2RlYzQ1Mjc2NDI3YjU4YmFjM2Q4NDVjMTdjN2Y0ZA==
+  data.tar.gz: !binary |-
+    NzM1MTVhYWFiZWU4Mzk1ZjBhODM5N2FiNGY2ZjczMzQyYTMxMTcxMg==
 SHA512:
-  metadata.gz: e48d547cdb0e47a50ede40c794d3a90eb012ab27c34e31aba0d696ae3936bcbdd0a0501887ba269833135b61e70b34d684892ff84e1e698918f54c9d9c9c7a2e
-  data.tar.gz: 78a9ecccf5c5f9f0549f7c53fa2e3515d7d900afe4695c1b52f7e5b2a019c38158e385e2daa088a7c716a396d7c31c6e3b06f70185b9d9a42b0dc756450f921a
+  metadata.gz: !binary |-
+    YmU4YjRiNDAyNGZmYmEwOWYxNDMwMDA2MjI3YjU2OTczNmNjM2E2Y2E4Yjg1
+    NmEwODFkZTc1MWU2MzM1YzQ1ZGI5OTFkNzcyOGM2YWRjODQ0NTZiMzlkZjU0
+    MTg3OGZmZTQ0OTI1MTk1MzNhMWQwYmI3ZTY1NDgyNDdmOTRjOGU=
+  data.tar.gz: !binary |-
+    MmVjZmU2MGQ1MmJlMzY3MzZlNDIwY2M0YWMxZTMwYjU4YWU4YTNiYzdlMDZj
+    NWFhMjk5NjBiMWFlNDQ1NjQwZDEwNzY5NWNkNjg2YWQ5OWYxOTEyMGQ2YTgx
+    ZTI2ODE0NWRlNTVlNWU4MjZjODJmNzU5ZjJiYzBjYzI2ODU1YWY=

data/README.md

@@ -68,25 +68,28 @@ 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 *Expects that a value is included in a cyclic order*
- - 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*
+ - `all` *All of the nested conditions must suffice*
+ - `any` *At least one of its nested conditions must suffice*
+ - `assert` *Tests that a given context value must be a truthy value*
+ - `between` *Evaluates that a given 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*
+ - `dig` *Digs into a Hash allowing to define conditions over nested attributes*
+ - `eq` *Tests a context value for equality*
+ - `every` *Evaluates that at all the elements of a context enumerable matches the nested conditions*
+ - `except` *Evaluates that any of the nested conditions does not suffice*
+ - `greater_than` *Tests that a given context value is greater than something*
+ - `greater_than_or_equal` *Tests that a given context value is greater than or equal to something*
+ - `in` *Given context value must belong to a specified list of values*
+ - `in_cyclic_order` *Expects that a given context value is included in a cyclic order*
+ - `include` *The context value must include a specified value*
+ - `less_than_or_equal` *Tests that a given context value is less than or equal to something*
+ - `less_than` *Tests that a given context value is less than something*
+ - `some` *Evaluates that at least one element of a context enumerable matches the nested conditions*
 
 ### Rules
 
-A Rule is a set of conditions that must suffice and returns a value resulting from either an
+A Rule is a set of conditions that must suffice, and return a value resulting from either an
 outcome or a fallback.
 
 ### Contexts
@@ -95,7 +98,8 @@ A context is a `Hash` from which values are fetched in order to evaluate a Rule.
 
 ### Lazy values
 
-Rules 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.
+Rules 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
@@ -104,7 +108,7 @@ gifter = Ruy::Rule.new
 
 gifter.let :amounts_average # an expensive calculation
 
-gifter.eq :friday, :week_of_day
+gifter.eq :friday, :day_of_week
 
 gifter.greater_than_or_equal 10_000, :amounts_average
 
@@ -121,7 +125,7 @@ conditions, in such case, if the conditions meet, the outcome value is returned.
 
 A Rule can have multiple outcomes, the first matching one is returned.
 
-### Time Zone awareness
+## 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.
 
@@ -141,9 +145,9 @@ String time patterns follow the Ruy's well-formed time pattern structure as foll
 
 `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.
+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 pattern specify it, UTC will be used.
 
-#### Days of week matcher
+### 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.
 
@@ -167,7 +171,7 @@ This matcher supports both the `Symbol` and number syntax in the range `(0..6)`
 
 The day of week matcher will try to parse timestamps using the ISO8601 format unless the context passes a Time object.
 
-#### Nested blocks support
+### 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`.
 
@@ -184,10 +188,19 @@ end
 rule.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.
+The following won't do what you expect. Instead, equality will be evaluated interpreting the time as a simple string.
+
+```ruby
+rule.tz 'America/New_York' do
+  any do
+    eq '2015-01-01T00:00:00', :timestamp
+    eq '2015-01-01T02:00:00zUTC', :timestamp
+  end
+end
+```
 
 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.
 
-### Documentation
+## Documentation
 
 [RubyDoc.info](http://www.rubydoc.info/github/moove-it/ruy)

data/lib/ruy/conditions.rb

@@ -7,7 +7,9 @@ require_relative 'conditions/between'
 require_relative 'conditions/in_cyclic_order'
 require_relative 'conditions/cond'
 require_relative 'conditions/day_of_week'
+require_relative 'conditions/dig'
 require_relative 'conditions/eq'
+require_relative 'conditions/every'
 require_relative 'conditions/except'
 require_relative 'conditions/greater_than'
 require_relative 'conditions/greater_than_or_equal'
@@ -15,4 +17,5 @@ require_relative 'conditions/in'
 require_relative 'conditions/include'
 require_relative 'conditions/less_than'
 require_relative 'conditions/less_than_or_equal'
+require_relative 'conditions/some'
 require_relative 'conditions/tz'

data/lib/ruy/conditions/all.rb

@@ -1,7 +1,8 @@
 module Ruy
   module Conditions
 
-    # Expects that all rules will succeed.
+    # Expects all sub-conditions to be satisfied
+    #
     class All < CompoundCondition
     end
   end

data/lib/ruy/conditions/any.rb

@@ -1,18 +1,19 @@
 module Ruy
   module Conditions
 
-    # Expects that at least one of the rules will succeed.
+    # Expects that at least one of the sub-conditions is satisfied
+    #
     class Any < CompoundCondition
-      def call(ctx)
+
+      protected
+
+      # @see CompoundCondition#evaluate
+      def evaluate(ctx)
         conditions.any? do |condition|
           condition.call(ctx)
         end
       end
 
-      def ==(o)
-        o.kind_of?(Any) &&
-          conditions == o.conditions
-      end
     end
   end
 end

data/lib/ruy/conditions/assert.rb

@@ -1,24 +1,29 @@
 module Ruy
   module Conditions
 
-    # Asserts that an attribute has a truth value.
+    # Expects that the context key stores a truthy value
+    #
     class Assert < Condition
-      attr_reader :attr
-
-      # @param attr Context attribute's name
-      def initialize(attr)
+      # @param key
+      # @example evaluate that :key passes
+      #   Assert.new(:key)
+      def initialize(*key)
         super
-        @attr = attr
-      end
-
-      def call(ctx)
-        ctx.resolve(@attr)
+        @key = key.first if key.any?
       end
 
       def ==(o)
         o.kind_of?(Assert) &&
-          @attr == o.attr
+          o.key == @key
       end
+
+      protected
+
+      # @see Condition#evaluate
+      def evaluate(obj)
+        !!obj
+      end
+
     end
   end
 end

data/lib/ruy/conditions/between.rb

@@ -1,34 +1,48 @@
 module Ruy
   module Conditions
 
-    # Expects that a context value belongs to a given range.
+    # Expects that a context key stores a value included in a defined range
     #
-    # Comparison formula: from <= context[attr] <= to
     class Between < Condition
-      attr_reader :attr, :from, :to
+      attr_reader :from, :to, :range
 
-      # @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(from, to, attr, &block)
+      # @overload initialize(from, to, key)
+      #   @param from Range lower bound
+      #   @param to Range upper bound
+      #   @param key Key that holds the value to be evaluated
+      # @overload initialize(range, key)
+      #   @param range Range
+      #   @param key Key that holds the value to be evaluated
+      def initialize(*args)
         super
-        @from = from
-        @to = to
-        @attr = attr
-      end
 
-      def call(ctx)
-        value = ctx.resolve(@attr)
-        @from <= value && @to >= value
+        if Range === args[0]
+          @range = args[0]
+          @key = args[1] if args.length > 1
+        else
+          @from, @to = args[0], args[1]
+          @key = args[2] if args.length > 2
+        end
       end
 
       def ==(o)
         o.kind_of?(Between) &&
-          @attr == o.attr &&
-          @from == o.from &&
-          @to   == o.to
+          o.from == @from &&
+          o.to == @to &&
+          o.range == @range &&
+          o.key == @key
+      end
+
+      protected
+
+      # @see Condition#evaluate
+      # @raise NoMethodError when values that do not support #<=> are passed
+      def evaluate(value)
+        if @range
+          @range.include?(value)
+        else
+          @from <= value && @to >= value
+        end
       end
     end
   end

data/lib/ruy/conditions/compound_condition.rb

@@ -1,25 +1,45 @@
 module Ruy
   module Conditions
 
+    # Abstract base class for compound conditions
+    #
+    # @abstract
     class CompoundCondition < Condition
-
       attr_reader :conditions
 
       def initialize(*params)
         super
-
         @conditions = []
       end
 
-      # Evaluates all conditions.
+      def ==(o)
+        o.kind_of?(self.class) &&
+          o.conditions == @conditions
+      end
+
+      protected
+
+      # Evaluates a context to check if it satisfies the set of sub-conditions
       #
-      # @return [true] When all conditions succeeds
-      # @return [false] Otherwise
-      def call(ctx)
+      # @abstract
+      # @param ctx [Context]
+      # @return [Boolean] true if satisfies the sub-conditions, false otherwise
+      def evaluate(ctx)
         @conditions.all? do |condition|
           condition.call(ctx)
         end
       end
+
+      # Lookups the object of evaluation in the context
+      # based on the initialization attribute
+      #
+      # @param ctx [Context]
+      # @return an object if a key has been defined,
+      #   the passed context otherwise
+      def resolve(ctx)
+        has_key? ? ctx.resolve(key) : ctx
+      end
+
     end
   end
 end

data/lib/ruy/conditions/cond.rb

@@ -1,14 +1,17 @@
 module Ruy
   module Conditions
 
-    # Expects a successful evaluation of a sub-pair of conditions.
+    # Evaluates any given number of sub-conditions in subsequent pairs
+    # until one pair evaluates succesfully.
+    # If an uneven number of conditions is given, it will evaluate in pairs
+    # except for the last condition which will be evaluated alone.
     #
-    # Groups rules in slices of 2 conditions. Then evalutes each slice until one of them succeds.
-    # If there's an even number of conditions, the last slice will have only one condition.
-    #
-    # Cond is handy for mocking if/else if/else constructs.
     class Cond < CompoundCondition
-      def call(ctx)
+
+      protected
+
+      # @see CompoundCondition#evaluate
+      def evaluate(ctx)
         clauses = conditions.each_slice(2)
 
         clauses.any? do |rule_1, rule_2|
@@ -21,6 +24,8 @@ module Ruy
           end
         end
       end
+
     end
+
   end
 end

data/lib/ruy/conditions/condition.rb

@@ -1,6 +1,9 @@
 module Ruy
   module Conditions
 
+    # Abstract base class for simple conditions
+    #
+    # @abstract
     class Condition
       include Ruy::DSL
 
@@ -10,6 +13,41 @@ module Ruy
         @params = params
       end
 
+      # Evaluates a context's object for its compliance with the condition.
+      #
+      # @param ctx [Context]
+      # @return [Boolean]
+      def call(ctx)
+        evaluate(resolve(ctx))
+      end
+
+      protected
+
+      attr_reader :key
+
+      # Returns true if a key has been defined among the condition attributes
+      #
+      # @return [Boolean]
+      def has_key?
+        defined? @key
+      end
+
+      # Evaluates an object to check if it satisfies the condition
+      #
+      # @abstract
+      # @param obj
+      # @return [Boolean] true if it satisfies the condition, false otherwise
+      def evaluate(obj); end
+
+      # Lookups the object of evaluation in the context
+      # based on the initialization attribute
+      #
+      # @param ctx [Context]
+      # @return an object stored in the context
+      def resolve(ctx)
+        has_key? ? ctx.resolve(key) : ctx.object
+      end
+
     end
   end
 end

data/lib/ruy/conditions/day_of_week.rb

@@ -4,39 +4,49 @@ 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 < Condition
       DAYS_INTO_WEEK = %w(sunday monday tuesday wednesday thursday friday saturday)
-      attr_reader :attr, :value, :tz_identifier
 
-      # @param value
-      # @param attr
+      attr_reader :day, :tz_identifier
+
+      # @param day
+      # @param key
       # @param tz_identifier
-      def initialize(value, attr, tz_identifier = 'UTC')
+      # @example to check that the day in 'time' is wednesday
+      #   DayOfWeek.new(:wednesday, :time)
+      # @example to check that the day in 'time' is wednesday in CST
+      #   DayOfWeek.new(:wednesday, :time, 'CST')
+      def initialize(day, key, tz_identifier = 'UTC')
         super
-        @value = value
-        @attr = attr
+        @day = day
+        @key = key
         @tz_identifier = tz_identifier
-        @tz = TZInfo::Timezone.get(tz_identifier)
       end
 
-      def call(ctx)
-        resolved = ctx.resolve(@attr)
-        cmp = @tz.utc_to_local(resolved.to_time.utc)
+      def ==(o)
+        o.kind_of?(DayOfWeek) &&
+          o.day == @day &&
+          o.key == @key &&
+          o.tz_identifier == @tz_identifier
+      end
+
+      protected
 
-        if @value.is_a?(Fixnum)
-          cmp.wday == @value
+      # @see Condition#evaluate
+      def evaluate(date)
+        # Get the TZInfo::Timezone object here so it can be garbage-collected later
+        cmp = TZInfo::Timezone.get(@tz_identifier).utc_to_local(date.to_time.utc)
+
+        if @day.is_a?(Fixnum)
+          cmp.wday == @day
         else
-          DAYS_INTO_WEEK.include?(@value.to_s) && cmp.send("#{@value}?")
+          DAYS_INTO_WEEK.include?(@day.to_s) && cmp.send("#{@day}?")
         end
       end
 
-      def ==(o)
-        o.kind_of?(DayOfWeek) &&
-          attr == o.attr &&
-          value == o.value &&
-          tz_identifier == o.tz_identifier
-      end
     end
   end
 end