montrose 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d44082eaa05a068714f05fe6116f8442b0507b3c7612174d93716ce6fd4af4ba
-  data.tar.gz: 691d88452db689b1555772b6749ae12e72bf675fbc55d4082b2d7f4cd41dd795
+  metadata.gz: c4b7914b70270912f8acf6757a8f130112d9137c50c34b933714f0edf97ac3c1
+  data.tar.gz: d70713d758bf62b45a7a74196f3d2c5bcc0a4bcf48b899164d7b5d4e2afe6b4a
 SHA512:
-  metadata.gz: 389adad3b13244fdb642204fa158bde6a204de4c752cab7a11dc1fe2a237a98f7b73c905477fd335d47164b795921a92090b68a528327b115ff2721b8c2945f7
-  data.tar.gz: 9ce4b11ae2d6c0fd06b06ca9fe56aa05767bca879be8c5cd3a24dae1c7fed442ca50d4195cf5225ff42f1bb2f2704a9ab8fb308b0a9167865317a245dd782441
+  metadata.gz: 5ea9a0877d09b1d360c3de7dc9b68a4fd9b6f64047728991d0398333777c18afa06f12fba1b2e178f53bd412f054314b125a174099a896c554cc53a337672fb5
+  data.tar.gz: f0b7431307846f0fa969352cfb98101ae2542ad37dd443e8324dd1480b01edfa81f8c06f92b6dc96f4278410f7cb221b7a1c1a487241a0faf8f5ee07fd763db3

data/.circleci/config.yml

@@ -1,6 +1,6 @@
 version: 2.1
 orbs:
-  ruby: circleci/ruby@1.1.2
+  ruby: circleci/ruby@1.3.0
 commands:
   run-tests:
     description: Run tests
@@ -37,7 +37,7 @@ jobs:
       gemfile:
         type: string
     docker:
-      - image: 'circleci/ruby:<< parameters.ruby_version >>'
+      - image: 'cimg/ruby:<< parameters.ruby_version >>'
     environment:
       GEMFILE_NAME: <<parameters.gemfile>>
     steps:
@@ -53,13 +53,14 @@ workflows:
       - test:
           matrix:
             parameters:
-              ruby_version: ['2.5', '2.6', '2.7']
+              ruby_version: ['2.6', '2.7', '3.0', '3.1']
               gemfile:
                 [
                   'gemfiles/activesupport_5.2.gemfile',
                   'gemfiles/activesupport_6.0.gemfile',
                   'gemfiles/activesupport_6.1.gemfile',
+                  'gemfiles/activesupport_7.0.gemfile',
                 ]
-            # exclude:
-            #   - ruby_version: '3.0'
-            #   - gemfile: rails_5_2.gemfile
+            exclude:
+              - ruby_version: '2.6'
+                gemfile: gemfiles/activesupport_7.0.gemfile

data/Appraisals

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
+appraise "activesupport-7.0" do
+  gem "activesupport", "~> 7.0"
+end
+
 appraise "activesupport-6.1" do
-  gem "activesupport", "~> 6.1.0"
+  gem "activesupport", "~> 6.1"
 end
 
 appraise "activesupport-6.0" do
-  gem "activesupport", "~> 6.0.0"
+  gem "activesupport", "~> 6.0"
 end
 
 appraise "activesupport-5.2" do
-  gem "activesupport", "~> 5.2.0"
+  gem "activesupport", "~> 5.2"
 end

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+### 0.12.0 - (2021-02-02)
+
+* enhancements
+  * Adds `Montrose.covering` to disambiguate `Montrose.between` behavior
+  `#covering` provides recurrence masking behavior, i.e., only recurrences
+  within the given range will be emitted
+  * Added support for ActiveSupport 6 and Ruby 2.7
+  * Adds `Montrose#infinite?` and ensures `Montrose.finite?` returns a boolean
+
+* bug fixes
+  * Fixes `Recurrence#include?` behavior for infinite recurrences with
+  intervals > 1
+
+* breaking changes
+  * `Montrose.between` no longer provides masking behavior, which is now
+  provided by `Montrose.covering`. A global option can be used
+  `Montrose.enable_deprecated_between_masking = true` to retain the legacy
+  behavior for `Montrose.between`. This option will be removed in v1.0.
+  * Dropped official support for EOL'd rubies and ActiveSupport < 5.2
+
+* miscellaneous
+  * switched from Travis to CircleCi for builds
+  * switched default branch to `main`
+#
 ### 0.11.0 - (2019-08-16)
 
 * enhancements

