periodoxical 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3836bd7c49ec987409e70592d93cb8c021a009ce3587e48a6419c12121af3b1d
-  data.tar.gz: 510bb79570482c8019e911c8900ec15ee5016b59c1d51677d38d53f7c632523f
+  metadata.gz: c9f062ec6b1b65c56a01d48386370fe8f1e12b91f0426228ca625bac03272d1b
+  data.tar.gz: 101efa2d001ca56deb4ff3d5cef552f4aeaa98e6cecbe043ea1f990b38b8bc36
 SHA512:
-  metadata.gz: 0afbe7ebba86480f7d04766a087020734135bb0075245fbe6ba03f75590eb0c74710991b14e5fad653779ba7d6a74811d11adaeb7cfa28ec194dc9eea05adfb9
-  data.tar.gz: ddc843c9de7c3ae536f939f0c7bfc6c6d5ce2a37d4bde07d2941bd2ef7f7e0a41328d347fe1e9d8d1c1e1ba9bf916648424bd18795ad8642531d37529841d913
+  metadata.gz: 7f0a45cb869fd3ec84bd097f0c793f1f0561ce292f48a3bc2521ad714685cd3cc1582956cc572fc4b23c045ea2fe853706467dcbb39fc328254d5855fcf4da2e
+  data.tar.gz: 4ab479448dbfc960996e8535f962cefd58392452f32f9e116d6faf1a373767c6062949e2959f9d64844fe0168c0e92b3edf313a9b5a3499e4c29771c6b0bd4bd

data/Gemfile.lock

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

data/README.md

@@ -29,7 +29,7 @@ Or install it yourself as:
 
 ## Usage
 
-### Example 1
+### Basic Example
 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
