periodoxical 0.5.2 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa1a430d11ca7fdd0cea524011b7164f926f87bad37a49c4848bdbca934bdc79
-  data.tar.gz: fea338a55f3b095b4ac6c1ff57f235e8490a9b6683ae48b9a573b0b1afba22f0
+  metadata.gz: 01bdfec5ba5930f743cc1c4197e0964631c8dde5be1bb14c79082fe363bf72e1
+  data.tar.gz: 6aaaf40f368acbdd78632455889298e6eb6ced8c0ee80f4ed9e96387e7d05536
 SHA512:
-  metadata.gz: 74ec882770d5567ad292ad26c020777d9075cbb0bf77259f37fa0713ab239772dea1dd52fadb2d415ceb8820a10cbc2572ee4847ac181ae208d81d6d759b0517
-  data.tar.gz: e2a7c7b00eec3522ce4d2bd15a999a7f86de8826245c464f0e0844b3f7cd42d7eb942d80e7cad2ecbc48d66399f4962fd9f7be7d8a9d4a025e51d79b477112e2
+  metadata.gz: dc697912db1f3a5439ffd3cdf3371c4be7f4475bb2bbae1f01c2ac42887d6041c45763e1977eabf8f68e5f6ee7c7c0d728e80153796acd419d9741a7a3126d5f
+  data.tar.gz: 7a0c713a31ccca86c48b08bdcf1908056475a589c7adc0b93ed94dd13af0ebd35fe58151340fe2e88ff3da13d653673064c9c1d3500e9dbe61845528ecdbb207

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    periodoxical (0.5.2)
+    periodoxical (0.6.2)
       tzinfo (~> 2.0, >= 2.0.0)
+      week_of_month (= 1.2.6)
 
 GEM
   remote: https://rubygems.org/
