montrose 0.10.0 → 0.12.0

data/lib/montrose/clock.rb

@@ -26,7 +26,7 @@ module Montrose
       if @at
         times = @at.map { |hour, min, sec = 0| @time.change(hour: hour, min: min, sec: sec) }
 
-        min_next = times.select { |t| t > @time }.min and return min_next
+        (min_next = times.select { |t| t > @time }.min) && (return min_next)
 
         advance_step(times.min || @time)
       else
@@ -41,7 +41,7 @@ module Montrose
     end
 
     def step
-      @step ||= smallest_step or fail ConfigurationError, "No step for #{@options.inspect}"
+      (@step ||= smallest_step) || fail(ConfigurationError, "No step for #{@options.inspect}")
     end
 
     def smallest_step
@@ -76,9 +76,9 @@ module Montrose
       is_frequency = @every == unit
       if ([unit] + alternates).any? { |u| @options.key?(u) } && !is_frequency
         # smallest unit, increment by 1
-        { step_key(unit) => 1 }
+        {step_key(unit) => 1}
       elsif is_frequency
-        { step_key(unit) => @interval }
+        {step_key(unit) => @interval}
       end
     end
 

data/lib/montrose/frequency.rb

@@ -30,17 +30,17 @@ module Montrose
     #
     def self.from_options(opts)
       frequency = opts.fetch(:every) { fail ConfigurationError, "Please specify the :every option" }
-      class_name = FREQUENCY_TERMS.fetch(frequency.to_s) do
+      class_name = FREQUENCY_TERMS.fetch(frequency.to_s) {
         fail "Don't know how to enumerate every: #{frequency}"
-      end
+      }
 
       Montrose::Frequency.const_get(class_name).new(opts)
     end
 
     # @private
     def self.assert(frequency)
-      FREQUENCY_TERMS.key?(frequency.to_s) or fail ConfigurationError,
-        "Don't know how to enumerate every: #{frequency}"
+      FREQUENCY_TERMS.key?(frequency.to_s) || fail(ConfigurationError,
+        "Don't know how to enumerate every: #{frequency}")
 
       frequency.to_sym
     end

data/lib/montrose/options.rb

@@ -86,6 +86,8 @@ module Montrose
     def_option :starts
     def_option :until
     def_option :between
+    def_option :covering
+    def_option :during
     def_option :hour
     def_option :day
     def_option :mday
@@ -119,12 +121,12 @@ module Montrose
     end
 
     def to_hash
-      hash_pairs = self.class.defined_options.flat_map do |opt_name|
+      hash_pairs = self.class.defined_options.flat_map { |opt_name|
         [opt_name, send(opt_name)]
-      end
+      }
       Hash[*hash_pairs].reject { |_k, v| v.nil? }
     end
-    alias to_h to_hash
+    alias_method :to_h, :to_hash
 
     def []=(option, val)
       send(:"#{option}=", val)
@@ -141,13 +143,13 @@ module Montrose
       self.class.new(h1.merge(h2))
     end
 
-    def fetch(key, *args, &_block)
-      fail ArgumentError, "wrong number of arguments (#{args.length} for 1..2)" if args.length > 1
+    def fetch(key, *args)
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 1..2)" if args.length > 1
 
       found = send(key)
       return found if found
       return args.first if args.length == 1
-      fail "Key #{key.inspect} not found" unless block_given?
+      raise "Key #{key.inspect} not found" unless block
 
       yield
     end
@@ -164,8 +166,8 @@ module Montrose
       @every = parsed.fetch(:every)
     end
 
-    alias frequency every
-    alias frequency= every=
+    alias_method :frequency, :every
+    alias_method :frequency=, :every=
 
     def starts=(time)
       @starts = normalize_time(as_time(time)) || default_starts
@@ -179,6 +181,15 @@ module Montrose
       @hour = map_arg(hours) { |h| assert_hour(h) }
     end
 
+    def during=(during)
+      @during = case during
+                when Range
+                  [decompose_during_arg(during)]
+                else
+                  map_arg(during) { |d| decompose_during_arg(d) }
+      end
+    end
+
     def day=(days)
       @day = nested_map_arg(days) { |d| day_number!(d) }
     end
