montrose 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6375eeb97c6ac8c0ea36b6be0b5281b4ffeceb5fa6fa591f4aab7c801240fcc
-  data.tar.gz: 903145e001fb0ddd6a4dff5f7cf9a9e0583e9d2242a1b00283e1a3de3d5a03ce
+  metadata.gz: 01fee4660a2a1e95d60de269d491675460289ae52f6c582aee5ea6be39a883cc
+  data.tar.gz: ece2fbd3f36909337abd6712025053385f6ceedf95695a7852b6e05b6c804906
 SHA512:
-  metadata.gz: 9598d8bc00e29c9adbf8b1d9323dcd02a2dc7aa54ae6d6a25ccc61ab5ffdc9dc1f0c8a390732bf6a1a8181b287fbee5a11c2c4b399b6cc81871276c374391baf
-  data.tar.gz: 74813535d8ec8248ee87e0ce2aa500a3e85722a0ad06b310b8de62d50fadc1819cd914046b04c4a0bd9fc6e76217de62510fa9a7af60ebe63d80c2b7e9fdd63b
+  metadata.gz: bb823d11097cd9228ec7631809bece2b1028adf728c7a4919284dfc7a6fcafa3d65c9d1ed446f60f1a16335143830ae36b4725c6d980b5cb6a152b80961f4e0b
+  data.tar.gz: deb0db72983faf47192095aef16e7512f928c4ff4f1f6fd20f913394850b354fc2e004dcda70455d08abe4471a2647d8b3a31832814f737cf68a09d6d9ffbaa8

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+### 0.11.0 - (2019-08-16)
+
+* enhancements
+  * Adds `Recurrence#during` to support recurrences within time-of-day ranges,
+    e.g. `Montrose.every(20.minutes).during("9am-5pm")`
+
+### 0.10.1 - (2019-07-22)
+
+* enhancements
+  * Adds `Schedule.dump` and `Schedule.load` to support ActiveRecord column
+    serialization
+
 ### 0.10.0 - (2019-07-17)
 
 * enhancements
@@ -61,7 +73,7 @@
   * Previously, the :between option served as a shorthand for :starts to :until.
     Now, when both :starts and :between are provided, the recurrence will behave
 as if anchored by the given :starts option, but filtered through the given
-:betweeen option.
+:between option.
   * The :exclude_end option changes the default behavior of :until--when the
     timestamp of the interval matches the :until timestamp, it will be included
 by default unless the :exclude_end option is set to true.

data/README.md

@@ -277,6 +277,15 @@ Montrose.every(90.minutes, total: 4)
 # every 20 minutes from 9:00 AM to 4:40 PM every day
 Montrose.every(20.minutes, hour: 9..16)
 
+# every 20 minutes from 9:00 AM to 4:40 PM every day with time-of-day precision
+r = Montrose.every(20.minutes)
+r.during("9am-4:40pm")                                        # as semantic time-of-day range OR
+r.during(time.change(hour: 9)..time.change(hour: 4: min: 40)) # as ruby time range OR
+r.during([9, 0, 0], [16, 40, 0])                              # as hour, min, sec tuple pairs for start, end
+
+# every 20 minutes during multiple time-of-day ranges
+Montrose.every(20.minutes).during("9am-12pm", "1pm-5pm")
+
 # Minutely
 Montrose.minutely
 Montrose.r(every: :minute)