@@ -40,6 +41,7 @@ GEM
     rspec-support (3.13.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
+    week_of_month (1.2.6)
 
 PLATFORMS
   arm64-darwin-22

data/README.md

@@ -29,8 +29,44 @@ Or install it yourself as:
 
 ## Usage
 
-#### Example 1
-As a Ruby dev, I want to generate all the datetimes blocks of **9:00AM - 10:30AM** and **2:00PM - 2:30PM**, on **Mondays**, **Wednesdays**, and **Thursdays**, between the dates of **May 23, 2024** and **June 12, 2024**, inclusive. This can be represented visually as:
+### Example 1
+As a Ruby dev, I want to generate all the datetime blocks of **9:00AM - 10:30AM** for all days from **May 23, 2024** to **May 26, 2024** inclusive.
+
+```rb
+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',
+)
+#=> 
+[
+    {
+     start_time: #<DateTime: 2024-05-23T09:00:00-0700>,
+     end_time: #<DateTime: 2024-05-23T10:30:00-0700>,
+    },
+    {
+     start_time: #<DateTime: 2024-05-24T09:00:00-0700>,
+     end_time: #<DateTime: 2024-05-24T10:30:00-0700>,
+    },
+    {
+     start_time: #<DateTime: 2024-05-25T09:00:00-0700>,
+     end_time: #<DateTime: 2024-05-25T10:30:00-0700>,
+    },
+    {
+     start_time: #<DateTime: 2024-05-26T09:00:00-0700>,
+     end_time: #<DateTime: 2024-05-26T10:30:00-0700>,
+    }
+]
+```
+
+### Example 2 - specify days of the week
+As a Ruby dev, I want to generate all the datetime blocks of **9:00AM - 10:30AM** and **2:00PM - 2:30PM**, on **Mondays**, **Wednesdays**, and **Thursdays**, between the dates of **May 23, 2024** and **June 12, 2024**, inclusive. This can be represented visually as:
 
 <div align="center">
   <img width="558" alt="calendar_image_1" src="https://github.com/StevenJL/periodoxical/assets/2191808/e92fc6ff-03fd-44ed-a955-d3a0dd0f5d0a">
@@ -79,9 +115,9 @@ Periodoxical.generate(
 ]
 ```
 
-#### Example 2 - using the `limit` key.
+### Example 3 - using the `limit` key.
 
-As a ruby dev, I want to generate the next 3 datetime blocks of **9:00AM - 10:30AM** and **2:00PM - 2:30PM** on **Sundays**, after **May 23, 2024** using the `limit` key.
+As a ruby dev, I want to generate the next **3** datetime blocks of **9:00AM - 10:30AM** and **2:00PM - 2:30PM** on **Sundays**, after **May 23, 2024** using the `limit` key.
 
 ```rb
 Periodoxical.generate(
@@ -117,7 +153,7 @@ Periodoxical.generate(
 ]
 ```
 
-#### Example 3 - when time blocks vary between days
+### Example 4 - when time blocks vary between days
 
 As a ruby dev, I want to generate all the timeblocks between **May 23, 2024** and **June 12, 2024** where the time should be **8AM-9AM** on **Mondays**, but **10:45AM-12:00PM** and **2:00PM-4:00PM** on **Wednesdays**, and **2:30PM-4:15PM** on **Thursdays**.
 
@@ -148,8 +184,115 @@ Periodoxical.generate(
 )
 ```
 
-#### Example 4 - 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.
+### 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**
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  start_date: '2024-06-1',
+  limit: 3,
+  days_of_month: [5, 10],
+  time_blocks: [
+    { start_time: '8:00AM', end_time: '9:00AM' },
+  ],
+)
+#=>
+[
+    {
+      start: #<DateTime: 2024-06-05T08:00:00-0700>,
+      end: #<DateTime: 2024-06-05T09:00:00-0700>,
+    },
+    {
+      start: #<DateTime: 2024-06-10T08:00:00-0700>,
+      end: #<DateTime: 2024-06-10T09:00:00-0700>,
+    },
+    {
+      start: #<DateTime: 2024-07-05T08:00:00-0700>,
+      end: #<DateTime: 2024-07-05T09:00:00-0700>,
+    },
+]
+```
+
+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**
+
+```
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  start_date: '2024-04-1',
+  limit: 4,
+  weeks_of_month: [1 2],
+  months: [4, 5, 6],
+  days_of_week: %w(mon),
+  time_blocks: [
+    { start_time: '8:00AM', end_time: '9:00AM' },
+  ],
+)
+#=> 
+[
+    {
+     start_time: #<DateTime: 2024-04-01T08:00:00-0700>,
+     end_time: #<DateTime: 2024-04-01T09:00:00-0700>,
+    },
+    {
+     start_time: #<DateTime: 2024-04-08T08:00:00-0700>,
+     end_time: #<DateTime: 2024-04-08T09:00:00-0700>,
+    },
+    {
+     start_time: #<DateTime: 2024-05-06T08:00:00-0700>,
+     end_time: #<DateTime: 2024-05-06T09:00:00-0700>,
+    },
+    {
+     start_time: #<DateTime: 2024-06-03T08:00:00-0700>,
+     end_time: #<DateTime: 2024-06-03T09:00:00-0700>,
+    },
+]
+```
+
+### 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.
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  start_date: '2024-06-01',
+  limit: 5,
+  nth_day_of_week_in_month: {
+    mon: [1, 2], # valid values: -1,1,2,3,4,5
+    fri: [-1], # Use -1 to specify "last" of the month.
+  },
+  time_blocks: [
+    { start_time: '8:00AM', end_time: '9:00AM' },
+  ],
+)
+# =>
+[
+  {
+    start: #<DateTime: 2024-06-03T08:00:00-0700>, # First Monday of June 2024
+    end: #<DateTime: 2024-06-03T09:00:00-0700>,
+  },
+  {
+    start: #<DateTime: 2024-06-10T08:00:00-0700>, # second Monday of June 2024
+    end: #<DateTime: 2024-06-10T09:00:00-0700>,
+  },
+  {
+    start: #<DateTime: 2024-06-28 08:00:00 -0700>, # last Friday of June 2024
+    end: #<DateTime: 2024-06-28 09:00:00 -0700>,
+  },
+  {
+    start: #<DateTime: 2024-07-01 08:00:00 -0700>, # First Monday of July 2024
+    end: #<DateTime: 2024-07-01 09:00:00 -0700>,
+  },
+  {
+    start: #<DateTime: 2024-07-08 08:00:00 -0700>, # Second Monday of July 2024
+    end: #<DateTime: 2024-07-08 09:00:00 -0700>,
+  },
+]
+```
+
+### 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**.
 
 ```rb
 Periodoxical.generate(
@@ -163,24 +306,101 @@ Periodoxical.generate(
     ],
   }
 )
-# Returns all Monday 8AM - 9AM blocks except for the june on June 10, 2024
+# Returns all Monday 8AM - 9AM blocks except for the Monday on June 10, 2024
 # => 
 [
     {
-      start: <#DateTime: 2024-06-03T08:00:00-0700>,
-      end: <#DateTime: 2024-06-03T09:00:00-0700>,
+      start: #<DateTime: 2024-06-03T08:00:00-0700>,
+      end: #<DateTime: 2024-06-03T09:00:00-0700>,
+    }
+    {
+      start: #<DateTime: 2024-06-17T08:00:00-0700>,
+      end: #<DateTime: 2024-06-17T09:00:00-0700>,
     }
     {
-      start: <#DateTime: 2024-06-17T08:00:00-0700>,
-      end: <#DateTime: 2024-06-17T09:00:00-0700>,
+      start: #<DateTime: 2024-06-24T08:00:00-0700>,
+      end: #<DateTime: 2024-06-24T09:00:00-0700>,
     }
     {
-      start: <#DateTime: 2024-06-24T08:00:00-0700>,
-      end: <#DateTime: 2024-06-24T09:00:00-0700>,
+      start: #<DateTime: 2024-07-01T08:00:00-0700>,
+      end: #<DateTime: 2024-07-01T09:00:00-0700>,
     }
+]
+```
+
+### Having Some Fun
+
+Generate all the Friday the 13ths ever since May 1980 (when the first Friday the 13th film was released).
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  start_date: '1980-05-01',
+  days_of_week: %w(fri),
+  days_of_month: [13],
+  limit: 100,
+  time_blocks: [
+    { start_time: '11:00PM', end_time: '12:00AM' },
+  ],
+)
+# =>
+[
+    {
+      start: #<DateTime: 1980-06-13T23:00:00-0700>,
+      end: #<DateTime: 1980-06-13T00:00:00-0700>,
+    },
+    {
+      start: #<DateTime: 1981-02-13T23:00:00-0800>,
+      end: #<DateTime: 1981-02-13T00:00:00-0800>,
+    },
+    {
+      start: #<DateTime: 1981-03-13T23:00:00-0800>,
+      end: #<DateTime: 1981-03-13T00:00:00-0800>,
+    },
+    {
+      start: #<DateTime: 1981-11-13T23:00:00-0800>,
+      end: #<DateTime: 1981-11-13T00:00:00-0800>,
+    }
+    ...
+]
+```
+
+Generate the next 10 Thanksgivings from now on (Thanksgivings is defined as the 4th Thursday in November).
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  start_date: '2024-05-01',
+  months: [11],
+  nth_day_of_week_in_month: {
+    thu: [4],
+  },
+  limit: 10,
+  time_blocks: [
+    { start_time: '5:00PM', end_time: '6:00PM' },
+  ],
+)
+#=>
+[
+    {
+      start: #<DateTime: 2024-11-28T17:00:00-0800>,
+      end: #<DateTime: 2024-11-28T18:00:00-0800>,
+    },
+    {
+      start: #<DateTime: 2025-11-27T17:00:00-0800>,
+      end: #<DateTime: 2025-11-27T18:00:00-0800>,
+    },
+    {
+      start: #<DateTime: 2026-11-26T17:00:00-0800>,
+      end: #<DateTime: 2026-11-26T18:00:00-0800>,
+    },
+    {
+      start: #<DateTime: 2027-11-25T17:00:00-0800>,
+      end: #<DateTime: 2027-11-25T18:00:00-0800>,
+    },
     {
-      start: <#DateTime: 2024-07-01T08:00:00-0700>,
-      end: <#DateTime: 2024-07-01T09:00:00-0700>,
+      start: #<DateTime: 2028-11-23T17:00:00-0800>,
+      end: #<DateTime: 2028-11-23T18:00:00-0800>,
     }
 ]
 ```

