montrose 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 53a2439841915011853eef7bb8fee926939b5335
-  data.tar.gz: fad0d53e1187f6a077c6410e63016526973633c2
+  metadata.gz: edcfdb878952330a2fcc9a78db4f4e7780e643e3
+  data.tar.gz: 619002eee045e0d960de83d2bdf78078d7d74883
 SHA512:
-  metadata.gz: 6e3b010f94e12c9705278b2fc860df7d0384476a097ab4f77ca3b503fa365272a6e5af2faa34d1ec4e4692f1c192f01179e63637e85d2164fa8bedaa8ad387ac
-  data.tar.gz: 2466894b36681dc0a8bc723e72b8976dab0c8d7d340f2cf47ec15b7f52bc697b919434aae9e52e13e3e2ea27d1754d47615e05876188afb8a087bd19e0b884b7
+  metadata.gz: 7be4df5c22b3677978134b446d30c7e3bac3e33309d35f66253aea93ed62d5e60a17bf9b1a8eb8a3745260ef38dee9f74d7f057a0b2fa181f752e7a3183336b1
+  data.tar.gz: 5a1c3a19e2e5fc6a7b64c620be48926d9d257e33b3b2fde91b0588b3d1355052b0b016e011ec7cf396f2046a2e3005b10fab43de0cd648224b55b7b90383f1c4

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+### 0.2.2 - 2016-02-08
+
+* bug fixes
+  * Handle `Hash` in `Montrose::Chainable` methods that support varargs
+* enhancements
+  * Adds `Montrose.r` method for starting a new recurrence
+  * Adds `Chainable` alias methods including `#starts`, `#until`, `#repeat`
+
 ### 0.2.1 - 2016-02-03
 
 * bug fixes

data/README.md

