montrose 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2624845de532b2888ed205eeb7e92be0e44475c2
-  data.tar.gz: 0be802540d67f55b0b930a57202ee44683718bf1
+  metadata.gz: e2af0b4abedbea2421c73f457fcdbd66390870f1
+  data.tar.gz: dafba1cbbd0f14757bc95ffe81764a065947e2fa
 SHA512:
-  metadata.gz: ac9b40468a9a9f00775f6d2041e1e98d6df31df6512a66f6870f43776f7dbbebc1f17c3901bcdfbae3dafd30761131601cbe42d9d709a042ac22db52dd57612f
-  data.tar.gz: 6c49f3532b8a7b49654fa2a7f4ca217394d9e03d3b315ce015f23ff7652d28f180172103b3e75dd079bb47ba064946811ee8b0c9d086b5411a0a7b7c85bd5049
+  metadata.gz: f3c9e25c8f3e30cf8df3037e653f3c515ea25c3bf9d144da520a4e4a5e043a8a51c8b8eefe449d4c83ac0b87ab47d5a0c0e14a58e875846a1d9995a9472501c0
+  data.tar.gz: fb805c48e5e6d9880e6c3c091ea738bf2b6f4e21a59afa78cf3c467ad062cdf12f5802f46078138fbde9e74030f6d3893a83fee5877fc527b1c66da38c609312

data/.rubocop.yml

@@ -112,3 +112,9 @@ Style/RegexpLiteral:
 
 Style/DotPosition:
   EnforcedStyle: trailing
+
+Style/VariableNumber:
+  Enabled: false
+
+Style/FormatString:
+  Enabled: false

data/.travis.yml

@@ -12,6 +12,6 @@ matrix:
   fast_finish: true
 rvm:
   - 2.1.10
-  - 2.2.5
-  - 2.3.1
+  - 2.2.6
+  - 2.3.3
 sudo: false

data/CHANGELOG.md

@@ -1,4 +1,10 @@
-### 0.4.3 - (2016-07-27)
+### 0.5.0 - (2016-11-23)
+
+* enhancements
+  * Adds `Recurrence#include?`
+  * Improved documentation
+
+### 0.4.3 - (2016-11-20)
 
 * enhancements
   * Add CI support for ActiveSupport 4.1, 4.2, 5.0 (by @phlipper)

data/README.md

@@ -351,9 +351,6 @@ Montrose.yearly(yday: [1, 100]) # yearly on the 1st and 100th day of year
 Montrose.yearly(on: { january: 31 })
 Montrose.r(every: :year, on: { 10 => 31 }, interval: 3)
 
-Montrose.daily(:day, except: "2017-01-31")
-Montrose.daily(except: [Date.today, "2017-01-31"])
-
 # Chaining
 Montrose.weekly.starting(3.weeks.from_now).on(:friday)
 Montrose.every(:day).at("4:05pm")

data/Rakefile

@@ -20,6 +20,7 @@ task default: [:spec, :rubocop]
 namespace :doc do
   desc "Generate docs and publish to gh-pages"
   task :publish do
+    puts "Generating docs"
     require "fileutils"
     sh "yard doc"
     sh "git checkout gh-pages"

data/lib/montrose/recurrence.rb

@@ -5,11 +5,216 @@ require "montrose/stack"
 require "montrose/clock"
 
 module Montrose