@@ -200,7 +211,9 @@ module Montrose
     end
 
     def between=(range)
-      @between = range
+      if Montrose.enable_deprecated_between_masking?
+        @covering = range
+      end
       self[:starts] = range.first unless self[:starts]
       self[:until] = range.last unless self[:until]
     end
@@ -302,7 +315,7 @@ module Montrose
           result[:mday] += map_mdays(v)
         end
       else
-        { day: map_days(arg) }
+        {day: map_days(arg)}
       end
     end
 
@@ -313,12 +326,12 @@ module Montrose
       day = day_number(key)
       return [:day, day] if day
 
-      fail ConfigurationError, "Did not recognize #{key} as a month or day"
+      raise ConfigurationError, "Did not recognize #{key} as a month or day"
     end
 
     def assert_range_includes(range, item, absolute = false)
       test = absolute ? item.abs : item
-      fail ConfigurationError, "Out of range: #{range.inspect} does not include #{test}" unless range.include?(test)
+      raise ConfigurationError, "Out of range: #{range.inspect} does not include #{test}" unless range.include?(test)
 
       item
     end
@@ -333,18 +346,18 @@ module Montrose
     def parse_frequency(input)
       if input.respond_to?(:parts)
         frequency, interval = duration_to_frequency_parts(input)
-        { every: frequency.to_s.singularize.to_sym, interval: interval }
+        {every: frequency.to_s.singularize.to_sym, interval: interval}
       elsif input.is_a?(Numeric)
         frequency, interval = numeric_to_frequency_parts(input)
-        { every: frequency, interval: interval }
+        {every: frequency, interval: interval}
       else
-        { every: Frequency.assert(input) }
+        {every: Frequency.assert(input)}
       end
     end
 
     def numeric_to_frequency_parts(number)
       parts = nil
-      [:year, :month, :week, :day, :hour, :minute].each do |freq|
+      %i[year month week day hour minute].each do |freq|
         div, mod = number.divmod(1.send(freq))
         parts = [freq, div]
         return parts if mod.zero?
@@ -355,5 +368,16 @@ module Montrose
     def duration_to_frequency_parts(duration)
       duration.parts.first
     end
+
+    def decompose_during_arg(during)
+      case during
+      when Range
+        [decompose_during_arg(during.first), decompose_during_arg(during.last)]
+      when String
+        during.split(/[-—–]/).map { |d| as_time_parts(d) }
+      else
+        as_time_parts(during)
+      end
+    end
   end
 end

data/lib/montrose/recurrence.rb

@@ -238,7 +238,7 @@ module Montrose
                else
                  fail SerializationError,
                    "Object was supposed to be a #{self}, but was a #{obj.class}. -- #{obj.inspect}"
-               end
+        end
 
         JSON.dump(hash)
       end
@@ -308,7 +308,7 @@ module Montrose
     def to_hash
       default_options.to_hash
     end
-    alias to_h to_hash
+    alias_method :to_h, :to_hash
 
     # Returns json string of options used to create the recurrence
     #
@@ -346,20 +346,41 @@ module Montrose
     def include?(timestamp)
       return false if earlier?(timestamp) || later?(timestamp)
 
-      recurrence = finite? ? self : starts(timestamp)
+      recurrence = finite? ? self : fast_forward(timestamp)
 
       recurrence.events.lazy.each do |event|
         return true if event == timestamp
         return false if event > timestamp
-      end or false
+      end || false
     end
 
-    # Return true/false if recurrence will iterate infinitely
+    def fast_forward(timestamp)
+      return starts(timestamp) unless starts_at.present?
+
+      interval = default_options[:interval]
+      frequency = default_options[:every]
+      duration = interval.send(frequency)
+
+      # Calculate nearest earlier time ahead matching frequency * interval
+      jump = ((timestamp - starts_at) / duration).floor * duration
+
+      starts(starts_at + jump)
+    end
+
+    # Return true/false if recurrence will terminate
     #
-    # @return [Boolean] whether or not recurrence is infinite
+    # @return [Boolean] returns true if recurrence has an end
     #
     def finite?
