periodoxical 0.7.2 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01bdfec5ba5930f743cc1c4197e0964631c8dde5be1bb14c79082fe363bf72e1
-  data.tar.gz: 6aaaf40f368acbdd78632455889298e6eb6ced8c0ee80f4ed9e96387e7d05536
+  metadata.gz: 78125f7c8e33a8588c933d7b0438daa5d0913394fe9c141e752dd73fc1968d88
+  data.tar.gz: 60acbba0684d36991ac7bffcb21dc8a97e27bfb313d1ab9641668463e73c718c
 SHA512:
-  metadata.gz: dc697912db1f3a5439ffd3cdf3371c4be7f4475bb2bbae1f01c2ac42887d6041c45763e1977eabf8f68e5f6ee7c7c0d728e80153796acd419d9741a7a3126d5f
-  data.tar.gz: 7a0c713a31ccca86c48b08bdcf1908056475a589c7adc0b93ed94dd13af0ebd35fe58151340fe2e88ff3da13d653673064c9c1d3500e9dbe61845528ecdbb207
+  metadata.gz: df7a8cc7abe1139af195aebe455feb7c66b75e27e3a8d43e4c862ec362111756a461b7293efe3c3fdcca50eb1f70d5fdb5de04e740014a4fc33fe3f324e8d6ec
+  data.tar.gz: '070876a087c2712b12f497054966f9cd98ac3d0e3eab1e4337e165e2ea42cef5ea4dd5b43b714393d92d14ddab2119b426128cf9d85f5de845b9e32959f72b1d'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    periodoxical (0.6.2)
+    periodoxical (0.8.3)
       tzinfo (~> 2.0, >= 2.0.0)
       week_of_month (= 1.2.6)
 

data/README.md