+  # Represents the rules for a set of recurring events. Can be instantiated
+  # and extended in a variety of ways as show in the examples below.
+  #
+  # @author Ross Kaffenberger
+  # @since 0.0.1
+  # @attr_reader [Montrose::Options] default_options contains the recurrence rules in hash-like format
+  #
+  # @example a new recurrence
+  #   Montrose.r
+  #   Montrose.recurrence
+  #   Montrose::Recurrence.new
+  #
+  # @example daily for 10 occurrences
+  #   Montrose.daily(total: 10)
+  #
+  # @example daily until December 23, 2015
+  #   starts = Date.new(2015, 1, 1)
+  #   ends = Date.new(2015, 12, 23)
+  #   Montrose.daily(starts: starts, until: ends)
+  #
+  # @example every other day forever
+  #   Montrose.daily(interval: 2)
+  #
+  # @example every 10 days 5 occurrences
+  #   Montrose.every(10.days, total: 5)
+  #
+  # @example everyday in January for 3 years
+  #   starts = Time.current.beginning_of_year
+  #   ends = Time.current.end_of_year + 2.years
+  #   Montrose.daily(month: :january, between: starts...ends)
+  #
+  # @example weekly for 10 occurrences
+  #   Montrose.weekly(total: 10)
+  #
+  # @example weekly until December 23, 2015
+  #   ends_on = Date.new(2015, 12, 23)
+  #   starts_on = ends_on - 15.weeks
+  #   Montrose.every(:week, until: ends_on, starts: starts_on)
+  #
+  # @example every other week forever
+  #   Montrose.every(2.weeks)
+  #
+  # @example weekly on Tuesday and Thursday for five weeks from September 1, 2015 until October 5, 2015
+  #   Montrose.weekly(on: [:tuesday, :thursday],
+  #     between: Date.new(2015, 9, 1)..Date.new(2015, 10, 5))
+  #
+  # @example every other week on Mon, Wed and Fri until December 23 2015, but starting on Tuesday, September 1, 2015
+  #   Montrose.every(2.weeks,
+  #     on: [:monday, :wednesday, :friday],
+  #     starts: Date.new(2015, 9, 1))
+  #
+  # @example every other week on Tuesday and Thursday, for 8 occurrences
+  #   Montrose.weekly(on: [:tuesday, :thursday], total: 8, interval: 2)
+  #
+  # @example monthly on the first Friday for ten occurrences
+  #   Montrose.monthly(day: { friday: [1] }, total: 10)
+  #
+  # @example monthly on the first Friday until December 23, 2015
+  #   Montrose.every(:month, day: { friday: [1] }, until: Date.new(2016, 12, 23))
+  #
+  # @example every other month on the first and last Sunday of the month for 10 occurrences
+  #   Montrose.every(:month, day: { sunday: [1, -1] }, interval: 2, total: 10)
+  #
+  # @example monthly on the second-to-last Monday of the month for 6 months
+  #   Montrose.every(:month, day: { monday: [-2] }, total: 6)
+  #
+  # @example monthly on the third-to-the-last day of the month, forever
+  #   Montrose.every(:month, mday: [-3])
+  #
+  # @example monthly on the 2nd and 15th of the month for 10 occurrences
+  #   Montrose.every(:month, mday: [2, 15], total: 10)
+  #
+  # @example monthly on the first and last day of the month for 10 occurrences
+  #   Montrose.monthly(mday: [1, -1], total: 10)
+  #
+  # @example every 18 months on the 10th thru 15th of the month for 10 occurrences
+  #   Montrose.every(18.months, total: 10, mday: 10..15)
+  #
+  # @example every Tuesday, every other month
+  #   Montrose.every(2.months, on: :tuesday)
+  #
+  # @example yearly in June and July for 10 occurrences
+  #   Montrose.yearly(month: [:june, :july], total: 10)
+  #
+  # @example every other year on January, February, and March for 10 occurrences
+  #   Montrose.every(2.years, month: [:january, :february, :march], total: 10)
+  #
+  # @example every third year on the 1st, 100th and 200th day for 10 occurrences
+  #   Montrose.yearly(yday: [1, 100, 200], total: 10)
+  #
+  # @example every 20th Monday of the year, forever
+  #   Montrose.yearly(day: { monday: [20] })
+  #
+  # @example Monday of week number 20 forever
+  #   Montrose.yearly(week: [20], on: :monday)
+  #
+  # @example every Thursday in March, forever
+  #   Montrose.monthly(month: :march, on: :thursday, at: "12 pm")
+  #
+  # @example every Thursday, but only during June, July, and August, forever" do
+  #   Montrose.monthly(month: 6..8, on: :thursday)
+  #
+  # @example every Friday 13th, forever
+  #   Montrose.monthly(on: { friday: 13 })
+  #
+  # @example first Saturday that follows the first Sunday of the month, forever
+  #   Montrose.monthly(on: { saturday: 7..13 })
+  #
+  # @example every four years, the first Tuesday after a Monday in November, forever (U.S. Presidential Election day)
+  #   Montrose.every(4.years, month: :november, on: { tuesday: 2..8 })
+  #
+  # @example every 3 hours from 9:00 AM to 5:00 PM on a specific day
+  #   date = Date.new(2016, 9, 1)
+  #   Montrose.hourly(between: date..(date+1), hour: 9..17, interval: 3)
+  #
+  # @example every 15 minutes for 6 occurrences
+  #   Montrose.every(90.minutes, total: 6)
+  #
+  # @example every hour and a half for four occurrences
+  #   Montrose.every(90.minutes, total: 4)
+  #
+  # @example every 20 minutes from 9:00 AM to 4:40 PM every day
+  #   Montrose.every(20.minutes, hour: 9..16)
+  #
+  # @example Minutely
+  #   Montrose.minutely
+  #   Montrose.r(every: :minute)
+  #   Montrose.every(10.minutes)
+  #   Montrose.r(every: 10.minutes)
+  #   Montrose.r(every: :minute, interval: 10) # every 10 minutes
+  #   Montrose.minutely(until: "9:00 PM")
+  #   Montrose.r(every: :minute, until: "9:00 PM")
+  #
+  # @example Daily
+  #   Montrose.daily
+  #   Montrose.every(:day)
+  #   Montrose.r(every: :day)
+  #   Montrose.every(9.days)
+  #   Montrose.r(every: 9.days)
+  #   Montrose.r(every: :day, interval: 9)
+  #   Montrose.daily(at: "9:00 AM")
+  #   Montrose.every(:day, at: "9:00 AM")
+  #   Montrose.r(every: :day, at: "9:00 AM")
+  #   Montrose.daily(total: 7)
+  #   Montrose.every(:day, total: 7)
+  #   Montrose.r(every: :day, total: 7)
+  #
+  # @example Weekly
+  #   Montrose.weekly
+  #   Montrose.every(:week)
+  #   Montrose.r(every: :week)
+  #   Montrose.every(:week, on: :monday)
+  #   Montrose.every(:week, on: [:monday, :wednesday, :friday])
+  #   Montrose.every(2.weeks, on: :friday)
+  #   Montrose.every(:week, on: :friday, at: "3:41 PM")
+  #   Montrose.weekly(on: :thursday)
+  #
+  # @example Monthly by month day
+  #   Montrose.monthly(mday: 1) # first of the month
+  #   Montrose.every(:month, mday: 1)
+  #   Montrose.r(every: :month, mday: 1)
+  #   Montrose.monthly(mday: [2, 15]) # 2nd and 15th of the month
+  #   Montrose.monthly(mday: -3) # third-to-last day of the month
+  #   Montrose.monthly(mday: 10..15) # 10th through the 15th day of the month
+  #
+  # @example Monthly by week day
+  #   Montrose.monthly(day: :friday, interval: 2) # every Friday every other month
+  #   Montrose.every(:month, day: :friday, interval: 2)
+  #   Montrose.r(every: :month, day: :friday, interval: 2)
+  #   Montrose.monthly(day: { friday: [1] }) # 1st Friday of the month
+  #   Montrose.monthly(day: { Sunday: [1, -1] }) # first and last Sunday of the month
+  #   Montrose.monthly(mday: 7..13, day: :saturday) # first Saturday that follow the first Sunday of the month
+  #
+  # @example Yearly
+  #   Montrose.yearly
+  #   Montrose.every(:year)
+  #   Montrose.r(every: :year)
+  #   Montrose.yearly(month: [:june, :july]) # yearly in June and July
+  #   Montrose.yearly(month: 6..8, day: :thursday) # yearly in June, July, August on Thursday
+  #   Montrose.yearly(yday: [1, 100]) # yearly on the 1st and 100th day of year
+  #   Montrose.yearly(on: { january: 31 })
+  #   Montrose.r(every: :year, on: { 10 => 31 }, interval: 3)
+  #
+  # @example Chaining
+  #   Montrose.weekly.starting(3.weeks.from_now).on(:friday)
+  #   Montrose.every(:day).at("4:05pm")
+  #   Montrose.yearly.between(Time.current..10.years.from_now)
+  #
+  # @example Enumerating events
+  #   r = Montrose.every(:month, mday: 31, until: "January 1, 2017")
+  #   r.each { |time| puts time.to_s }
+  #   r.take(10).to_a
+  #
+  # @example Merging rules
+  #   r.merge(starts: "2017-01-01").each { |time| puts time.to_s }
+  #
+  # @example Using #events Enumerator
+  #   r.events # => #<Enumerator: ...>
+  #   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 }
+  #
   class Recurrence