-      ends_at || length
+      !infinite?
+    end
+
+    # Return true/false if recurrence will iterate infinitely
+    #
+    # @return [Boolean] returns true if recurrence has no end
+    #
+    def infinite?
+      !ends_at && !length
     end
 
     # Return true/false if given timestamp occurs before
@@ -391,7 +412,7 @@ module Montrose
         loop do
           stack.advance(clock.tick) do |time|
             yielder << time
-          end or break
+          end || break
         end
       end
     end

data/lib/montrose/rule.rb

@@ -36,10 +36,11 @@ module Montrose
 end
 
 require "montrose/rule/after"
-require "montrose/rule/between"
+require "montrose/rule/covering"
 require "montrose/rule/day_of_month"
 require "montrose/rule/day_of_week"
 require "montrose/rule/day_of_year"
+require "montrose/rule/during"
 require "montrose/rule/except"
 require "montrose/rule/hour_of_day"
 require "montrose/rule/month_of_year"

data/lib/montrose/rule/between.rb

@@ -22,7 +22,7 @@ module Montrose
       end
 
       def continue?(time)
-        @between.max > time
+        time < @between.max
       end
     end
   end

data/lib/montrose/rule/covering.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Montrose
+  module Rule
+    class Covering
+      include Montrose::Rule
+
+      def self.apply_options(opts)
+        opts[:covering].is_a?(Range) && opts[:covering]
+      end
+
+      # Initializes rule
+      #
+      # @param [Range] covering - timestamp range
+      #
+      def initialize(covering)
+        @covering = case covering.first
+        when Date
+          DateRange.new(covering)
+        else
+          covering
+        end
+      end
+
+      def include?(time)
+        @covering.include?(time)
+      end
+
+      def continue?(time)
+        time < @covering.last
+      end
+
+      class DateRange < SimpleDelegator
+        def include?(time)
+          __getobj__.include?(time.to_date)
+        end
+      end
+    end
+  end
+end

data/lib/montrose/rule/during.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Montrose
+  module Rule
+    class During
+      include Montrose::Rule
+
+      def self.apply_options(opts)
+        opts[:during]
+      end
+
+      # Initializes rule
+      #
+      # @param during [Array<Array<Fixnum>>] array of time parts arrays, e.g. [[9, 0, 0], [17, 0, 0]], i.e., "9 to 5"
+      #
+      def initialize(during)
+        @during = during.map { |first, last| TimeOfDayRange.new(first, last) }
+      end
+
+      def include?(time)
+        @during.any? { |range| range.include?(time) }
+      end
+
+      class TimeOfDay
+        def initialize(hour, min, sec)
+          @hour = hour
+          @min = min
+          @sec = sec
+        end
+
+        def seconds_since_midnight
+          @seconds_since_midnight ||= (@hour * 60 * 60) + (@min * 60) + @sec
+        end
+      end
+
+      class TimeOfDayRange
+        def initialize(first, last, exclude_end: false)
+          @first = TimeOfDay.new(*first)
+          @last = TimeOfDay.new(*last)
+          @exclude_end = exclude_end
+        end
+
+        def include?(time)
+          range.include?(time.seconds_since_midnight.to_i)
+        end
+
+        private
+
+        def range
+          @range ||= Range.new(@first.seconds_since_midnight, @last.seconds_since_midnight, @exclude_end)
+        end
+      end
+    end
+  end
+end

data/lib/montrose/rule/until.rb

@@ -8,7 +8,7 @@ module Montrose
       def self.apply_options(opts)
         return false unless opts[:until]
 
-        { until: opts[:until], exclude_end: opts.fetch(:exclude_end, false) }
+        {until: opts[:until], exclude_end: opts.fetch(:exclude_end, false)}
       end
 
       def initialize(opts)

data/lib/montrose/schedule.rb

@@ -8,27 +8,56 @@ module Montrose
   # @attr_reader [Array] rules the list of recurrences
   #
   class Schedule
+    include Enumerable
+
     attr_accessor :rules
 