data/README.md

@@ -4,10 +4,10 @@
 [![Code Climate](https://codeclimate.com/github/rossta/montrose/badges/gpa.svg)](https://codeclimate.com/github/rossta/montrose)
 [![Coverage Status](https://coveralls.io/repos/rossta/montrose/badge.svg?branch=master&service=github)](https://coveralls.io/github/rossta/montrose?branch=master)
 
-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).
+Montrose is an easy-to-use library for defining recurring events in Ruby. It uses a simple chaining system for building enumerable 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).
 
-* [Introductory blog post](http://bit.ly/1PA68Zb)
-* [NYC.rb
+- [Introductory blog post](http://bit.ly/1PA68Zb)
+- [NYC.rb
   presentation](https://speakerdeck.com/rossta/recurring-events-with-montrose)
 
 ## Installation
@@ -32,17 +32,17 @@ Dealing with recurring events is hard. `Montrose` provides a simple interface fo
 
 More specifically, this project intends to:
 
-* model recurring events in Ruby
-* embrace Ruby idioms
-* support recent Rubies
-* 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
+- model recurring events in Ruby
+- embrace Ruby idioms
+- support recent Rubies
+- 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 your Rails app. Use one of these instead: [cron](https://en.wikipedia.org/wiki/Cron), [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)
+- support all calendaring use cases under the sun
+- schedule recurring jobs for your Rails app. Use one of these instead: [cron](https://en.wikipedia.org/wiki/Cron), [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
 
@@ -392,13 +392,16 @@ 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:
 
@@ -419,7 +422,9 @@ class RecurringEvent < ApplicationRecord
 
 end
 ```
+
 `Montrose::Schedule` can also be serialized:
+
 ```ruby
 class RecurringEvent < ApplicationRecord
   serialize :recurrence, Montrose::Schedule
@@ -435,10 +440,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`.
 
-* [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`
+- [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/gemfiles/activesupport_5.2.gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "activesupport", "~> 5.2.0"
+gem "activesupport", "~> 5.2"
 
 group :development do
   gem "coveralls"

data/gemfiles/activesupport_6.0.gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "activesupport", "~> 6.0.0"
+gem "activesupport", "~> 6.0"
 
 group :development do
   gem "coveralls"

data/gemfiles/activesupport_6.1.gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "activesupport", "~> 6.1.0"
+gem "activesupport", "~> 6.1"
 
 group :development do
   gem "coveralls"

data/gemfiles/activesupport_7.0.gemfile

@@ -0,0 +1,16 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activesupport", "~> 7.0"
+
+group :development do
+  gem "coveralls"
+  gem "yard"
+  gem "guard"
+  gem "guard-minitest"
+  gem "guard-rubocop"
+  gem "pry-byebug"
+end
+
+gemspec path: "../"

data/lib/montrose/chainable.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "montrose/options"
 require "montrose/refinements/array_concat"
 
 module Montrose

data/lib/montrose/day.rb

@@ -0,0 +1,83 @@
+module Montrose
+  class Day
+    extend Montrose::Utils
+
+    NAMES = ::Date::DAYNAMES
+    TWO_LETTER_ABBREVIATIONS = %w[SU MO TU WE TH FR SA].freeze
+    THREE_LETTER_ABBREVIATIONS = %w[SUN MON TUE WED THU FRI SAT]
+    NUMBERS = NAMES.map.with_index { |_n, i| i.to_s }
+
+    ICAL_MATCH = /(?<ordinal>[+-]?\d+)?(?<day>[A-Z]{2})/ # e.g. 1FR
+
+    class << self
+      def parse(arg)
+        case arg
+        when Hash
+          parse_entries(arg.entries)
+        when String
+          parse(arg.split(","))
+        else
+          parse_entries(map_arg(arg) { |value| parse_value(value) })
+        end
+      end
+
+      def parse_entries(entries)
+        hash = Hash.new { |h, k| h[k] = [] }
+        result = entries.each_with_object(hash) { |(k, v), hash|
+          index = number!(k)
+          hash[index] = hash[index] + [*v]
+        }
+        result.values.all?(&:empty?) ? result.keys : result
+      end
+
+      def parse_value(value)
+        parse_ical(value) || [number!(value), nil]
+      end
+
+      def parse_ical(value)
+        (match = ICAL_MATCH.match(value.to_s)) || (return nil)
+        index = number!(match[:day])
+        ordinal = match[:ordinal]&.to_i
+        [index, ordinal]
+      end
+
+      def map_arg(arg, &block)
+        return nil unless arg.present?
+
+        Array(arg).map(&block)
+      end
+
+      def names
+        NAMES
+      end
+
+      def number(name)
+        case name
+        when 0..6
+          name
+        when Symbol, String
+          string = name.to_s.downcase
+          NAMES.index(string.titleize) ||
+            TWO_LETTER_ABBREVIATIONS.index(string.upcase) ||
+            THREE_LETTER_ABBREVIATIONS.index(string.upcase) ||
+            number(to_index(string))
+        when Array
+          number name.first
+        end
+      end
+
+      def number!(name)
+        number(name) || raise(ConfigurationError,
+          "Did not recognize day #{name}, must be one of #{(names + abbreviations + numbers).inspect}")
+      end
+
+      def numbers
+        NUMBERS
+      end
+
+      def abbreviations
+        TWO_LETTER_ABBREVIATIONS + THREE_LETTER_ABBREVIATIONS
+      end
+    end
+  end
+end

data/lib/montrose/frequency.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
-require "montrose/errors"
-require "montrose/options"
-
 module Montrose
   # Abstract class for special recurrence rule required
   # in all instances of Recurrence. Frequency describes
   # the base recurrence interval.
   #
   class Frequency
+    autoload :Daily, "montrose/frequency/daily"
+    autoload :Hourly, "montrose/frequency/hourly"
+    autoload :Minutely, "montrose/frequency/minutely"
+    autoload :Monthly, "montrose/frequency/monthly"
+    autoload :Secondly, "montrose/frequency/secondly"
+    autoload :Weekly, "montrose/frequency/weekly"
+    autoload :Yearly, "montrose/frequency/yearly"
+
     include Montrose::Rule
 
     FREQUENCY_TERMS = {
@@ -25,24 +30,60 @@ module Montrose
 
     attr_reader :time, :starts
 
-    # Factory method for instantiating the appropriate Frequency
-    # subclass.
-    #
-    def self.from_options(opts)
-      frequency = opts.fetch(:every) { fail ConfigurationError, "Please specify the :every option" }
-      class_name = FREQUENCY_TERMS.fetch(frequency.to_s) {
-        fail "Don't know how to enumerate every: #{frequency}"
-      }
+    class << self
+      def parse(input)
+        if input.respond_to?(:parts)
+          frequency, interval = duration_to_frequency_parts(input)
+          {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}
+        else
+          {every: Frequency.assert(input)}
+        end
+      end
 
-      Montrose::Frequency.const_get(class_name).new(opts)
-    end
+      # Factory method for instantiating the appropriate Frequency
+      # subclass.
+      #
+      def from_options(opts)
+        frequency = opts.fetch(:every) { fail ConfigurationError, "Please specify the :every option" }
+        class_name = FREQUENCY_TERMS.fetch(frequency.to_s) {
+          fail "Don't know how to enumerate every: #{frequency}"
+        }
+
+        Montrose::Frequency.const_get(class_name).new(opts)
+      end
 
-    # @private
-    def self.assert(frequency)
-      FREQUENCY_TERMS.key?(frequency.to_s) || fail(ConfigurationError,
-        "Don't know how to enumerate every: #{frequency}")
+      def from_term(term)
+        FREQUENCY_TERMS.invert.map { |k, v| [k.downcase, v] }.to_h.fetch(term.downcase) do
+          fail "Don't know how to convert #{term} to a Montrose frequency"
+        end
+      end
 
-      frequency.to_sym
+      # @private
+      def assert(frequency)
+        FREQUENCY_TERMS.key?(frequency.to_s) || fail(ConfigurationError,
+          "Don't know how to enumerate every: #{frequency}")
+
+        frequency.to_sym
+      end
+
+      # @private
+      def numeric_to_frequency_parts(number)
+        parts = nil
+        %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?
+        end
+        parts
+      end
+
+      # @private
+      def duration_to_frequency_parts(duration)
+        duration.parts.first
+      end
     end
 
     def initialize(opts = {})
@@ -67,11 +108,3 @@ module Montrose
     end
   end
 end
-
-require "montrose/frequency/daily"
-require "montrose/frequency/hourly"
-require "montrose/frequency/minutely"
-require "montrose/frequency/monthly"
-require "montrose/frequency/secondly"
-require "montrose/frequency/weekly"
-require "montrose/frequency/yearly"

data/lib/montrose/hour.rb

@@ -0,0 +1,22 @@
+module Montrose
+  class Hour
+    HOURS_IN_DAY = 1.upto(24).to_a.freeze
+
+    class << self
+      def parse(arg)
+        case arg
+        when String
+          parse(arg.split(","))
+        else
+          Array(arg).map { |h| assert(h.to_i) }.presence
+        end
+      end
+
+      def assert(hour)
+        raise ConfigurationError, "Out of range: #{HOURS_IN_DAY.inspect} does not include #{hour}" unless HOURS_IN_DAY.include?(hour)
+
+        hour
+      end
+    end
+  end
+end

data/lib/montrose/ical.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Montrose
+  class ICal
+    # DTSTART;TZID=US-Eastern:19970902T090000
+    # RRULE:FREQ=DAILY;INTERVAL=2
+    def self.parse(ical)
+      new(ical).parse
+    end
+
+    def initialize(ical)
+      @ical = ical
+    end
+
+    def parse
+      time_zone = extract_time_zone(@ical)
+
+      Time.use_zone(time_zone) do
+        Hash[*parse_properties(@ical)]
+      end
+    end
+
+    private
+
+    def extract_time_zone(ical_string)
+      _label, time_string = ical_string.split("\n").grep(/^DTSTART/).join.split(";")
+      time_zone_rule, _ = time_string.split(":")
+      _label, time_zone = (time_zone_rule || "").split("=")
+      time_zone
+    end
+
+    # First pass parsing to normalize arbitrary line breaks
+    def property_lines(ical_string)
+      ical_string.split("\n").each_with_object([]) do |line, lines|
+        case line
+        when /^(DTSTART|DTEND|EXDATE|RDATE|RRULE)/
+          lines << line
+        else
+          (lines.last || lines << "")
+          lines.last << line
+        end
+      end
+    end
+
+    def parse_properties(ical_string)
+      property_lines(ical_string).flat_map do |line|
+        (property, value) = line.split(":")
+        (property, tzid) = property.split(";")
+
+        case property
+        when "DTSTART"
+          parse_dtstart(tzid, value)
+        when "DTEND"
+          warn "DTEND not currently supported!"
+        when "EXDATE"
+          parse_exdate(value)
+        when "RDATE"
+          warn "RDATE not currently supported!"
+        when "RRULE"
+          parse_rrule(value)
+        end
+      end
+    end
+
+    def parse_dtstart(tzid, time)
+      return [] unless time.present?
+
+      @starts_at = parse_time([tzid, time].compact.join(":"))
+
+      [:starts, @starts_at]
+    end
+
+    def parse_timezone(time_string)
+       time_zone_rule, _ = time_string.split(":")
+       _label, time_zone = (time_zone_rule || "").split("=")
+       time_zone
+    end
+
+    def parse_time(time_string)
+      time_zone = parse_timezone(time_string)
+      Montrose::Utils.parse_time(time_string).in_time_zone(time_zone)
+    end
+
+    def parse_exdate(exdate)
+      return [] unless exdate.present?
+
+      @except = Montrose::Utils.as_date(exdate) # only currently supports dates
+
+      [:except, @except]
+    end
+
+    def parse_rrule(rrule)
+      rrule.gsub(/\s+/, "").split(";").flat_map do |rule|
+        prop, value = rule.split("=")
+        case prop
+        when "FREQ"
+          [:every, Montrose::Frequency.from_term(value)]
+        when "INTERVAL"
+          [:interval, value.to_i]
+        when "COUNT"
+          [:total, value.to_i]
+        when "UNTIL"
+          [:until, parse_time(value)]
+        when "BYMINUTE"
+          [:minute, Montrose::Minute.parse(value)]
+        when "BYHOUR"
+          [:hour, Montrose::Hour.parse(value)]
+        when "BYMONTH"
+          [:month, Montrose::Month.parse(value)]
+        when "BYDAY"
+          [:day, Montrose::Day.parse(value)]
+        when "BYMONTHDAY"
+          [:mday, Montrose::MonthDay.parse(value)]
+        when "BYYEARDAY"
+          [:yday, Montrose::YearDay.parse(value)]
+        when "BYWEEKNO"
+          [:week, Montrose::Week.parse(value)]
+        when "WKST"
+          [:week_start, value]
+        when "BYSETPOS"
+          warn "BYSETPOS not currently supported!"
+        else
+          raise "Unrecognized rrule '#{rule}'"
+        end
+      end
+    end
+  end
+end

data/lib/montrose/minute.rb

@@ -0,0 +1,22 @@
+module Montrose
+  class Minute
+    MINUTES_IN_HOUR = 0.upto(59).to_a.freeze
+
+    class << self
+      def parse(arg)
+        case arg
+        when String
+          parse(arg.split(","))
+        else
+          Array(arg).map { |m| assert(m.to_i) }.presence
+        end
+      end
+
+      def assert(minute)
+        raise ConfigurationError, "Out of range: #{MINUTES_IN_HOUR.inspect} does not include #{minute}" unless MINUTES_IN_HOUR.include?(minute)
+
+        minute
+      end
+    end
+  end
+end

data/lib/montrose/month.rb

@@ -0,0 +1,47 @@
+module Montrose
+  class Month
+    extend Montrose::Utils
+
+    NAMES = ::Date::MONTHNAMES # starts with nil to match 1-12 numbering
+    NUMBERS = NAMES.map.with_index { |_n, i| i.to_s }.slice(1, 12)
+
+    class << self
+      def parse(value)
+        case value
+        when String
+          parse(value.split(",").compact)
+        when Array
+          value.map { |m|
+            Montrose::Month.number!(m)
+          }.presence
+        else
+          parse(Array(value))
+        end
+      end
+
+      def names
+        NAMES
+      end
+
+      def numbers
+        NUMBERS
+      end
+
+      def number(name)
+        case name
+        when Symbol, String
+          string = name.to_s
+          NAMES.index(string.titleize) || number(to_index(string))
+        when 1..12
+          name
+        end
+      end
+
+      def number!(name)
+        numbers = NAMES.map.with_index { |_n, i| i.to_s }.slice(1, 12)
+        number(name) || raise(ConfigurationError,
+          "Did not recognize month #{name}, must be one of #{(NAMES + numbers).inspect}")
+      end
+    end
+  end
+end

data/lib/montrose/month_day.rb

@@ -0,0 +1,25 @@
+module Montrose
+  class MonthDay
+    class << self
+      MDAYS = (-31.upto(-1).to_a + 1.upto(31).to_a)
+
+      def parse(mdays)
+        return nil unless mdays.present?
+
+        case mdays
+        when String
+          parse(mdays.split(","))
+        else
+          Array(mdays).map { |d| assert(d.to_i) }
+        end
+      end
+
+      def assert(number)
+        test = number.abs
+        raise ConfigurationError, "Out of range: #{MDAYS.inspect} does not include #{test}" unless MDAYS.include?(number.abs)
+
+        number
+      end
+    end
+  end
+end