periodoxical 0.8.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78125f7c8e33a8588c933d7b0438daa5d0913394fe9c141e752dd73fc1968d88
-  data.tar.gz: 60acbba0684d36991ac7bffcb21dc8a97e27bfb313d1ab9641668463e73c718c
+  metadata.gz: 3836bd7c49ec987409e70592d93cb8c021a009ce3587e48a6419c12121af3b1d
+  data.tar.gz: 510bb79570482c8019e911c8900ec15ee5016b59c1d51677d38d53f7c632523f
 SHA512:
-  metadata.gz: df7a8cc7abe1139af195aebe455feb7c66b75e27e3a8d43e4c862ec362111756a461b7293efe3c3fdcca50eb1f70d5fdb5de04e740014a4fc33fe3f324e8d6ec
-  data.tar.gz: '070876a087c2712b12f497054966f9cd98ac3d0e3eab1e4337e165e2ea42cef5ea4dd5b43b714393d92d14ddab2119b426128cf9d85f5de845b9e32959f72b1d'
+  metadata.gz: 0afbe7ebba86480f7d04766a087020734135bb0075245fbe6ba03f75590eb0c74710991b14e5fad653779ba7d6a74811d11adaeb7cfa28ec194dc9eea05adfb9
+  data.tar.gz: ddc843c9de7c3ae536f939f0c7bfc6c6d5ce2a37d4bde07d2941bd2ef7f7e0a41328d347fe1e9d8d1c1e1ba9bf916648424bd18795ad8642531d37529841d913

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at steven@fountain.com. All
+reported by contacting the project team at stevenJLi@gmail.com. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

data/Gemfile.lock

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

data/README.md

@@ -41,8 +41,8 @@ Periodoxical.generate(
       end_time: '10:30AM'
     },
   ],