-    # Instantiates a schedule and yields the instance to an optional
-    # block for building recurrences inline
-    #
-    # @example Build a schedule with multiple rules added in the given block
-    #   schedule = Montrose::Schedule.build do |s|
-    #     s << { every: :day }
-    #     s << { every: :year }
-    #   end
-    #
-    # @return [Montrose::Schedule]
-    #
-    def self.build
-      schedule = new
-      yield schedule if block_given?
-      schedule
+    class << self
+      # Instantiates a schedule and yields the instance to an optional
+      # block for building recurrences inline
+      #
+      # @example Build a schedule with multiple rules added in the given block
+      #   schedule = Montrose::Schedule.build do |s|
+      #     s << { every: :day }
+      #     s << { every: :year }
+      #   end
+      #
+      # @return [Montrose::Schedule]
+      #
+      def build
+        schedule = new
+        yield schedule if block_given?
+        schedule
+      end
+
+      def dump(obj)
+        return nil if obj.nil?
+        return dump(load(obj)) if obj.is_a?(String)
+
+        array = case obj
+                when Array
+                  new(obj).to_a
+                when self
+                  obj.to_a
+                else
+                  fail SerializationError,
+                    "Object was supposed to be a #{self}, but was a #{obj.class}. -- #{obj.inspect}"
+        end
+
+        JSON.dump(array)
+      end
+
+      def load(json)
+        return nil if json.blank?
+
+        new JSON.parse(json)
+      rescue JSON::ParserError => e
+        fail SerializationError, "Could not parse JSON: #{e}"
+      end
     end
 
-    def initialize
-      @rules = []
+    def initialize(rules = [])
+      @rules = rules.map { |rule| Montrose::Recurrence.new(rule) }
     end
 
     # Add a recurrence rule to the schedule, either by hash or recurrence
@@ -48,7 +77,7 @@ module Montrose
 
       self
     end
-    alias add <<
+    alias_method :add, :<<
 
     # Return true/false if given timestamp is included in any of the rules
     # found in the schedule
@@ -59,6 +88,31 @@ module Montrose
       @rules.any? { |r| r.include?(timestamp) }
     end
 
+    # Iterate over the events of a recurrence. Along with the Enumerable
+    # module, this makes Montrose occurrences enumerable like other Ruby
+    # collections
+    #
+    # @example Iterate over a finite recurrence
+    #   schedule = Montrose::Schedule.build do |s|
+    #     s << { every: :day }
+    #   end
+    #   schedule.each do |event|
+    #     puts event
+    #   end
+    #
+    # @example Iterate over an infinite recurrence
+    #   schedule = Montrose::Schedule.build do |s|
+    #     s << { every: :day }
+    #   end
+    #   schedule.lazy.each do |event|
+    #     puts event
+    #   end
+    #
+    # @return [Enumerator] an enumerator of recurrence timestamps
+    def each(&block)
+      events.each(&block)
+    end
+
     # Returns an enumerator for iterating over timestamps in the schedule
     #
     # @example Return the events
@@ -73,21 +127,55 @@ module Montrose
       enums = @rules.map { |r| r.merge(opts).events }
       Enumerator.new do |y|
         loop do
-          enum = active_enums(enums).min_by(&:peek) or break
+          (enum = active_enums(enums).min_by(&:peek)) || break
           y << enum.next
         end
       end
     end
 
+    # Returns an array of the options used to create the recurrence
+    #
+    # @return [Array] array of hashes of recurrence options
+    #
+    def to_a
+      @rules.map(&:to_hash)
+    end
+
+    # Returns json string of options used to create the schedule
+    #
+    # @return [String] json of schedule recurrences
+    #
+    def to_json(*args)
+      JSON.dump(to_a, *args)
+    end
+
+    # Returns json array of options used to create the schedule
+    #
+    # @return [Array] json of schedule recurrence options
+    #
+    def as_json(*args)
+      to_a.as_json(*args)
+    end
+
+    # Returns options used to create the schedule recurrences in YAML format
+    #
+    # @return [String] YAML-formatted schedule recurrence options
+    #
+    def to_yaml(*args)
+      YAML.dump(JSON.parse(to_json(*args)))
+    end
+
+    def inspect
+      "#<#{self.class}:#{object_id.to_s(16)} #{to_a.inspect}>"
+    end
+
     private
 
     def active_enums(enums)
       enums.select do |e|
-        begin
-          e.peek
-        rescue StopIteration
-          false
-        end
+        e.peek
+      rescue StopIteration
+        false
       end
     end
   end