@@ -186,7 +186,7 @@ Periodoxical.generate(
 
 ### Example 5 - when specifying time blocks using day-of-month and/or week-of-month and/or month.
 
-As a Ruby dev, I want to generate the next 3 slots for **8AM - 9AM** for the **5th** and **10th** day of every month starting from **June**
+As a Ruby dev, I want to generate the next 3 timeblocks for **8AM - 9AM** for the **5th** and **10th** day of every month starting from **June**
 
 ```rb
 Periodoxical.generate(
@@ -215,7 +215,7 @@ Periodoxical.generate(
 ]
 ```
 
-As a Ruby dev, I want to generate **4** slots for **8AM - 9AM** on **Mondays** but only in the **first two weeks** in the months of **April, May, and June**
+As a Ruby dev, I want to generate **4** timeblocks for **8AM - 9AM** on **Mondays** but only in the **first two weeks** in the months of **April, May, and June**
 
 ```
 Periodoxical.generate(
@@ -251,7 +251,7 @@ Periodoxical.generate(
 ```
 
 ### Example 6 - Specify nth day-of-week in month (ie. first Monday of the Month, second Tuesday of the Month, last Friday of Month)
-As a Ruby dev, I want to generate slots for **8AM - 9AM** on the **first and second Mondays**  and **last Fridays** of every month starting in June 2024.  I can do this with the `nth_day_of_week_in_month` param.
+As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on the **first and second Mondays**  and **last Fridays** of every month starting in June 2024.  I can do this with the `nth_day_of_week_in_month` param.
 
 ```rb
 Periodoxical.generate(
@@ -292,7 +292,7 @@ Periodoxical.generate(
 ```
 
 ### Example 7 - Exclude time blocks using the `exclusion_dates` parameter
-As a Ruby dev, I want to generate slots for **8AM - 9AM** on **Mondays**, except for the **Monday of June 10, 2024**.
+As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on **Mondays**, except for the **Monday of June 10, 2024**.
 
 ```rb
 Periodoxical.generate(
@@ -328,6 +328,69 @@ Periodoxical.generate(
 ]
 ```
 
+### Example 8 - Every-other-nth day-of-week rules (ie. every other Tuesday, every 3rd Wednesday, every 10th Friday)
+
+As a Ruby dev, I want to generate timeblocks for **9AM- 10AM** on **every Monday**, but **every other Tuesday**, and **every other 3rd Wednesday**. I can do this using the `days_of_week` parameter, but also using the `every` and `every_other_nth` keys to specify the every-other-nth-rules.
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  start_date: '2024-12-30',
+  days_of_week: {
+    mon: { every: true }, # every Monday (no skipping)
+    tue: { every_other_nth: 2 }, # every other Tuesday starting at first Tuesday from start date
+    wed: { every_other_nth: 3 }, # every 3rd Wednesday starting at first Wednesday from start date
+  },
+  limit: 10,
+  time_blocks: [
+    { start_time: '9:00AM', end_time: '10:00AM' },
+  ],
+)
+#=> 
+[
+    {
+       start: #<DateTime: 2024-12-30T09:00:00-0800>,
+       end: #<DateTime: 2024-12-30T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2024-12-31T09:00:00-0800>,
+       end: #<DateTime: 2024-12-31T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-01T09:00:00-0800>,
+       end: #<DateTime: 2025-01-01T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-06T09:00:00-0800>,
+       end: #<DateTime: 2025-01-06T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-13T09:00:00-0800>,
+       end: #<DateTime: 2025-01-13T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-14T09:00:00-0800>,
+       end: #<DateTime: 2025-01-14T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-20T09:00:00-0800>,
+       end: #<DateTime: 2025-01-20T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-22T09:00:00-0800>,
+       end: #<DateTime: 2025-01-22T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-27T09:00:00-0800>,
+       end: #<DateTime: 2025-01-27T10:00:00-0800>,
+    },
+    {
+       start: #<DateTime: 2025-01-28T09:00:00-0800>,
+       end: #<DateTime: 2025-01-28T10:00:00-0800>,
+    }
+]
+```
+
 ### Having Some Fun
 
 Generate all the Friday the 13ths ever since May 1980 (when the first Friday the 13th film was released).

data/lib/periodoxical/validation.rb

@@ -0,0 +1,104 @@
+module Periodoxical
+  module Validation
+    VALID_DAYS_OF_WEEK = %w[mon tue wed thu fri sat sun].freeze
+    def validate!
+      unless @day_of_week_time_blocks || @time_blocks
+        raise "`day_of_week_time_blocks` or `time_blocks` need to be provided"
+      end
+
+      if (@days_of_week || @days_of_week_with_alternations) && @day_of_week_time_blocks
+        raise "`days_of_week` and `day_of_week_time_blocks` are both provided, which leads to ambiguity.  Please use only one of these parameters."
+      end
+
+      if @weeks_of_month
+        @weeks_of_month.each do |wom|
+          unless wom.is_a?(Integer) && wom.between?(1, 5)
+            raise "weeks_of_month must be an array of integers between 1 and 5"
+          end
+        end
+      end
+
+      # days of week are valid
+      if @days_of_week
+        @days_of_week.each do |day|
+          unless VALID_DAYS_OF_WEEK.include?(day.to_s)
+            raise "#{day} is not valid day of week format.  Must be: #{VALID_DAYS_OF_WEEK}"
+          end
+        end
+      end
+
+      if @days_of_week_with_alternations
+        @days_of_week_with_alternations.each do |dow, every_other|
+          unless VALID_DAYS_OF_WEEK.include?(dow.to_s)
+            raise "#{dow} is not valid day of week format.  Must be: #{VALID_DAYS_OF_WEEK}"
+          end
+          unless every_other.is_a?(Hash)
+            raise "days_of_week parameter is not used correctly.  Please look at examples in README."
+          end
+          unless every_other[:every] || every_other[:every_other_nth]
+            raise "days_of_week parameter is not used correctly.  Please look at examples in README."
+          end
+          if every_other[:every_other_nth]
+            unless every_other[:every_other_nth].is_a?(Integer)
+              raise "days_of_week parameter is not used correctly.  Please look at examples in README."
+            end
+
+            unless every_other[:every_other_nth] > 1
+              raise "days_of_week parameter is not used correctly.  Please look at examples in README."
+            end
+          end
+        end
+      end
+
+      if @nth_day_of_week_in_month
+        @nth_day_of_week_in_month.keys.each do |day|
+          unless VALID_DAYS_OF_WEEK.include?(day.to_s)
+            raise "#{day} is not valid day of week format.  Must be: #{VALID_DAYS_OF_WEEK}"
+          end
+        end
+          @nth_day_of_week_in_month.each do |k,v|
+            unless v.is_a?(Array)
+              raise "nth_day_of_week_in_month parameter is invalid.  Please look at the README for examples."
+            end
+            v.each do |num|
+              unless [-1,1,2,3,4,5].include?(num)
+                raise "nth_day_of_week_in_month parameter is invalid. Please look at the README for examples. "
+              end
+            end
+          end
+      end
+
+      if @nth_day_of_week_in_month && (@days_of_week || @days_of_week_with_alternations || @day_of_week_time_blocks)
+        raise "nth_day_of_week_in_month parameter cannot be used in combination with `days_of_week` or `day_of_week_time_blocks`.  Please look at the README for examples."
+      end
+
+      if @day_of_week_time_blocks
+        @day_of_week_time_blocks.keys.each do |d|
+          unless VALID_DAYS_OF_WEEK.include?(d.to_s)
+            raise "#{d} is not a valid day of week format. Must be #{VALID_DAYS_OF_WEEK}"
+          end
+        end
+      end
+
+      if @days_of_month
+        @days_of_month.each do |dom|
+          unless dom.is_a?(Integer) && dom.between?(1,31)
+            raise 'days_of_months must be array of integers between 1 and 31'
+          end
+        end
+      end
+
+      if @months
+        @months.each do |mon|
+          unless mon.is_a?(Integer) && mon.between?(1, 12)
+            raise 'months must be array of integers between 1 and 12'
+          end
+        end
+      end
+
+      unless( @limit || @end_date)
+        raise "Either `limit` or `end_date` must be provided"
+      end
+    end
+  end
+end

data/lib/periodoxical/version.rb

@@ -1,3 +1,3 @@
 module Periodoxical
-  VERSION = "0.7.2"
+  VERSION = "0.8.3"
 end

data/lib/periodoxical.rb

@@ -1,4 +1,5 @@
 require "periodoxical/version"
+require "periodoxical/validation"
 require "date"
 require "time"
 require "tzinfo"
@@ -12,7 +13,7 @@ module Periodoxical
   end
 
   class Core
-    VALID_DAYS_OF_WEEK = %w[mon tue wed thu fri sat sun].freeze
+    include Periodoxical::Validation
     # @param [String] time_zone
     #   Ex: 'America/Los_Angeles', 'America/Chicago',
     #   TZInfo::DataTimezone#name from the tzinfo gem (https://github.com/tzinfo/tzinfo)
@@ -66,7 +67,11 @@ module Periodoxical
     )
 
       @time_zone = TZInfo::Timezone.get(time_zone)
-      @days_of_week = days_of_week
+      if days_of_week.is_a?(Array)
+        @days_of_week = days_of_week
+      elsif days_of_week.is_a?(Hash)
+        @days_of_week_with_alternations = days_of_week
+      end
       @nth_day_of_week_in_month = nth_day_of_week_in_month
       @days_of_month = days_of_month
       @weeks_of_month = weeks_of_month
@@ -87,7 +92,11 @@ module Periodoxical
     #     {
     #       start: #<DateTime>,
     #       end: #<DateTime>,
-    #     }
+    #     },
+    #     {
+    #       start: #<DateTime>,
+    #       end: #<DateTime>,
+    #     },
     #   ]
     def generate
       initialize_looping_variables!
@@ -102,87 +111,6 @@ module Periodoxical
 
     private
 
-    def validate!
-      unless @day_of_week_time_blocks || @time_blocks
-        raise "`day_of_week_time_blocks` or `time_blocks` need to be provided"
-      end
-
-      if @days_of_week && @day_of_week_time_blocks
-        raise "`days_of_week` and `day_of_week_time_blocks` are both provided, which leads to ambiguity.  Please use only one of these parameters."
-      end
-
-      if @weeks_of_month
-        @weeks_of_month.each do |wom|
-          unless wom.is_a?(Integer) && wom.between?(1, 5)
-            raise "weeks_of_month must be an array of integers between 1 and 5"
-          end
-        end
-      end
-
-      # days of week are valid
-      if @days_of_week
-        @days_of_week.each do |day|
-          unless VALID_DAYS_OF_WEEK.include?(day.to_s)
-            raise "#{day} is not valid day of week format.  Must be: #{VALID_DAYS_OF_WEEK}"
-          end
-        end
-      end
-
-      if @nth_day_of_week_in_month
-        @nth_day_of_week_in_month.keys.each do |day|
-          unless VALID_DAYS_OF_WEEK.include?(day.to_s)
-            raise "#{day} is not valid day of week format.  Must be: #{VALID_DAYS_OF_WEEK}"
-          end
-        end
-          @nth_day_of_week_in_month.each do |k,v|
-            unless v.is_a?(Array)
-              raise "nth_day_of_week_in_month parameter is invalid.  Please look at the README for examples."
-            end
-            v.each do |num|
-              unless [-1,1,2,3,4,5].include?(num)
-                raise "nth_day_of_week_in_month parameter is invalid. Please look at the README for examples. "
-              end
-            end
-          end
-      end
-
-      if @days_of_week && @nth_day_of_week_in_month
-        # If both `days_of_week` and `nth_day_of_week_in_month` are provided for the same days-of-the-week, then it is ambiguous.  (ie. I want this timeslot for every Monday, but also only for the first Mondays, well which one is it?)
-        overlapping_days = @days_of_week & @nth_day_of_week_in_month.keys.map(&:to_s)
-        unless overlapping_days.empty?
-          raise "#{overlapping_days} is specified in both `days_of_week` and also `nth_day_of_week_in_month`, which leads to ambiguity.  Pleasee look at the README for examples."
-        end
-      end
-
-      if @day_of_week_time_blocks
-        @day_of_week_time_blocks.keys.each do |d|
-          unless VALID_DAYS_OF_WEEK.include?(d.to_s)
-            raise "#{d} is not a valid day of week format. Must be #{VALID_DAYS_OF_WEEK}"
-          end
-        end
-      end
-
-      if @days_of_month
-        @days_of_month.each do |dom|
-          unless dom.is_a?(Integer) && dom.between?(1,31)
-            raise 'days_of_months must be array of integers between 1 and 31'
-          end
-        end
-      end
-
-      if @months
-        @months.each do |mon|
-          unless mon.is_a?(Integer) && mon.between?(1, 12)
-            raise 'months must be array of integers between 1 and 12'
-          end
-        end
-      end
-
-      unless( @limit || @end_date)
-        raise "Either `limit` or `end_date` must be provided"
-      end
-    end
-
     def day_of_week_long_to_short(dow)
       {
         "Monday" => "mon",
@@ -228,8 +156,24 @@ module Periodoxical
     def initialize_looping_variables!
       @output = []
       @current_date = @start_date
+      @current_day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
       @current_count = 0
       @keep_generating = true
+      # When there are alternations in days of week
+      # (ie. every other Monday, every 3rd Thursday, etc).
+      # We keep running tally of day_of_week counts and use modulo-math to pick out
+      # every n-th one.
+      if @days_of_week_with_alternations
+        @days_of_week_running_tally = {
+          mon: 0,
+          tue: 0,
+          wed: 0,
+          thu: 0,
+          fri: 0,
+          sat: 0,
+          sun: 0,
+        }
+      end
     end
 
     # @param [Hash] time_block
@@ -256,9 +200,19 @@ module Periodoxical
     def advance_current_date_and_check_if_reached_end_date
       @current_date = @current_date + 1
 
+      @current_day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
+
       if @end_date && (@current_date > @end_date)
         @keep_generating = false
       end
+
+      # kill switch to stop infinite loop when `limit` is used but
+      # there is bug, or poorly specified rules.  If @current_date goes into
+      # 1000 years in the future, but still no dates have been generated yet, this is
+      # most likely an infinite loop situation, and needs to be killed.
+      if @limit && ((@current_date - @start_date).to_i > 365000) && @output.empty?
+        raise "No end condition detected, causing infinite loop.  Please check rules/conditions or raise github issue for potential bug fixed"
+      end
     end
 
     # @return [Boolean]
@@ -286,17 +240,36 @@ module Periodoxical
         return false unless @days_of_month.include?(@current_date.day)
       end
 
-      # The following conditions depend on the day-of-week of current_date.
-      day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
-
       # If days of week are specified, but current_date does not satisfy it,
       # return false
       if @days_of_week
-        return false unless @days_of_week.include?(day_of_week)
+        return false unless @days_of_week.include?(@current_day_of_week)
+      end
+
+      if @days_of_week_with_alternations
+        # current_date is not specified in days_of_week, so skip it
+        return false if @days_of_week_with_alternations[@current_day_of_week.to_sym].nil?
+
+        alternating_spec = @days_of_week_with_alternations[@current_day_of_week.to_sym]
+
+        # In the { every: true } case, we don't check the alternations logic, we just add it.
+        unless alternating_spec[:every]
+          # We are now specifying every other nth occurrence (ie. every 2nd Tuesday, every 3rd Wednesday)
+          alternating_frequency = alternating_spec[:every_other_nth]
+
+          unless (@days_of_week_running_tally[@current_day_of_week.to_sym] % alternating_frequency) == 0
+            # If day-of-week alternations are present, we need to keep track of day-of-weeks
+            # we have encountered and added or would have added so far.
+            update_days_of_week_running_tally!
+
+            return false
+          end
+          update_days_of_week_running_tally!
+        end
       end
 
       if @day_of_week_time_blocks
-        dowtb = @day_of_week_time_blocks[day_of_week.to_sym]
+        dowtb = @day_of_week_time_blocks[@current_day_of_week.to_sym]
         return false if dowtb.nil?
         return false if dowtb.empty?
       end
@@ -304,41 +277,42 @@ module Periodoxical
       if @nth_day_of_week_in_month
         # If the day of week is specified in nth_day_of_week_in_month,
         # we need to investigate it whether or not to exclude it.
-        if @nth_day_of_week_in_month[day_of_week.to_sym]
+        if @nth_day_of_week_in_month[@current_day_of_week.to_sym]
           n_occurence_of_day_of_week_in_month = ((@current_date.day - 1) / 7) + 1
           # -1 is a special case and requires extra-math
-          if @nth_day_of_week_in_month[day_of_week.to_sym].include?(-1)
+          if @nth_day_of_week_in_month[@current_day_of_week.to_sym].include?(-1)
             # We basically want to convert the -1 into its 'positive-equivalent` in this month, and compare it with that.
             # For example, in June 2024, the Last Friday is also the 4th Friday.  So in that case, we convert the -1 into a 4.
-            positivized_indices = @nth_day_of_week_in_month[day_of_week.to_sym].map { |indx| positivize_index(indx, day_of_week) }
+            positivized_indices = @nth_day_of_week_in_month[@current_day_of_week.to_sym].map { |indx| positivize_index(indx, @current_day_of_week) }
             return positivized_indices.include?(n_occurence_of_day_of_week_in_month)
           else
-            return @nth_day_of_week_in_month[day_of_week.to_sym].include?(n_occurence_of_day_of_week_in_month)
+            return @nth_day_of_week_in_month[@current_day_of_week.to_sym].include?(n_occurence_of_day_of_week_in_month)
           end
         else
-          # if day-of-week was not specified in nth_day_of_week_in_month,
-          # it could have been specified in either `days_of_week` or `day_of_week_time_blocks and we unfortunately need to re-check those here. I cant think of a way to further DRY-it up.
-          return false unless @days_of_week && @day_of_week_time_blocks
-          if @day_of_week
-            return false unless @days_of_week.include?(day_of_week)
-          end
-
-          if @day_of_week_time_blocks
-            dowtb = @day_of_week_time_blocks[day_of_week.to_sym]
-            return false if dowtb.nil?
-            return false if dowtb.empty?
-          end
+          return false
         end
       end
 