@@ -7,6 +7,8 @@
 
 Montrose is an easy-to-use library for defining recurring events in Ruby. It uses a simple chaining system for building recurrences, inspired heavily by the design principles of [HTTP.rb](https://github.com/httprb/http) and rule definitions available in [Recurrence](https://github.com/fnando/recurrence).
 
+[Introduction](https://rossta.net/blog/recurring-events-in-ruby.html)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -28,6 +30,11 @@ Or install it yourself as:
 ```ruby
 require "montrose"
 
+# a new recurrence
+Montrose.r
+Montrose.recurrence
+Montrose::Recurrence.new
+
 # daily for 10 occurrences
 Montrose.daily(total: 10)
 
@@ -144,36 +151,36 @@ Montrose.every(20.minutes, hour: 9..16)
 
 # Minutely
 Montrose.minutely
-Montrose::Recurrence.new(every: :minute)
+Montrose.r(every: :minute)
 
 Montrose.every(10.minutes)
-Montrose::Recurrence.new(every: 10.minutes)
-Montrose::Recurrence.new(every: :minute, interval: 10) # every 10 minutes
+Montrose.r(every: 10.minutes)
+Montrose.r(every: :minute, interval: 10) # every 10 minutes
 
 Montrose.minutely(until: "9:00 PM")
-Montrose::Recurrence.new(every: :minute, until: "9:00 PM")
+Montrose.r(every: :minute, until: "9:00 PM")
 
 # Daily
 Montrose.daily
 Montrose.every(:day)
-Montrose::Recurrence.new(every: :day)
+Montrose.r(every: :day)
 
 Montrose.every(9.days)
-Montrose::Recurrence.new(every: 9.days)
-Montrose::Recurrence.new(every: :day, interval: 9)
+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::Recurrence.new(every: :day, at: "9:00 AM")
+Montrose.r(every: :day, at: "9:00 AM")
 
 Montrose.daily(total: 7)
 Montrose.every(:day, total: 7)
-Montrose::Recurrence.new(every: :day, total: 7)
+Montrose.r(every: :day, total: 7)
 
 # Weekly
 Montrose.weekly
 Montrose.every(:week)
-Montrose::Recurrence.new(every: :week)
+Montrose.r(every: :week)
 
 Montrose.every(:week, on: :monday)
 Montrose.every(:week, on: [:monday, :wednesday, :friday])
@@ -184,7 +191,7 @@ Montrose.weekly(on: :thursday)
 # Monthly by month day
 Montrose.monthly(mday: 1) # first of the month
 Montrose.every(:month, mday: 1)
-Montrose::Recurrence.new(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
@@ -193,7 +200,7 @@ Montrose.monthly(mday: 10..15) # 10th through the 15th day of the month
 # Monthly by week day
 Montrose.monthly(day: :friday, interval: 2) # every Friday every other month
 Montrose.every(:month, day: :friday, interval: 2)
-Montrose::Recurrence.new(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
@@ -203,14 +210,14 @@ Montrose.monthly(mday: 7..13, day: :saturday) # first Saturday that follow the f
 # Yearly
 Montrose.yearly
 Montrose.every(:year)
-Montrose::Recurrence.new(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::Recurrence.yearly(on: { january: 31 })
-Montrose::Recurrence.new(every: :year, on: { 10 => 31 }, interval: 3)
+Montrose.yearly(on: { january: 31 })
+Montrose.r(every: :year, on: { 10 => 31 }, interval: 3)
 
 # TODO: Remove a date in the series with :except date(s)
 Montrose.daily(:day, except: "2017-01-31")
@@ -235,9 +242,11 @@ 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 }
 ```
 
-## Goals
+## Why?
+
+`Montrose` aims to provide a simple interface for specifying and enumerating recurring events as `Time` objects.
 
-`Montrose` aims to provide a simple interface for specifying and enumerating recurring events as Time objects. To that end, the project intends to:
+More specifically, this project intends to:
 
 * embrace Ruby idioms
 * support Ruby 2.1+
@@ -245,9 +254,112 @@ r.events.lazy.select { |time| time > 1.month.from_now }.take(3).each { |date| pu
 * serialize to yaml, hash, and [ical](http://www.kanzaki.com/docs/ical/rrule.html#basic) formats
 * be suitable for integration with persistence libraries
 
-What `Montrose` isn't:
+What `Montrose` doesn't do:
 
 * support all calendaring use cases under the sun
+* schedule recurring jobs for you. See instead [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler), [sidetiq](https://github.com/tobiassvn/sidetiq), [whenever](https://github.com/javan/whenever)
+
+## Concepts
+
+Montrose allows you to easily create "recurrence" objects through chaining:
+
+```ruby
+# Every Monday at 10:30am
+Montrose.weekly.on(:monday).at("10:30 am")
+=> #<Montrose::Recurrence...>
+```
+
+Or the constructor hash-syntax:
+
+```ruby
+Montrose.r(every: :week, on: :monday, at: "10:30 am")
+=> #<Montrose::Recurrence...>
+```
+
+A Montrose recurrence responds to `#events`, which returns an [`Enumerator`](/blog/what-is-enumerator.html) that can generate timestamps:
+
+```ruby
+r = Montrose.hourly
+=> #<Montrose::Recurrence...>
+
+r.events
+=> #<Enumerator:...>
+
+r.events.take(10)
+=> [2016-02-03 18:26:08 -0500,
+2016-02-03 19:26:08 -0500,
+2016-02-03 20:26:08 -0500,
+2016-02-03 21:26:08 -0500,
+2016-02-03 22:26:08 -0500,
+2016-02-03 23:26:08 -0500,
+2016-02-04 00:26:08 -0500,
+2016-02-04 01:26:08 -0500,
+2016-02-04 02:26:08 -0500,
+2016-02-04 03:26:08 -0500]
+```
+
+Montrose recurrences are themselves enumerable:
+
+```ruby
+# Every month starting a year from now on Friday the 13th for 5 occurrences
+r = Montrose.monthly.starting(1.year.from_now).on(friday: 13).repeat(5)
+
+r.map(&:to_date)
+=> [Fri, 13 Oct 2017,
+Fri, 13 Apr 2018,
+Fri, 13 Jul 2018,
+Fri, 13 Sep 2019,
+Fri, 13 Dec 2019]
+```
+
+Each chained recurrence returns a new object so they can be composed and
+merged:
+
+```ruby
+# Every week
+r1 = Montrose.every(:week)
+r2 = Montrose.on([:tuesday, :thursday])
+r3 = Montrose.at("12 pm")
+r4 = Montrose.total(4)
+
+r1.merge(r2).merge(r3).merge(r4).to_a
+=> [2016-02-04 12:00:00 -0500,
+2016-02-09 12:00:00 -0500,
+2016-02-11 12:00:00 -0500,
+2016-02-16 12:00:00 -0500]
+```
+
+Conceptually, recurrences can represent an infinite sequence. When we say
+simply "every day", there is no implied ending. It's therefore possible to
+create a recurrence that can enumerate forever.
+
+```ruby
+# Every day starting now
+r = Montrose.daily
+
+# this expression will never complete, Ctrl-c!
+r.map(&:to_date)
+
+# so use your `Enumerable` methods wisely
+r.lazy.map(&:to_date).select { |d| d.mday > 25 }.take(5).to_a
+=> [Fri, 26 Feb 2016,
+Sat, 27 Feb 2016,
+Sun, 28 Feb 2016,
+Mon, 29 Feb 2016,
+Sat, 26 Mar 2016]
+```
+
+It's straightforward to convert a recurrence to a hash and back.
+
+```ruby
+opts = Montrose::Recurrence.new(every: 10.minutes).to_h
+=> {:every=>:minute, :interval=>10}
+
+Montrose::Recurrence.new(opts).take(3)
+=> [2016-02-03 19:06:07 -0500,
+2016-02-03 19:16:07 -0500,
+2016-02-03 19:26:07 -0500]
+```
 
 ## Inspiration
 

data/lib/montrose.rb

@@ -17,4 +17,20 @@ require "montrose/version"
 
 module Montrose
   extend Chainable
+
+  class << self
+    # Create a new recurrence from given options
+    # An alias to {Montrose::Recurrence.new}
+    #
+    # @param options [Hash] recurrence options
+    #
+    # @example
+    #   Montrose.recurrence(every: :day)
+    #   Montrose.r(every: :day)
+    #
+    # @return [Montrose::Recurrence]
+    #
+    alias recurrence branch
+    alias r branch
+  end
 end

data/lib/montrose/chainable.rb

@@ -16,6 +16,8 @@ module Montrose
     #   Montrose.every(3.days, starts: 2.days.from_now)
     #   Montrose.every(1.year, until: 10.days.from_now)
     #
+    # @return [Montrose::Recurrence]
+    #
     def every(frequency, options = {})
       branch options.merge(every: frequency)
     end
@@ -32,6 +34,8 @@ module Montrose
     #   Montrose.minutely(total: 5)
     #   Montrose.minutely(except: Date.tomorrow)
     #
+    # @return [Montrose::Recurrence]
+    #
     def minutely(options = {})
       branch options.merge(every: :minute)
     end
@@ -48,6 +52,8 @@ module Montrose
     #   Montrose.hourly(total: 5)
     #   Montrose.hourly(except: Date.tomorrow)
     #
+    # @return [Montrose::Recurrence]
+    #
     def hourly(options = {})
       branch options.merge(every: :hour)
     end
@@ -64,6 +70,8 @@ module Montrose
     #   Montrose.daily(total: 5)
     #   Montrose.daily(except: Date.tomorrow)
     #
+    # @return [Montrose::Recurrence]
+    #
     def daily(options = {})
       branch options.merge(every: :day)
     end
@@ -79,6 +87,8 @@ module Montrose
     #   Montrose.weekly(on: :saturday, interval: 2)
     #   Montrose.weekly(on: :saturday, total: 5)
     #
+    # @return [Montrose::Recurrence]
+    #
     def weekly(options = {})
       branch options.merge(every: :week)
     end
@@ -92,6 +102,8 @@ module Montrose
     #   Montrose.monthly(mday: -3) # third-to-last day of the month
     #   Montrose.monthly(mday: 10..15) # 10th through the 15th day of the month
     #
+    # @return [Montrose::Recurrence]
+    #
     def monthly(options = {})
       branch options.merge(every: :month)
     end
@@ -107,6 +119,8 @@ module Montrose
     #   Montrose.yearly(on: [:january, 14], interval: 2)
     #   Montrose.yearly(on: [:january, 14], total: 5)
     #
+    # @return [Montrose::Recurrence]
+    #
     def yearly(options = {})
       branch options.merge(every: :year)
     end
@@ -118,9 +132,12 @@ module Montrose
     # @example
     #   Montrose.daily.starting(Date.tomorrow)
     #
-    def starting(starts_at)
+    # @return [Montrose::Recurrence]
+    #
+    def starts(starts_at)
       merge(starts: starts_at)
     end
+    alias starting starts
 
     # Create a recurrence ending at given timestamp.
     #
@@ -129,9 +146,12 @@ module Montrose
     # @example
     #   Montrose.daily.ending(1.year.from_now)
     #
-    def ending(ends_at)
+    # @return [Montrose::Recurrence]
+    #
+    def until(ends_at)
       merge(until: ends_at)
     end
+    alias ending until
 
     # Create a recurrence occurring during date range.
     #
@@ -140,6 +160,8 @@ module Montrose
     # @example
     #   Montrose.weekly.between(Date.today..Date.new(2016, 3, 15))
     #
+    # @return [Montrose::Recurrence]
+    #
     def between(date_range)
       merge(between: date_range)
     end
@@ -152,6 +174,8 @@ module Montrose
     #   Montrose.weekly.on(:friday)
     #   Montrose.monthly.on(friday: 13)
     #
+    # @return [Montrose::Recurrence]
+    #
     def on(day)
       merge(on: day)
     end
@@ -164,6 +188,8 @@ module Montrose
     #   Montrose.daily.at("12pm")
     #   Montrose.daily.at("9:37am")
     #
+    # @return [Montrose::Recurrence]
+    #
     def at(time)
       merge(at: time)
     end
@@ -177,6 +203,8 @@ module Montrose
     #   Montrose.daily.day_of_month([1, -1])
     #   Montrose.daily.day_of_month(2..8)
     #
+    # @return [Montrose::Recurrence]
+    #
     def day_of_month(days, *extras)
       merge(mday: days.array_concat(extras))
     end
@@ -191,6 +219,8 @@ module Montrose
     #   Montrose.daily.day_of_week(:monday, :tuesday)
     #   Montrose.daily.day_of_week(2..5)
     #
+    # @return [Montrose::Recurrence]
+    #
     def day_of_week(weekdays, *extras)
       merge(day: weekdays.array_concat(extras))
     end
@@ -205,6 +235,8 @@ module Montrose
     #   Montrose.daily.day_of_year([1, 10, 100])
     #   Montrose.daily.day_of_year(20..50)
     #
+    # @return [Montrose::Recurrence]
+    #
     def day_of_year(days, *extras)
       merge(yday: days.array_concat(extras))
     end
@@ -219,6 +251,8 @@ module Montrose
     #   Montrose.hourly.hour_of_day(15)
     #   Montrose.hourly.hour_of_day(6..10)
     #
+    # @return [Montrose::Recurrence]
+    #
     def hour_of_day(hours, *extras)
       merge(hour: hours.array_concat(extras))
     end
@@ -233,6 +267,8 @@ module Montrose
     #   Montrose.monthly.month_of_year([2, 5])
     #   Montrose.monthly.month_of_year(2..5)
     #
+    # @return [Montrose::Recurrence]
+    #
     def month_of_year(months, *extras)
       merge(month: months.array_concat(extras))
     end
@@ -247,6 +283,8 @@ module Montrose
     #   Montrose.weekly.week_of_year([2, 5])
     #   Montrose.weekly.week_of_year(2..5)
     #
+    # @return [Montrose::Recurrence]
+    #
     def week_of_year(weeks, *extras)
       merge(week: weeks.array_concat(extras))
     end
@@ -259,31 +297,36 @@ module Montrose
     # @example
     #   Montrose.daily.total(10)
     #
+    # @return [Montrose::Recurrence]
+    #
     def total(total)
       merge(total: total)
     end
+    alias repeat total
 
     # Create a new recurrence combining options of self
     # and other. The value of entries with duplicate
     # keys will be those of other
     #
-    # @param opts [Hash,Montrose::Recurrence] other options or recurrence
+    # @param other [Hash,Montrose::Recurrence] other options or recurrence
     #
     # @example
     #   Montrose.daily.total(10)
     #
+    # @return [Montrose::Recurrence]
+    #
     def merge(other = {})
       branch default_options.merge(other)
     end
 
     # @private
-    def default_options
-      @default_options ||= Montrose::Options.new
+    def branch(options)
+      Montrose::Recurrence.new(options)
     end
 
     # @private
-    def branch(options)
-      Montrose::Recurrence.new(options)
+    def default_options
+      @default_options ||= Montrose::Options.new
     end
   end
 end

data/lib/montrose/recurrence.rb

@@ -36,6 +36,14 @@ module Montrose
       @default_options = Montrose::Options.new(opts)
     end
 
+    # Returns an enumerator for iterating over
+    # timestamps in the recurrence
+    #
+    # @example
+    #   recurrence.events
+    #
+    # @return [Enumerator] a enumerator of recurrence timestamps
+    #
     def events
       event_enum
     end
@@ -44,6 +52,11 @@ module Montrose
       events.each(&block)
     end
 
+    # Returns a hash of the options used to create
+    # the recurrence
+    #
+    # @return [Hash] hash of recurrence options
+    #
     def to_hash
       default_options.to_hash
     end

data/lib/montrose/refinements/array_concat.rb

@@ -6,6 +6,14 @@ module Montrose
           Array(self) + other
         end
       end
+
+      refine Hash do
+        # array concat for Hash not supported
+        # so we just return self
+        def array_concat(_other)
+          self
+        end
+      end
     end
   end
 end

data/lib/montrose/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: montrose
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Ross Kaffenberger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-03 00:00:00.000000000 Z
+date: 2016-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -186,7 +186,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