data/lib/periodoxical/version.rb

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

data/lib/periodoxical.rb

@@ -2,6 +2,7 @@ require "periodoxical/version"
 require "date"
 require "time"
 require "tzinfo"
+require "week_of_month"
 
 module Periodoxical
   class << self
@@ -32,22 +33,44 @@ module Periodoxical
     #   Days of the week to generate the times for, if nil, then times are generated
     #   for every day.
     #   Ex: %w(mon tue wed sat)
+    # @param [Array<Integer>, nil] days_of_month
+    #   Days of month to generate times for.
+    #   Ex: %w(5 10) - The 5th and 10th days of every month
+    # @param [Array<Integer>, nil] months
+    #   Months as integers, where 1 = Jan, 12 = Dec
     # @param [Integer] limit
     #   How many date times to generate.  To be used when `end_date` is nil.
     # @param [Aray<String>] exclusion_dates
     #   Dates to be excluded when generating the time blocks
     #   Ex: ['2024-06-10', '2024-06-14']
-    # @param [Hash<Hash>] day_of_week_time_blocks
+    # @param [Hash<Array<Hash>>] day_of_week_time_blocks
     #   To be used when hours are different between days of the week
     #   Ex: {
     #     mon: [{ start_time: '10:15AM', end_time: '11:35AM' }, { start_time: '9:00AM' }, {end_time: '4:30PM'} ],
     #     tue: { start_time: '11:30PM', end_time: '12:00AM' },
     #     fri: { start_time: '7:00PM', end_time: '9:00PM' },
     #   }
