periodoxical 0.6.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c90e3908492b944735cc23b5da95746309133de5b54413495d4ed49e0d2dce3
-  data.tar.gz: 7fa63855a49e2c6feb9955007361aa6d8c9262f847e6fc0fc159c47f95ed1db5
+  metadata.gz: 63ed27b7ac9376b1cd35d505dbcf13c6637e47a8bee5983aa8697a389c2423ee
+  data.tar.gz: df71967f5be8771b0bda25c4b6352f922a82bac39a546f2f66e04247a41ea3cb
 SHA512:
-  metadata.gz: 36ba01fb5173e0fae2dea0eeba563145b373860989891f2640b468ee688b0cdd5d78b7f5b44e7d52f8d137cd80940ebe8e9b75b997dc144d0d159982bd15aa87
-  data.tar.gz: 5e678e7218811a7d5f0e779a2b766e2099742554414ee007078af87b0fc10f196900672c5fe0daa58b978ce1c4e31f9f08bfc21c0573f257f48823c211acdd74
+  metadata.gz: ce019309287e5c8d065e77ce9cdc31348c12d867ba9140a43cfb2da2a086a647dcfd0ef0e1a801c11b41f3794fb0b056d695a7f079ad87e5e77e75bae1646bc2
+  data.tar.gz: f8ae7b9cdc4e395618665f5b625624418bdc8d343fdc4e4dccd7aa8af9672671d2d02230d344193ac016ab1ada3468f3e9089b7fcc3b41a110f974d04c5f1486

data/Gemfile.lock

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

data/README.md

@@ -29,8 +29,8 @@ Or install it yourself as:
 
 ## Usage
 
-#### 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.
+### 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(
@@ -65,7 +65,7 @@ Periodoxical.generate(
 ]
 ```
 
-#### Example 2
+### 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">
@@ -115,9 +115,9 @@ Periodoxical.generate(
 ]
 ```
 
-#### Example 3 - 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(
@@ -153,7 +153,7 @@ Periodoxical.generate(
 ]
 ```
 
-#### Example 4 - 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**.
 
@@ -184,9 +184,9 @@ Periodoxical.generate(
 )
 ```
 
-#### Example 5 - when specifying time blocks occur by day-of-month and/or and/or week-of-month and/or month.
+### 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 slots for **8AM - 9AM** for the **5th** and **10th** day of every month starting from **June**
 
 ```rb
 Periodoxical.generate(
@@ -201,21 +201,21 @@ Periodoxical.generate(
 #=>
 [
     {
-      start: #<DateTime: 2024-06-05 08:00:00 -0700>,
-      end: #<DateTime: 2024-06-05 09:00:00 -0700>,
+      start: #<DateTime: 2024-06-05T08:00:00-0700>,
+      end: #<DateTime: 2024-06-05T09:00:00-0700>,
     },
     {
-      start: #<DateTime: 2024-06-10 08:00:00 -0700>,
-      end: #<DateTime: 2024-06-10 09:00:00 -0700>,
+      start: #<DateTime: 2024-06-10T08:00:00-0700>,
+      end: #<DateTime: 2024-06-10T09:00:00-0700>,
     },
     {
-      start: #<DateTime: 2024-07-05 08:00:00 -0700>,
-      end: #<DateTime: 2024-07-05 09: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, June
+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(
@@ -232,26 +232,67 @@ Periodoxical.generate(
 #=> 
 [
     {
-     start_time: #<DateTime: 2024-04-01 08:00:00 -0700>,
-     end_time: #<DateTime: 2024-04-01 09:00:00 -0700>,
+     start_time: #<DateTime: 2024-04-01T08:00:00-0700>,
+     end_time: #<DateTime: 2024-04-01T09:00:00-0700>,
     },
     {
-     start_time: #<DateTime: 2024-04-08 08:00:00 -0700>,
-     end_time: #<DateTime: 2024-04-08 09: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-06 08:00:00 -0700>,
-     end_time: #<DateTime: 2024-05-06 09: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-03 08:00:00 -0700>,
-     end_time: #<DateTime: 2024-06-03 09:00:00 -0700>,
+     start_time: #<DateTime: 2024-06-03T08:00:00-0700>,
+     end_time: #<DateTime: 2024-06-03T09:00:00-0700>,
     },
 ]
 ```
 
-#### Example 6 - 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 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(
@@ -287,6 +328,83 @@ Periodoxical.generate(
 ]
 ```
 
+### 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: 2028-11-23T17:00:00-0800>,
+      end: #<DateTime: 2028-11-23T18:00:00-0800>,
+    }
+]
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/periodoxical/version.rb

@@ -1,3 +1,3 @@
 module Periodoxical
-  VERSION = "0.6.2"
+  VERSION = "0.7.3"
 end

data/lib/periodoxical.rb

@@ -59,6 +59,7 @@ module Periodoxical
       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
@@ -66,6 +67,7 @@ module Periodoxical
 
       @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
@@ -85,7 +87,11 @@ module Periodoxical
     #     {
     #       start: #<DateTime>,
     #       end: #<DateTime>,
-    #     }
+    #     },
+    #     {
+    #       start: #<DateTime>,
+    #       end: #<DateTime>,
+    #     },
     #   ]
     def generate
       initialize_looping_variables!
@@ -105,6 +111,10 @@ module Periodoxical
         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)
@@ -122,6 +132,28 @@ 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 @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)
@@ -196,6 +228,7 @@ 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
     end
@@ -223,10 +256,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]
@@ -257,25 +299,41 @@ module Periodoxical
       # If days of week are specified, but current_date does not satisfy it,
       # return false
       if @days_of_week
-        day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
-        return false unless @days_of_week.include?(day_of_week)
+        return false unless @days_of_week.include?(@current_day_of_week)
       end
 
       if @day_of_week_time_blocks
-        day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
-        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
 
+      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[@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[@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[@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[@current_day_of_week.to_sym].include?(n_occurence_of_day_of_week_in_month)
+          end
+        else
+          return false
+        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]
+        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)
@@ -289,5 +347,25 @@ module Periodoxical
         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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.3
 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