-  start_date: '2024-05-23',
-  end_date: '2024-05-27',
+  starting_from: '2024-05-23',
+  ending_at: '2024-05-26',
 )
 #=> 
 [
@@ -65,6 +65,30 @@ Periodoxical.generate(
 ]
 ```
 
+The `starting_from` and `ending_at` params can also accept datetimes in ISO 8601 format for more precision. This example generate all the datetime blocks of **9:00AM - 10:30AM** but starting from **May 23, 2024 at 9:30AM**.
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  time_blocks: [
+    {
+      start_time: '9:00AM',
+      end_time: '10:30AM'
+    },
+  ],
+  starting_from: '2024-05-23T09:30:00-07:00', # can be string in iso8601 format
+  ending_at: DateTime.parse('2024-05-26T17:00:00-07:00'), # or an instance of DateTime
+)
+#=> [
+    # 2024-05-23 was skipped because the 9AM timeslot was before the `starting_from` of '2024-05-23T09:30:00-07:00'
+    {
+     start_time: #<DateTime: 2024-05-24T09:00:00-0700>,
+     end_time: #<DateTime: 2024-05-24T10: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:
 
@@ -89,8 +113,8 @@ Periodoxical.generate(
       end_time: '2:30PM'
     }
   ],
-  start_date: '2024-05-23',
-  end_date: '2024-06-12',
+  starting_from: '2024-05-23',
+  ending_at: '2024-06-12',
 )
 # returns an array of hashes, each with :start and :end keys
 #=> 
@@ -133,7 +157,7 @@ Periodoxical.generate(
       end_time: '2:30PM'
     }
   ],
-  start_date: Date.parse('2024-05-23'), # Can also pass in `Date` object.
+  starting_from: Date.parse('2024-05-23'), # Can also pass in `Date` object.
   limit: 3
 )
 # =>
@@ -167,8 +191,8 @@ As a ruby dev, I want to generate all the timeblocks between **May 23, 2024** an
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: Date.parse('2024-05-23'), # can also pass in Date objects
-  end_date: Date.parse('2024-06-12'), # can also pass in Date objects,
+  starting_from: Date.parse('2024-05-23'), # can also pass in Date objects
+  ending_at: Date.parse('2024-06-12'), # can also pass in Date objects,
   day_of_week_time_blocks: {
     mon: [
       { start_time: '8:00AM', end_time: '9:00AM' },
@@ -191,7 +215,7 @@ As a Ruby dev, I want to generate the next 3 timeblocks for **8AM - 9AM** for th
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: '2024-06-1',
+  starting_from: '2024-06-01',
   limit: 3,
   days_of_month: [5, 10],
   time_blocks: [
@@ -220,7 +244,7 @@ As a Ruby dev, I want to generate **4** timeblocks for **8AM - 9AM** on **Monday
 ```
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: '2024-04-1',
+  starting_from: '2024-04-01',
   limit: 4,
   weeks_of_month: [1 2],
   months: [4, 5, 6],
@@ -256,7 +280,7 @@ As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on the **first an
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: '2024-06-01',
+  starting_from: '2024-06-01',
   limit: 5,
   nth_day_of_week_in_month: {
     mon: [1, 2], # valid values: -1,1,2,3,4,5
@@ -291,13 +315,13 @@ Periodoxical.generate(
 ]
 ```
 
-### Example 7 - Exclude time blocks using the `exclusion_dates` parameter
+### Example 7 - Exclude time blocks using the `exclusion_dates` and `exclusion_times` parameters
 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(
   time_zone: 'America/Los_Angeles',
-  start_date: '2024-06-3',
+  starting_from: '2024-06-03',
   limit: 4,
   exclusion_dates: %w(2024-06-10),
   day_of_week_time_blocks: {
@@ -328,18 +352,76 @@ Periodoxical.generate(
 ]
 ```
 
+As a Ruby dev, I want to generate timeblocks for **8AM - 9AM**, and **10AM - 11AM** on **Mondays**, except for those that conflict (meaning overlap) with the time block of **10:30AM - 11:30AM** on the **Monday of June 10, 2024**.  I can skip the conflicting time blocks by using the `exclusion_times` parameter.
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  starting_from: '2024-06-03',
+  limit: 4,
+  days_of_week: %(mon),
+  time_blocks: [
+      { start_time: '8:00AM', end_time: '9:00AM' },
+      { start_time: '10:00AM', end_time: '11:00AM' },
+  ],
+  exclusion_times: [
+    {
+        start: '2024-06-10T10:30:00-07:00',
+        end: '2024-06-10T11:30:00-07:00',
+    }
+  ],
+)
+# =>
+[
+    {
+      start: #<DateTime 2024-06-03T08:00:00-0700>,
+      end: #<DateTime 2024-06-03T09:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-03T10:00:00-0700>,
+      end: #<DateTime 2024-06-03T11:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-10T08:00:00-0700>,
+      end: #<DateTime 2024-06-10T09:00:00-0700>,
+    },
+    # The June 10 10AM - 11AM was skipped because it overlapped with the June 10 10:30AM - 11:30AM exclusion time.
+    {
+      start: #<DateTime 2024-06-17T08:00:00-0700>,
+      end: #<DateTime 2024-06-17T09:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-17T10:00:00-0700>,
+      end: #<DateTime 2024-06-17T11:00:00-0700>,
+    },
+    {
+      start: #<DateTime 2024-06-24T08:00:00-0700>,
+      end: #<DateTime 2024-06-24T09:00:00-0700>,
+    },
+]
+```
+
 ### 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.
 
+This can be visualized as:
+
+<div align="center">
+  <img width="600" alt="alt_google_cal_image" src="https://github.com/StevenJL/periodoxical/assets/2191808/d663da17-a94a-4715-886a-8223b129dd60">
+  <p><i>(image courtesy of calendar.google.com)</i></p>
+</div>
+
+<br>
+
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: '2024-12-30',
+  starting_from: '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
+    tue: { every_other_nth: 2 }, # every other Tuesday starting at first Tuesday from `starting_from` date
+    wed: { every_other_nth: 3 }, # every 3rd Wednesday starting at first Wednesday from `starting_from` date
   },
   limit: 10,
   time_blocks: [
@@ -398,7 +480,7 @@ Generate all the Friday the 13ths ever since May 1980 (when the first Friday the
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: '1980-05-01',
+  starting_from: '1980-05-01',
   days_of_week: %w(fri),
   days_of_month: [13],
   limit: 100,
@@ -433,7 +515,7 @@ Generate the next 10 Thanksgivings from now on (Thanksgivings is defined as the
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: '2024-05-01',
+  starting_from: '2024-05-01',
   months: [11],
   nth_day_of_week_in_month: {
     thu: [4],
@@ -464,7 +546,8 @@ Periodoxical.generate(
     {
       start: #<DateTime: 2028-11-23T17:00:00-0800>,
       end: #<DateTime: 2028-11-23T18:00:00-0800>,
-    }
+    },
+    ...
 ]
 ```
 

data/lib/periodoxical/validation.rb

@@ -96,8 +96,16 @@ module Periodoxical
         end
       end
 
-      unless( @limit || @end_date)
-        raise "Either `limit` or `end_date` must be provided"
+      unless( @limit || @ending_at)
+        raise "Either `limit` or `ending_at` must be provided"
+      end
+
+      if @exclusion_times
+        @exclusion_times.each do |tb|
+          unless tb[:start] < tb[:end]
+            raise "Exclusion times must have `start` before `end`. #{tb[:start]} not before #{tb[:end]}"
+          end
+        end
       end
     end
   end

data/lib/periodoxical/version.rb

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

data/lib/periodoxical.rb

@@ -17,8 +17,8 @@ module Periodoxical
     # @param [String] time_zone
     #   Ex: 'America/Los_Angeles', 'America/Chicago',
     #   TZInfo::DataTimezone#name from the tzinfo gem (https://github.com/tzinfo/tzinfo)
-    # @param [Date, String] start_date
-    # @param [Date, String] end_date
+    # @param [Date, String] starting_from
+    # @param [Date, String] ending_at
     # @param [Array<Hash>] time_blocks
     #   Ex: [
     #     {
@@ -40,10 +40,23 @@ module Periodoxical
     # @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.
+    #   How many date times to generate.  To be used when `ending_at` is nil.
     # @param [Aray<String>] exclusion_dates
     #   Dates to be excluded when generating the time blocks
     #   Ex: ['2024-06-10', '2024-06-14']
+    # @param [Aray<Hash>] exclusion_times
+    #   Timeblocks to be excluded when generating the time blocks if there is conflict (ie. overlap)
+    #   Ex: [
+    #         {
+    #           start: '2024-06-10T10:30:00-07:00',
+    #           end: '2024-06-10T11:30:00-07:00'
+    #         },
+    #         {
+    #           start: '2024-06-10T14:30:00-07:00',
+    #           end: '2024-06-10T15:30:00-07:00'
+    #         },
+    #       ]
+    #
     # @param [Hash<Array<Hash>>] day_of_week_time_blocks
     #   To be used when hours are different between days of the week
     #   Ex: {
@@ -52,12 +65,13 @@ module Periodoxical
     #     fri: { start_time: '7:00PM', end_time: '9:00PM' },
     #   }
     def initialize(
-      start_date:,
-      end_date: nil,
+      starting_from:,
+      ending_at: nil,
       time_blocks: nil,
       day_of_week_time_blocks: nil,
       limit: nil,
       exclusion_dates: nil,
+      exclusion_times: nil,
       time_zone: 'Etc/UTC',
       days_of_week: nil,
       nth_day_of_week_in_month: nil,
@@ -78,12 +92,17 @@ module Periodoxical
       @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
-      @end_date = end_date.is_a?(String) ? Date.parse(end_date) : end_date
+      @starting_from = date_object_from(starting_from)
+      @ending_at = date_object_from(ending_at)
       @limit = limit
       @exclusion_dates = if exclusion_dates && !exclusion_dates.empty?
                            exclusion_dates.map { |ed| Date.parse(ed) }
                          end
+      @exclusion_times = if exclusion_times
+                           exclusion_times.map do |et|
+                             { start: DateTime.parse(et[:start]), end: DateTime.parse(et[:end]) }
+                           end
+                         end
       validate!
     end
 
@@ -155,7 +174,11 @@ module Periodoxical
     # Variables which manage flow of looping through time and generating slots
     def initialize_looping_variables!
       @output = []
-      @current_date = @start_date
+      if @starting_from.is_a?(DateTime)
+        @current_date = @starting_from.to_date
+      else
+        @current_date = @starting_from
+      end
       @current_day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
       @current_count = 0
       @keep_generating = true
@@ -184,6 +207,10 @@ module Periodoxical
     #  }
     #  Generates time block but also checks if we should stop generating
     def append_to_output_and_check_limit(time_block)
+      # Check if this particular time is conflicts with any times from `exclusion_times`.
+      return if overlaps_with_an_excluded_time?(time_block)
+      return if before_starting_from_or_after_ending_at?(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])
@@ -202,7 +229,7 @@ module Periodoxical
 
       @current_day_of_week = day_of_week_long_to_short(@current_date.strftime("%A"))
 
-      if @end_date && (@current_date > @end_date)
+      if @ending_at && (@current_date > @ending_at)
         @keep_generating = false
       end
 
@@ -210,7 +237,7 @@ module Periodoxical
       # 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?
+      if @limit && ((@current_date - @starting_from).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
@@ -302,8 +329,8 @@ module Periodoxical
       #       end_time: '10:30AM'
       #     },
       #   ],
-      #   start_date: '2024-05-23',
-      #   end_date: '2024-05-27',
+      #   starting_from: '2024-05-23',
+      #   ending_at: '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.
@@ -350,5 +377,86 @@ module Periodoxical
     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
+
+    # @return [Boolean]
+    #   Used only when `starting_from` and `ending_at` are instances of DateTime
+    #   instead of Date, requiring more precision, calculation.
+    def before_starting_from_or_after_ending_at?(time_block)
+      return false unless @starting_from.is_a?(DateTime) || @ending_at.is_a?(DateTime)
+
+      if @starting_from.is_a?(DateTime)
+        start_time = time_str_to_object(@current_date, time_block[:start_time])
+
+        # If the candidate time block is starting earlier than @starting_from, we want to skip it
+        return true if start_time < @starting_from
+      end
+
+      if @ending_at.is_a?(DateTime)
+        end_time = time_str_to_object(@current_date, time_block[:end_time])
+
+        # If the candidate time block is ending after @ending_at, we want to skip it
+        return true if end_time > @ending_at
+      end
+
+      false
+    end
+
+    # @return [Boolean]
+    #   Whether or not the given `time_block` in the @current_date and
+    #   @time_zone overlaps with the times in `exclusion_times`.
+    def overlaps_with_an_excluded_time?(time_block)
+      return false unless @exclusion_times
+
+      @exclusion_times.each do |exclusion_timeblock|
+        return true if overlap?(
+          exclusion_timeblock,
+          {
+            start: time_str_to_object(@current_date, time_block[:start_time]),
+            end: time_str_to_object(@current_date, time_block[:end_time]),
+          }
+        )
+      end
+
+      false
+    end
+
+    # @param [Hash] time_block_1, time_block_2
+    #  Ex: {
+    #    start: #<DateTime>,
+    #    end: #<DateTime>,
+    #  }
+    def overlap?(time_block_1, time_block_2)
+      tb_1_start = time_block_1[:start]
+      tb_1_end = time_block_1[:end]
+      tb_2_start = time_block_2[:start]
+      tb_2_end = time_block_2[:end]
+
+      # Basicall overlap is when one starts before the other has ended
+      return true if tb_1_end > tb_2_start && tb_1_end < tb_2_end
+      # By symmetry
+      return true if tb_2_end > tb_1_start && tb_2_end < tb_1_end
+
+      false
+    end
+
+    def date_object_from(dt)
+      return unless dt
+      return dt if dt.is_a?(Date) || dt.is_a?(DateTime)
+
+      if dt.is_a?(String)
+        return Date.parse(dt) if /\A\d{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[12]\d|3[01])\z/ =~ dt
+
+        if /\A\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-][01]\d:[0-5]\d)?\z/ =~ dt
+          # convert to DateTime object
+          dt = DateTime.parse(dt)
+          # convert to given time_zone
+          return dt.to_time.localtime(@time_zone.utc_offset).to_datetime
+        end
+
+        raise "Could not parse date/datetime string #{dt}.  Please README for examples."
+      else
+        raise "Invalid argument: #{dt}"
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Steven Li
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-03 00:00:00.000000000 Z
+date: 2024-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo