periodoxical 0.7.3 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63ed27b7ac9376b1cd35d505dbcf13c6637e47a8bee5983aa8697a389c2423ee
-  data.tar.gz: df71967f5be8771b0bda25c4b6352f922a82bac39a546f2f66e04247a41ea3cb
+  metadata.gz: 78125f7c8e33a8588c933d7b0438daa5d0913394fe9c141e752dd73fc1968d88
+  data.tar.gz: 60acbba0684d36991ac7bffcb21dc8a97e27bfb313d1ab9641668463e73c718c
 SHA512:
-  metadata.gz: ce019309287e5c8d065e77ce9cdc31348c12d867ba9140a43cfb2da2a086a647dcfd0ef0e1a801c11b41f3794fb0b056d695a7f079ad87e5e77e75bae1646bc2
-  data.tar.gz: f8ae7b9cdc4e395618665f5b625624418bdc8d343fdc4e4dccd7aa8af9672671d2d02230d344193ac016ab1ada3468f3e9089b7fcc3b41a110f974d04c5f1486
+  metadata.gz: df7a8cc7abe1139af195aebe455feb7c66b75e27e3a8d43e4c862ec362111756a461b7293efe3c3fdcca50eb1f70d5fdb5de04e740014a4fc33fe3f324e8d6ec
+  data.tar.gz: '070876a087c2712b12f497054966f9cd98ac3d0e3eab1e4337e165e2ea42cef5ea4dd5b43b714393d92d14ddab2119b426128cf9d85f5de845b9e32959f72b1d'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    periodoxical (0.7.3)
+    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.3"
+  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
@@ -106,83 +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 @nth_day_of_week_in_month && (@days_of_week || @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
-
     def day_of_week_long_to_short(dow)
       {
         "Monday" => "mon",
@@ -231,6 +159,21 @@ module Periodoxical
       @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,6 +199,7 @@ 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)
@@ -302,6 +246,28 @@ module Periodoxical
         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[@current_day_of_week.to_sym]
         return false if dowtb.nil?
@@ -327,7 +293,20 @@ module Periodoxical
         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
 
@@ -367,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.3
+  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