+    extend Forwardable
     include Chainable
     include Enumerable
 
     attr_reader :default_options
+    def_delegator :@default_options, :total, :length
+    def_delegator :@default_options, :starts, :starts_at
+    def_delegator :@default_options, :until, :ends_at
 
     class << self
       def new(options = {})
@@ -28,7 +233,7 @@ module Montrose
       end
 
       def load(json)
-        new JSON.load(json)
+        new JSON.parse(json)
       end
     end
 
@@ -36,24 +241,52 @@ module Montrose
       @default_options = Montrose::Options.new(opts)
     end
 
-    # Returns an enumerator for iterating over
-    # timestamps in the recurrence
+    # Returns an enumerator for iterating over timestamps in the recurrence
     #
-    # @example
+    # @example Return the events
+    #   recurrence = Montrose.recurrence(every: :day)
     #   recurrence.events
     #
-    # @return [Enumerator] a enumerator of recurrence timestamps
+    # @example Iterate over a finite recurrence
+    #   recurrence = Montrose.recurrence(every: :day, until: 1.year.from_now)
+    #   recurrence.events.each do |event|
+    #     puts event
+    #   end
+    #
+    # @example Iterate over an infinite recurrence
+    #   recurrence = Montrose.recurrence(every: :day)
+    #   recurrence.events.lazy.each do |event|
+    #     puts event
+    #   end
+    #
+    # @return [Enumerator] an enumerator of recurrence timestamps
     #
     def events
       event_enum
     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