-      # Otherwise, return true
+      # The default return true is really only needed to support this use-case:
+      # Periodoxical.generate(
+      #   time_zone: 'America/Los_Angeles',
+      #   time_blocks: [
+      #     {
+      #       start_time: '9:00AM',
+      #       end_time: '10:30AM'
+      #     },
+      #   ],
+      #   start_date: '2024-05-23',
+      #   end_date: '2024-05-27',
+      # )
+      # where if we don't specify any date-of-week/month constraints, we return all consecutive dates.
+      # In the future, if we don't support this case, we can use `false` as the return value.
       true
     end
 
     def add_time_blocks_from_current_date!
       if @day_of_week_time_blocks
-        day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
-        time_blocks = @day_of_week_time_blocks[day_of_week.to_sym]
+        time_blocks = @day_of_week_time_blocks[@current_day_of_week.to_sym]
         catch :done do
           time_blocks.each do |tb|
             append_to_output_and_check_limit(tb)
@@ -372,5 +346,9 @@ module Periodoxical
 
       ((last_date.day - 1) / 7) + 1
     end
+
+    def update_days_of_week_running_tally!
+      @days_of_week_running_tally[@current_day_of_week.to_sym] = @days_of_week_running_tally[@current_day_of_week.to_sym] + 1
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.3
 platform: ruby
 authors:
 - Steven Li
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-02 00:00:00.000000000 Z
+date: 2024-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -135,6 +135,7 @@ files:
 - bin/console
 - bin/setup
 - lib/periodoxical.rb
+- lib/periodoxical/validation.rb
 - lib/periodoxical/version.rb
 - periodoxical.gemspec
 homepage: https://github.com/StevenJL/periodoxical