@@ -366,6 +375,40 @@ r.events.take(10).each { |date| puts date.to_s }
 r.events.lazy.select { |time| time > 1.month.from_now }.take(3).each { |date| puts date.to_s }
 ```
 
+### Combining recurrences
+
+It may be necessary to combine several recurrence rules into a single
+enumeration of events. For this purpose, there is `Montrose::Schedule`. To create a schedule of multiple recurrences:
+
+```ruby
+recurrence_1 = Montrose.monthly(day: { friday: [1] })
+recurrence_2 = Montrose.weekly(on: :tuesday)
+
+schedule = Montrose::Schedule.build do |s|
+  s << recurrence_1
+  s << recurrence_2
+end
+
+# add after building
+s << Montrose.yearly
+```
+The `Schedule#<<` method also accepts valid recurrence options as hashes:
+```ruby
+schedule = Montrose::Schedule.build do |s|
+  s << { day: { friday: [1] } }
+  s << { on: :tuesday }
+end
+```
+A schedule acts like a collection of recurrence rules that also behaves as a single
+stream of events:
+
+```ruby
+schedule.events # => #<Enumerator: ...>
+schedule.each do |event|
+  puts event
+end
+```
+
 ### Ruby on Rails
 
 Instances of `Montrose::Recurrence` support the ActiveRecord serialization API so recurrence objects can be marshalled to and from a single database column:
@@ -374,6 +417,13 @@ Instances of `Montrose::Recurrence` support the ActiveRecord serialization API s
 class RecurringEvent < ApplicationRecord
   serialize :recurrence, Montrose::Recurrence
 
+end
+```
+`Montrose::Schedule` can also be serialized:
+```ruby
+class RecurringEvent < ApplicationRecord
+  serialize :recurrence, Montrose::Schedule
+
 end
 ```
 

data/lib/montrose/chainable.rb

@@ -168,6 +168,23 @@ module Montrose
       merge(between: date_range)
     end
 
+    # Create a recurrence occurring within a time-of-day range or ranges.
+    # Given time ranges will parse as times-of-day and ignore given dates.
+    #
+    # @param [Range<Time>,String,Array<Array>] time-of-day range(s)
+    #
+    # @example
+    #   Montrose.every(20.minutes).during("9am-5pm")
+    #   Montrose.every(20.minutes).during(time.change(hour: 9)..time.change(hour: 5))
+    #   Montrose.every(20.minutes).during([9, 0, 0], [17, 0, 0])
+    #   Montrose.every(20.minutes).during("9am-12pm", "1pm-5pm")
+    #
+    # @return [Montrose::Recurrence]
+    #
+    def during(time_of_day, *extras)
+      merge(during: time_of_day.array_concat(extras))
+    end
+
     # Create a recurrence through :on option
     #
     # @param day [Hash,Symbol] weekday or day of month as hash, e.g. { friday: 13 }

data/lib/montrose/options.rb

@@ -86,6 +86,7 @@ module Montrose
     def_option :starts
     def_option :until
     def_option :between
+    def_option :during
     def_option :hour
     def_option :day
     def_option :mday
@@ -179,6 +180,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
@@ -355,5 +365,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(%r{[-—–]}).map { |d| as_time_parts(d) }
+      else
+        as_time_parts(during)
+      end
+    end
   end
 end

data/lib/montrose/rule.rb

@@ -40,6 +40,7 @@ require "montrose/rule/between"
 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/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/schedule.rb

@@ -8,6 +8,8 @@ module Montrose
   # @attr_reader [Array] rules the list of recurrences
   #
   class Schedule
+    include Enumerable
+
     attr_accessor :rules
 
     class << self
@@ -86,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
@@ -106,10 +133,42 @@ module Montrose
       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)

data/lib/montrose/stack.rb

@@ -14,6 +14,7 @@ module Montrose
         Rule::After,
         Rule::Until,
         Rule::Between,
+        Rule::During,
         Rule::Except,
         Rule::Total,
         Rule::TimeOfDay,

data/lib/montrose/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Montrose
-  VERSION = "0.10.1"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: montrose
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Ross Kaffenberger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-22 00:00:00.000000000 Z
+date: 2019-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -169,6 +169,7 @@ files:
 - lib/montrose/rule/day_of_month.rb
 - lib/montrose/rule/day_of_week.rb
 - lib/montrose/rule/day_of_year.rb
+- lib/montrose/rule/during.rb
 - lib/montrose/rule/except.rb
 - lib/montrose/rule/hour_of_day.rb
 - lib/montrose/rule/month_of_year.rb
@@ -203,7 +204,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubyforge_project: 
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Recurring events in Ruby