-    def initialize(time_zone: 'Etc/UTC', days_of_week: nil,
-                   start_date:, end_date: nil, time_blocks: nil, day_of_week_time_blocks: nil, limit: nil, exclusion_dates: nil)
+    def initialize(
+      start_date:,
+      end_date: nil,
+      time_blocks: nil,
+      day_of_week_time_blocks: nil,
+      limit: nil,
+      exclusion_dates: nil,
+      time_zone: 'Etc/UTC',
+      days_of_week: nil,
+      nth_day_of_week_in_month: nil,
+      days_of_month: nil,
+      weeks_of_month: nil,
+      months: nil
+    )
+
       @time_zone = TZInfo::Timezone.get(time_zone)
       @days_of_week = days_of_week
+      @nth_day_of_week_in_month = nth_day_of_week_in_month
+      @days_of_month = days_of_month
+      @weeks_of_month = weeks_of_month
+      @months = months
       @time_blocks = time_blocks
       @day_of_week_time_blocks = day_of_week_time_blocks
       @start_date = start_date.is_a?(String) ? Date.parse(start_date) : start_date
@@ -67,74 +90,35 @@ module Periodoxical
     #     }
     #   ]
     def generate
-      if @days_of_week && @time_blocks
-        generate_when_same_time_blocks_for_all_days
-      elsif @day_of_week_time_blocks
-        generate_when_different_time_blocks_between_days
+      initialize_looping_variables!
+      while @keep_generating
+        if should_add_time_blocks_from_current_date?
+          add_time_blocks_from_current_date!
+        end
+        advance_current_date_and_check_if_reached_end_date
       end
+      @output
     end
 
     private
 
-    def generate_when_different_time_blocks_between_days
-      times_output = []
-      current_date = @start_date
-      current_count = 0
-      keep_generating = true
-      while keep_generating
-        day_of_week = day_of_week_long_to_short(current_date.strftime("%A"))
-        if @day_of_week_time_blocks[day_of_week.to_sym] && !excluded_date?(current_date)
-          time_blocks = @day_of_week_time_blocks[day_of_week.to_sym]
-          time_blocks.each do |tb|
-            times_output << {
-              start: time_str_to_object(current_date, tb[:start_time]),
-              end: time_str_to_object(current_date, tb[:end_time])
-            }
-            current_count = current_count + 1
-            if @limit && current_count == @limit
-              keep_generating = false
-              break
-            end
-          end
-        end
-        current_date = current_date + 1
-        if @end_date && (current_date > @end_date)
-          keep_generating = false
-        end
+    def validate!
+      unless @day_of_week_time_blocks || @time_blocks
+        raise "`day_of_week_time_blocks` or `time_blocks` need to be provided"
       end
-      times_output
-    end
 
-    def generate_when_same_time_blocks_for_all_days 
-      times_output = []
-      current_date = @start_date
-      current_count = 0
-      keep_generating = true
-      while keep_generating
-        day_of_week = day_of_week_long_to_short(current_date.strftime("%A"))
-        if @days_of_week.include?(day_of_week) && !excluded_date?(current_date)
-          @time_blocks.each do |tb|
-            times_output << {
-              start: time_str_to_object(current_date, tb[:start_time]),
-              end: time_str_to_object(current_date, tb[:end_time])
-            }
-            current_count = current_count + 1
-            if @limit && current_count == @limit
-              keep_generating = false
-              break
-            end
-          end
-        end
-        current_date = current_date + 1
+      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 @end_date && (current_date > @end_date)
-          keep_generating = false
+      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
-      times_output
-    end
 