@@ -47,25 +47,25 @@ Periodoxical.generate(
 #=> 
 [
     {
-     start_time: #<DateTime: 2024-05-23T09:00:00-0700>,
-     end_time: #<DateTime: 2024-05-23T10:30:00-0700>,
+     start: #<DateTime: 2024-05-23T09:00:00-0700>,
+     end: #<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: #<DateTime: 2024-05-24T09:00:00-0700>,
+     end: #<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: #<DateTime: 2024-05-25T09:00:00-0700>,
+     end: #<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>,
+     start: #<DateTime: 2024-05-26T09:00:00-0700>,
+     end: #<DateTime: 2024-05-26T10:30:00-0700>,
     }
 ]
 ```
 
-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**.
+The `starting_from` and `ending_at` params can also accept datetimes in ISO 8601 format. This example generate all the datetime blocks of **9:00AM - 10:30AM** but starting from **May 23, 2024 at 9:30AM**.
 
 ```rb
 Periodoxical.generate(
@@ -80,7 +80,8 @@ Periodoxical.generate(
   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'
+    # 2024-05-23 was skipped because the 9AM time block 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>,
@@ -89,8 +90,8 @@ Periodoxical.generate(
 ]
 ```
 
-### 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:
+### 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. I can do this using the `days_of_week` parameter. 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">
@@ -139,9 +140,9 @@ Periodoxical.generate(
 ]
 ```
 
-### Example 3 - using the `limit` key.
+### Example using the `limit` parameter.
 
-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**. I can do this using the `limit` parameter, instead of `ending_at`.
 
 ```rb
 Periodoxical.generate(
@@ -177,9 +178,9 @@ Periodoxical.generate(
 ]
 ```
 
-### Example 4 - when time blocks vary between days
+### Time blocks that vary between days-of-the-week
 
-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**.
+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**.  I can do this using the `day_of_week_time_blocks` parameter.
 
 <div align="center">
   <img width="628" alt="calendar_image_2" src="https://github.com/StevenJL/periodoxical/assets/2191808/26d14824-08ff-481a-97e2-9b6b11beea29">
@@ -208,9 +209,9 @@ Periodoxical.generate(
 )
 ```
 
-### Example 5 - when specifying time blocks using day-of-month and/or week-of-month and/or month.
+### Specifying time blocks using rules for day-of-month and/or week-of-month and/or month.
 
-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**
+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**.  I can do this using the `days_of_month` parameter.
 
 ```rb
 Periodoxical.generate(
@@ -239,7 +240,7 @@ Periodoxical.generate(
 ]
 ```
 
-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**
+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**.  I can do this using the `months` parameter.
 
 ```
 Periodoxical.generate(
@@ -284,7 +285,7 @@ Periodoxical.generate(
   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.
+    fri: [-1], # Use -1 to specify the last Friday of the month.
   },
   time_blocks: [
     { start_time: '8:00AM', end_time: '9:00AM' },
@@ -316,7 +317,7 @@ Periodoxical.generate(
 ```
 
 ### 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**.
+As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on **Mondays**, except for the **Monday of June 10, 2024**.  I can do this using the `exlcusion_dates` parameter.
 
 ```rb
 Periodoxical.generate(
@@ -403,7 +404,7 @@ 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.
+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 with the `every` and `every_other_nth` keys to specify the every-other-nth-rules.
 
 This can be visualized as:
 
@@ -473,6 +474,50 @@ Periodoxical.generate(
 ]
 ```
 
+### Use the `duration` key, to automatically partition the provided `time_blocks` into smaller chunks to the given duration.
+
+As a Ruby dev, I want to generate **30 minute** time blocks between **9:00AM - 1:00PM, and 2:00PM - 5:00PM**.  Because it is too tedious to generate all 14 of these time blocks, I prefer to pass in the `duration` key and have `periodoxical` generate them for me.
+
+N.B. If you provide a duration that conflicts with your time blocks, `periodoxical` will not return any time blocks.  For example, if you specify **9:00AM - 10:00AM** but set your **duration** as  90 minutes, no time blocks are generated since we can't fit 90 minutes into an hour!
+
+
+```rb
+Periodoxical.generate(
+  time_zone: 'America/Los_Angeles',
+  time_blocks: [
+    {
+      start_time: '9:00AM',
+      end_time: '1:00PM'
+    },
+    {
+      start_time: '2:00PM',
+      end_time: '5:00PM'
+    },
+  ],
+  duration: 30, #(minutes)
+  starting_from: '2024-05-23',
+  ending_at: '2024-05-26',
+)
+# => [
+    {
+      start: #<DateTime: 2024-05-23T09:00:00--0700>
+      end: #<DateTime: 2024-05-23T09:30:00--0700>
+    },
+    {
+      start: #<DateTime: 2024-05-23T09:30:00--0700>
+      end: #<DateTime: 2024-05-23T10:00:00--0700>
+    },
+    {
+      start: #<DateTime: 2024-05-23T10:00:00--0700>
+      end: #<DateTime: 2024-05-23T10:30:00--0700>
+    },
+    {
+      start: #<DateTime: 2024-05-23T10:30:00--0700>
+      end: #<DateTime: 2024-05-23T11: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).

data/lib/periodoxical/helpers.rb

@@ -0,0 +1,70 @@
+module Periodoxical
+  module Helpers
+    def deep_symbolize_keys(obj)
+      return unless obj
+
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          symbolized_key = key.to_sym rescue key
+          result[symbolized_key] = deep_symbolize_keys(value)
+        end
+      when Array
+        obj.map { |e| deep_symbolize_keys(e) }
+      else
+        obj
+      end
+    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
+
+    def day_of_week_long_to_short(dow)
+      {
+        "Monday" => "mon",
+        "Tuesday" => "tue",
+        "Wednesday" => "wed",
+        "Thursday" => "thu",
+        "Friday" => "fri",
+        "Saturday" => "sat",
+        "Sunday" => "sun",
+      }[dow]
+    end
+  end
+end

data/lib/periodoxical/version.rb

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

data/lib/periodoxical.rb

@@ -1,5 +1,6 @@
 require "periodoxical/version"
 require "periodoxical/validation"
+require "periodoxical/helpers"
 require "date"
 require "time"
 require "tzinfo"
@@ -14,6 +15,7 @@ module Periodoxical
 
   class Core
     include Periodoxical::Validation
+    include Periodoxical::Helpers
     # @param [String] time_zone
     #   Ex: 'America/Los_Angeles', 'America/Chicago',
     #   TZInfo::DataTimezone#name from the tzinfo gem (https://github.com/tzinfo/tzinfo)
@@ -64,6 +66,12 @@ module Periodoxical
     #     tue: { start_time: '11:30PM', end_time: '12:00AM' },
     #     fri: { start_time: '7:00PM', end_time: '9:00PM' },
     #   }
+    # @param [Integer] duration
+    #   Splits the time_blocks into this duration (in minutes). For example, if time_block is 9:00AM - 10:00AM,
+    #   and duration is 20 minutes.  It creates 3 timeblocks of:
+    #     - 9:00AM - 9:20AM
+    #     - 9:20AM - 9:40AM
+    #     - 9:40AM - 10:00AM
     def initialize(
       starting_from:,
       ending_at: nil,
@@ -77,29 +85,38 @@ module Periodoxical
       nth_day_of_week_in_month: nil,
       days_of_month: nil,
       weeks_of_month: nil,
+      duration: nil,
       months: nil
     )
 
       @time_zone = TZInfo::Timezone.get(time_zone)
       if days_of_week.is_a?(Array)
-        @days_of_week = days_of_week
+        @days_of_week = deep_symbolize_keys(days_of_week)
       elsif days_of_week.is_a?(Hash)
-        @days_of_week_with_alternations = days_of_week
+        @days_of_week_with_alternations = deep_symbolize_keys(days_of_week)
       end
-      @nth_day_of_week_in_month = nth_day_of_week_in_month
+      @nth_day_of_week_in_month = deep_symbolize_keys(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
+      @time_blocks = deep_symbolize_keys(time_blocks)
+      @day_of_week_time_blocks = deep_symbolize_keys(day_of_week_time_blocks)
       @starting_from = date_object_from(starting_from)
       @ending_at = date_object_from(ending_at)
       @limit = limit
+
+      if duration
+        unless duration.is_a?(Integer)
+          raise "duration must be an integer"
+        else
+          @duration = duration
+        end
+      end
       @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|
+                           deep_symbolize_keys(exclusion_times).map do |et|
                              { start: DateTime.parse(et[:start]), end: DateTime.parse(et[:end]) }
                            end
                          end
@@ -130,18 +147,6 @@ module Periodoxical
 
     private
 
-    def day_of_week_long_to_short(dow)
-      {
-        "Monday" => "mon",
-        "Tuesday" => "tue",
-        "Wednesday" => "wed",
-        "Thursday" => "thu",
-        "Friday" => "fri",
-        "Saturday" => "sat",
-        "Sunday" => "sun",
-      }[dow]
-    end
-
     # @param [String] time_str
     #   Ex: '9:00AM'
     # @param [Date] date
@@ -211,19 +216,31 @@ module Periodoxical
       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])
-      }
+      strtm = time_str_to_object(@current_date, time_block[:start_time])
+      endtm = 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
+      if @duration
+        split_by_duration_and_append(strtm, endtm)
+      else
+        @output << {
+          start: strtm,
+          end: endtm 
+        }
+        increment_and_check_limit
       end
     end
 
+    # increment count, if `limit` is used to stop generating
+    def increment_and_check_limit
+      return unless @limit
+
+      @current_count += 1
+      return if @current_count < @limit
+
+      @keep_generating = false
+      throw :done
+    end
+
     def advance_current_date_and_check_if_reached_end_date
       @current_date = @current_date + 1
 
@@ -420,42 +437,18 @@ module Periodoxical
       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}"
+    def split_by_duration_and_append(strtm, endtm)
+      delta = Rational(@duration, 24 * 60)
+      si = strtm
+      ei = strtm + delta
+      while ei <= endtm
+        @output << {
+          start: si,
+          end: ei
+        }
+        si += delta
+        ei += delta
+        increment_and_check_limit
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Steven Li
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-04 00:00:00.000000000 Z
+date: 2024-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -125,7 +125,6 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -135,6 +134,7 @@ files:
 - bin/console
 - bin/setup
 - lib/periodoxical.rb
+- lib/periodoxical/helpers.rb
 - lib/periodoxical/validation.rb
 - lib/periodoxical/version.rb
 - periodoxical.gemspec

data/.travis.yml

@@ -1,7 +0,0 @@
----
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-  - 2.6.10
-before_install: gem install bundler -v 1.17.2