+    #   recurrence = Montrose.recurrence(every: :day, until: 1.year.from_now)
+    #   recurrence.each do |event|
+    #     puts event
+    #   end
+    #
+    # @example Iterate over an infinite recurrence
+    #   recurrence = Montrose.recurrence(every: :day)
+    #   recurrence.lazy.each do |event|
+    #     puts event
+    #   end
+    #
+    # @return [Enumerator] an enumerator of recurrence timestamps
     def each(&block)
       events.each(&block)
     end
 
-    # Returns a hash of the options used to create
-    # the recurrence
+    # Returns a hash of the options used to create the recurrence
     #
     # @return [Hash] hash of recurrence options
     #
@@ -62,8 +295,7 @@ module Montrose
     end
     alias to_h to_hash
 
-    # Returns json string of options used to create
-    # the recurrence
+    # Returns json string of options used to create the recurrence
     #
     # @return [String] json of recurrence options
     #
@@ -75,6 +307,48 @@ module Montrose
       "#<#{self.class}:#{object_id.to_s(16)} #{to_h.inspect}>"
     end
 
+    # Return true/false if given timestamp equals a timestamp given
+    # by the recurrence
+    #
+    # @return [Boolean] whether or not timestamp is included in recurrence
+    #
+    def include?(timestamp)
+      return false if earlier?(timestamp) || later?(timestamp)
+
+      recurrence = finite? ? self : starts(timestamp)
+
+      recurrence.events.lazy.each do |event|
+        return true if event == timestamp
+        return false if event > timestamp
+      end or false
+    end
+
+    # Return true/false if recurrence will iterate infinitely
+    #
+    # @return [Boolean] whether or not recurrence is infinite
+    #
+    def finite?
+      ends_at || length
+    end
+
+    # Return true/false if given timestamp occurs before
+    # the recurrence
+    #
+    # @return [Boolean] whether or not timestamp is earlier
+    #
+    def earlier?(timestamp)
+      starts_at && timestamp < starts_at
+    end
+
+    # Return true/false if given timestamp occurs after
+    # the recurrence
+    #
+    # @return [Boolean] whether or not timestamp is later
+    #
+    def later?(timestamp)
+      ends_at && timestamp > ends_at
+    end
+
     private
 
     def event_enum

data/lib/montrose/schedule.rb

@@ -1,7 +1,24 @@
 module Montrose
+  # A schedule represents a group of recurrences
+  #
+  # @author Ross Kaffenberger
+  # @since 0.0.1
+  # @attr_reader [Array] rules the list of recurrences
+  #
   class Schedule
     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?
@@ -12,6 +29,18 @@ module Montrose
       @rules = []
     end
 
+    # Add a recurrence rule to the schedule, either by hash or recurrence
+    # instance
+    #
+    # @example Add a recurrence by hash
+    #   schedule = Montrose::Schedule.new
+    #   schedule << { every: :day }
+    #
+    # @example Add a recurrence by instance
+    #   schedule = Montrose::Schedule.new
+    #   recurrence = Montrose.recurrence(every: :day)
+    #   schedule << recurrence
+    #
     def <<(rule)
       @rules << Montrose::Recurrence.new(rule)
 
@@ -19,10 +48,25 @@ module Montrose
     end
     alias add <<
 
-    def include?(time)
-      @rules.any? { |r| r.include?(time) }
+    # Return true/false if given timestamp is included in any of the rules
+    # found in the schedule
+    #
+    # @return [Boolean] whether or not timestamp is included in schedule
+    #
+    def include?(timestamp)
+      @rules.any? { |r| r.include?(timestamp) }
     end
 
+    # Returns an enumerator for iterating over timestamps in the schedule
+    #
+    # @example Return the events
+    #   schedule = Montrose::Schedule.build do |s|
+    #     s << { every: :day }
+    #   end
+    #   schedule.events
+    #
+    # @return [Enumerator] an enumerator of recurrence timestamps
+    #
     def events(opts = {})
       enums = @rules.map { |r| r.merge(opts).events }
       Enumerator.new do |y|

data/lib/montrose/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Montrose
-  VERSION = "0.4.3".freeze
+  VERSION = "0.5.0".freeze
 end

data/montrose.gemspec

@@ -28,6 +28,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 11.0"
   spec.add_development_dependency "minitest", "~> 5.9"
   spec.add_development_dependency "m", "~> 1.4"
-  spec.add_development_dependency "rubocop", "0.41.0"
+  spec.add_development_dependency "rubocop", "0.45.0"
   spec.add_development_dependency "timecop"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: montrose
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Ross Kaffenberger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-20 00:00:00.000000000 Z
+date: 2016-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -106,14 +106,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.41.0
+        version: 0.45.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.41.0
+        version: 0.45.0
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
@@ -212,7 +212,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Recurring events in Ruby