-    def validate!
       # days of week are valid
       if @days_of_week
         @days_of_week.each do |day|
@@ -144,6 +128,32 @@ module Periodoxical
         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)
@@ -152,8 +162,20 @@ module Periodoxical
         end
       end
 
-      unless (@days_of_week && @time_blocks) || (@day_of_week_time_blocks)
-        raise "Need to provide either `days_of_week` and `time_blocks` or `day_of_week_time_blocks`"
+      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)
@@ -189,17 +211,166 @@ module Periodoxical
       @time_zone.local_to_utc(date_time).new_offset(@time_zone.current_period.offset.utc_total_offset)
     end
 
-    # @param [Date] current_date
+    # @param [Date] date
     # @return [Boolean]
     #   Whether or not the date is excluded
-    def excluded_date?(current_date)
+    def excluded_date?(date)
       return false unless @exclusion_dates
 
       @exclusion_dates.each do |ed|
-        return true if current_date == ed
+        return true if date == ed
       end
 
       false
     end
+
+    # Variables which manage flow of looping through time and generating slots
+    def initialize_looping_variables!
+      @output = []
+      @current_date = @start_date
+      @current_count = 0
+      @keep_generating = true
+    end
+
+    # @param [Hash] time_block
+    #  Ex:
+    #  {
+    #    start_time: "9:00AM",
+    #    start_time: "10:00AM",
+    #  }
+    #  Generates time block but also checks if we should stop generating
+    def append_to_output_and_check_limit(time_block)
+      @output << {
+        start: time_str_to_object(@current_date, time_block[:start_time]),
+        end: time_str_to_object(@current_date, time_block[:end_time])
+      }
+
+      # increment count, if `limit` is used to stop generating
+      @current_count = @current_count + 1
+      if @limit && @current_count == @limit
+        @keep_generating = false
+        throw :done
+      end
+    end
+
+    def advance_current_date_and_check_if_reached_end_date
+      @current_date = @current_date + 1
+
+      if @end_date && (@current_date > @end_date)
+        @keep_generating = false
+      end
+    end
+
+    # @return [Boolean]
+    #   Should time blocks be added based on the current_date?
+    def should_add_time_blocks_from_current_date?
+      # return false if current_date is explicitly excluded
+      if @exclusion_dates
+        return false if @exclusion_dates.include?(@current_date)
+      end
+
+      # If weeks_of_months are specified but not satisified, return false
+      if @weeks_of_month
+        return false unless @weeks_of_month.include?(@current_date.week_of_month)
+      end
+
+      # If months are specified, but current_date does not satisfy months,
+      # return false
+      if @months
+        return false unless @months.include?(@current_date.month)
+      end
+
+      # If days of months are specified, but current_date does not satisfy it,
+      # return false
+      if @days_of_month
+        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)
+      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
+
+      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]
+          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)
+            # 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) }
+            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)
+          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
+        end
+      end
+
+      # Otherwise, return true
+      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]
+        catch :done do
+          time_blocks.each do |tb|
+            append_to_output_and_check_limit(tb)
+          end
+        end
+      elsif @time_blocks
+        catch :done do
+          @time_blocks.each do |tb|
+            append_to_output_and_check_limit(tb)
+          end
+        end
+      end
+    end
+
+    # What is the positive index of the last day-of-week for the given month-year?
+    # For example, the last Friday in June 2024 is also the nth Friday.  What is this n?
+    # @return [Integer]
+    def positivize_index(indx, day_of_week)
+      # If index is already positive, just return it
+      return indx if indx > 0
+
+      # get last_day_of month
+      month = @current_date.month
+      year = @current_date.year
+      last_date = Date.new(year, month, -1)
+
+      # walk backwords until you get to the right day of the week
+      while day_of_week_long_to_short(last_date.strftime("%A")) != day_of_week
+        last_date = last_date - 1
+      end
+
+      ((last_date.day - 1) / 7) + 1
+    end
   end
 end

data/periodoxical.gemspec

@@ -35,6 +35,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency 'tzinfo', '~> 2.0', '>= 2.0.0'
+  spec.add_dependency 'week_of_month', '1.2.6'
 
   spec.add_development_dependency "bundler", "~> 2.4"
   spec.add_development_dependency "rake", "~> 12.3.3"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.7.2
 platform: ruby
 authors:
 - Steven Li
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-01 00:00:00.000000000 Z
+date: 2024-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -30,6 +30,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: week_of_month
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.6
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement