montrose 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: edcfdb878952330a2fcc9a78db4f4e7780e643e3
-  data.tar.gz: 619002eee045e0d960de83d2bdf78078d7d74883
+  metadata.gz: a88cd103fc68290cf832c8e41ec2e8a1ca4d4a87
+  data.tar.gz: c74c51dad1844316155c1b138b0b34f548d27dfd
 SHA512:
-  metadata.gz: 7be4df5c22b3677978134b446d30c7e3bac3e33309d35f66253aea93ed62d5e60a17bf9b1a8eb8a3745260ef38dee9f74d7f057a0b2fa181f752e7a3183336b1
-  data.tar.gz: 5a1c3a19e2e5fc6a7b64c620be48926d9d257e33b3b2fde91b0588b3d1355052b0b016e011ec7cf396f2046a2e3005b10fab43de0cd648224b55b7b90383f1c4
+  metadata.gz: 3d186764038aaeb902fb809225a5e26779831e55a3ed0cc11998a6395821c9ab4e34af9d0152f43558f660c39d02ad9e2eff82630e24d56986e1958d0ff51de6
+  data.tar.gz: 4c939c9c4e6a416f20fb24b718d6fab5026b17650f72e5769b03abaa40ecc10d002a6a8210cd0ec6ae44c832d41020a222cf5e248597ede1754d830e8587d92b

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+### 0.3.0 - (2016-02-19)
+
+* enhancements
+  * Adds `:except` option and chainable method to filter timestamps by date (by
+    @thewatts)
+* bug fixes
+  * Fix recurrences when specifying both `:starts` and `:at` by treating
+    `:starts` value like a date
+  * Respect recurrence rules using multiple `:at` values
+  * Using `Montrose.r` without any arguments no longer throws `ArgumentError`
+
 ### 0.2.2 - 2016-02-08
 
 * bug fixes
@@ -5,6 +16,7 @@
 * enhancements
   * Adds `Montrose.r` method for starting a new recurrence
   * Adds `Chainable` alias methods including `#starts`, `#until`, `#repeat`
+  * README updates (by @thegcat)
 
 ### 0.2.1 - 2016-02-03
 

data/Gemfile

@@ -1,6 +1,5 @@
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in cure.gemspec
 gemspec
 
 group :development do

data/README.md

@@ -7,7 +7,9 @@
 
 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)
+* [Introductory blog post](http://bit.ly/1PA68Zb)
+* [NYC.rb
+  presentation](https://speaderdeck.com/rossta/recurring-events-with-montrose)
 
 ## Installation
 
@@ -25,6 +27,135 @@ Or install it yourself as:
 
     $ gem install montrose
 
+## Why
+
+Dealing with recurring events is hard. `Montrose` provides a simple interface for specifying and enumerating recurring events as `Time` objects.
+
+More specifically, this project intends to:
+
+* embrace Ruby idioms
+* support Ruby 2.1+
+* be reasonably performant
+* 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` 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), [sidekiq-cron](https://github.com/ondrejbartas/sidekiq-cron), [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...>
+```
+
+Each chained recurrence returns a **new object** so they can be composed and merged. In both examples below, recurrence `r4` represents 'every week on Tuesday and Thursday at noon for four occurrences'.
+
+```ruby
+# Example 1 - building recurrence in succession
+r1 = Montrose.every(:week)
+r2 = r1.on([:tuesday, :thursday])
+r3 = r2.at("12 pm")
+r4 = r3.total(4)
+
+# Example 2 - merging distinct recurrences
+r1 = Montrose.every(:week)
+r2 = Montrose.on([:tuesday, :thursday])
+r3 = Montrose.at("12 pm")
+r4 = r1.merge(r2).merge(r3).total(4)
+```
+
+Most recurrence methods accept additional options if you favor the hash-syntax:
+
+```ruby
+Montrose.r(every: :week, on: :monday, at: "10:30 am")
+=> #<Montrose::Recurrence...>
+```
+
+See [the docs for `Montrose::Chainable`](https://rossta.net/montrose/Montrose/Chainable.html) for more info on recurrence creation methods.
+
+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]
+```
+
+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, so use your `Enumerable` methods wisely.
+
+```ruby
+# Every day starting now
+r = Montrose.daily
+
+# this expression will never complete, Ctrl-c!
+r.map(&:to_date)
+
+# use `lazy` enumerator to avoid eager enumeration
+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]
+```
+
+A recurrence object must minimally specify a frequency, e.g. `:minute`, `:hour`, `:day`, `:week`, `:month`, or, `:year`, to be viable. Otherwise, you'll see an informative error message when attempting to enumerate the recurrence.
+
+```ruby
+r = Montrose.at("12pm")
+=> #<Montrose::Recurrence...>
+r.each
+Montrose::ConfigurationError: Please specify the :every option
+```
+
 ## Usage
 
 ```ruby
@@ -60,7 +191,7 @@ Montrose.weekly(total: 10)
 # 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
+Montrose.every(:week, until: ends_on, starts: starts_on)
 
 # every other week forever
 Montrose.every(2.weeks)
@@ -219,7 +350,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)
 
-# TODO: Remove a date in the series with :except date(s)
 Montrose.daily(:day, except: "2017-01-31")
 Montrose.daily(except: [Date.today, "2017-01-31"])
 
@@ -242,125 +372,6 @@ 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 }
 ```
 
-## Why?
-
-`Montrose` aims to provide a simple interface for specifying and enumerating recurring events as `Time` objects.
-
-More specifically, this project intends to:
-
-* embrace Ruby idioms
-* support Ruby 2.1+
-* be reasonably performant
-* 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` 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
 
 Montrose is named after the beautifully diverse and artistic [neighborhood in Houston, Texas](https://en.wikipedia.org/wiki/Montrose,_Houston).
@@ -369,9 +380,10 @@ Montrose is named after the beautifully diverse and artistic [neighborhood in Ho
 
 Check out following related projects, all of which have provided inspiration for `Montrose`.
 
-* [recurrence](https://github.com/fnando/recurrence)
 * [ice_cube](https://github.com/seejohnrun/ice_cube)
+* [recurrence](https://github.com/fnando/recurrence)
 * [runt](https://github.com/mlipper/runt)
+* [http.rb](https://github.com/httprb/http) - not a recurrence project, but inspirational to design, implementation, and interface of `Montrose`
 
 ## Development
 

data/lib/montrose.rb

@@ -30,7 +30,9 @@ module Montrose
     #
     # @return [Montrose::Recurrence]
     #
-    alias recurrence branch
-    alias r branch
+    def recurrence(options = {})
+      branch(options)
+    end
+    alias r recurrence
   end
 end

data/lib/montrose/chainable.rb

@@ -194,6 +194,20 @@ module Montrose
       merge(at: time)
     end
 
+    # Create a recurrence with dates except dates given
+    #
+    # @param date [String, Date] represents date
+    #
+    # @example
+    #   Montrose.daily.except("2016-03-01")
+    #   Montrose.daily.except(Date.today)
+    #
+    # @return [Montrose::Recurrence]
+    #
+    def except(date)
+      merge(except: date)
+    end
+
     # Create a recurrence for given days of month
     #
     # @param days [Fixnum] days of month, e.g. 1, 2, -1, ...

data/lib/montrose/clock.rb

@@ -6,8 +6,9 @@ module Montrose
       @options = Montrose::Options.merge(opts)
       @time = nil
       @every = @options.fetch(:every) { fail ConfigurationError, "Required option :every not provided" }
-      @starts = @options.fetch(:starts)
       @interval = @options.fetch(:interval)
+      @start_time = @options.fetch(:start_time)
+      @at = @options.fetch(:at, nil)
     end
 
     # Advances time to new unit by increment and sets
@@ -18,13 +19,25 @@ module Montrose
     end
 
     def peek
-      return @starts if @time.nil?
+      return @start_time if @time.nil?
 
-      @time.advance(step)
+      if @at
+        times = @at.map { |(hour, min)| @time.change(hour: hour, min: min) }
+
+        min_next = times.select { |t| t > @time }.min and return min_next
+
+        advance_step(times.min || @time)
+      else
+        advance_step(@time)
+      end
     end
 
     private
 
+    def advance_step(time)
+      time.advance(step)
+    end
+
     def step
       @step ||= smallest_step or fail ConfigurationError, "No step for #{@options.inspect}"
     end

data/lib/montrose/frequency.rb

@@ -45,7 +45,7 @@ module Montrose
     def initialize(opts = {})
       opts = Montrose::Options.merge(opts)
       @time = nil
-      @starts = opts.fetch(:starts)
+      @starts = opts.fetch(:start_time)
       @interval = opts.fetch(:interval)
     end
 

data/lib/montrose/options.rb

@@ -1,5 +1,7 @@
 module Montrose
   class Options
+    include Montrose::Utils
+
     @default_starts = nil
     @default_until = nil
     @default_every = nil
@@ -65,7 +67,6 @@ module Montrose
 
       def default_options
         {
-          starts: default_starts,
           until: default_until,
           interval: 1
         }
@@ -86,6 +87,7 @@ module Montrose
     def_option :between
     def_option :at
     def_option :on
+    def_option :except
 
     def initialize(opts = {})
       defaults = {
@@ -163,7 +165,7 @@ module Montrose
     end
 
     def day=(days)
-      @day = nested_map_arg(days) { |d| Montrose::Utils.day_number!(d) }
+      @day = nested_map_arg(days) { |d| day_number!(d) }
     end
 
     def mday=(mdays)
@@ -179,7 +181,7 @@ module Montrose
     end
 
     def month=(months)
-      @month = map_arg(months) { |d| Montrose::Utils.month_number!(d) }
+      @month = map_arg(months) { |d| month_number!(d) }
     end
 
     def between=(range)
@@ -194,11 +196,7 @@ module Montrose
     end
 
     def at=(time)
-      times = map_arg(time) { |t| as_time(t) }
-      now = Time.now
-      first = times.map { |t| t < now ? t + 24.hours : t }.min
-      self[:starts] = first if first
-      @at = times
+      @at = map_arg(time) { |t| as_time_parts(t) }
     end
 
     def on=(arg)
@@ -209,12 +207,30 @@ module Montrose
       @on = arg
     end
 
+    def except=(date)
+      @except = map_arg(date) { |d| as_date(d) }
+    end
+
     def inspect
       "#<#{self.class} #{to_h.inspect}>"
     end
 
+    def start_time
+      time = starts || default_starts
+
+      if at
+        at.map { |(hour, min)| time.change(hour: hour, min: min) }.min || time
+      else
+        time
+      end
+    end
+
     private
 
+    def default_starts
+      self.class.default_starts
+    end
+
     def nested_map_arg(arg, &block)
       case arg
       when Hash
@@ -233,7 +249,7 @@ module Montrose
     end
 
     def map_days(arg)
-      map_arg(arg) { |d| Montrose::Utils.day_number!(d) }
+      map_arg(arg) { |d| day_number!(d) }
     end
 
     def map_mdays(arg)
@@ -275,9 +291,9 @@ module Montrose
     end
 
     def month_or_day(key)
-      month = Montrose::Utils.month_number(key)
+      month = month_number(key)
       return [:month, month] if month
-      day = Montrose::Utils.day_number(key)
+      day = day_number(key)
       return [:day, day] if day
       fail ConfigurationError, "Did not recognize #{key} as a month or day"
     end
@@ -289,17 +305,11 @@ module Montrose
       item
     end
 
-    def as_time(time)
-      return nil unless time
+    def as_time_parts(arg)
+      return arg if arg.is_a?(Array)
 
-      case
-      when time.is_a?(String)
-        Time.parse(time)
-      when time.respond_to?(:to_time)
-        time.to_time
-      else
-        Array(time).flat_map { |d| as_time(d) }
-      end
+      time = as_time(arg)
+      [time.hour, time.min]
     end
 
     def parse_frequency(input)

data/lib/montrose/rule.rb

@@ -38,6 +38,7 @@ require "montrose/rule/before"
 require "montrose/rule/day_of_month"
 require "montrose/rule/day_of_week"
 require "montrose/rule/day_of_year"
+require "montrose/rule/except"
 require "montrose/rule/hour_of_day"
 require "montrose/rule/month_of_year"
 require "montrose/rule/nth_day_of_month"

data/lib/montrose/rule/except.rb

@@ -0,0 +1,23 @@
+module Montrose
+  module Rule
+    class Except
+      include Montrose::Rule
+
+      def self.apply_options(opts)
+        opts[:except]
+      end
+
+      # Initializes rule
+      #
+      # @param [Date] dates - array of date objects
+      #
+      def initialize(dates)
+        @dates = dates
+      end
+
+      def include?(time)
+        !@dates.include?(time.to_date)
+      end
+    end
+  end
+end

data/lib/montrose/rule/time_of_day.rb

@@ -16,7 +16,7 @@ module Montrose
       end
 
       def include?(time)
-        times_of_day.include?(parts(time))
+        @times.include?(parts(time))
       end
 
       private
@@ -24,10 +24,6 @@ module Montrose
       def parts(time)
         [time.hour, time.min]
       end
-
-      def times_of_day
-        @times_of_day ||= @times.map { |t| parts(t) }
-      end
     end
   end
 end

data/lib/montrose/stack.rb

@@ -11,6 +11,7 @@ module Montrose
         Frequency,
         Rule::After,
         Rule::Before,
+        Rule::Except,
         Rule::Total,
         Rule::TimeOfDay,
         Rule::HourOfDay,

data/lib/montrose/utils.rb

@@ -5,6 +5,23 @@ module Montrose
     MONTHS = Date::MONTHNAMES
     DAYS = Date::DAYNAMES
 
+    def as_time(time)
+      return nil unless time
+
+      case
+      when time.is_a?(String)
+        Time.parse(time)
+      when time.respond_to?(:to_time)
+        time.to_time
+      else
+        Array(time).flat_map { |d| as_time(d) }
+      end
+    end
+
+    def as_date(time)
+      as_time(time).to_date
+    end
+
     def month_number(name)
       case name
       when Symbol, String

data/lib/montrose/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: montrose
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Ross Kaffenberger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-09 00:00:00.000000000 Z
+date: 2016-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -153,6 +153,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/except.rb
 - lib/montrose/rule/hour_of_day.rb
 - lib/montrose/rule/month_of_year.rb
 - lib/montrose/rule/nth_day_matcher.rb
@@ -186,7 +187,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Recurring events in Ruby