periodoxical 0.9.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1028e4261c9759e49e7446a1ff506fcb4d3b789b4bdd1ef40dbec0bd8df18ae8
-  data.tar.gz: c7dece06fabe86ede77b98203bea7716d0d1e039393f1e6e693c8a232615ef01
+  metadata.gz: 3836bd7c49ec987409e70592d93cb8c021a009ce3587e48a6419c12121af3b1d
+  data.tar.gz: 510bb79570482c8019e911c8900ec15ee5016b59c1d51677d38d53f7c632523f
 SHA512:
-  metadata.gz: '08dc98ece1a24ed33564c60f32c31fcf76defddbab51fbf2c0c3df04b296759767fc1dde8a4ed744a24b700fe812ce97bcdc06c052c382e61872c55426116258'
-  data.tar.gz: c8edb8ea410b88c5888edda103752c27c149e4e06421b74fb7c4a29ed0f09ae32726536ed495702156b8e6e054da0a5140e1a3487bbbac4468abb94ed7cfb79f
+  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.9.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
@@ -297,7 +321,7 @@ As a Ruby dev, I want to generate timeblocks for **8AM - 9AM** on **Mondays**, e
 ```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: {
@@ -333,7 +357,7 @@ As a Ruby dev, I want to generate timeblocks for **8AM - 9AM**, and **10AM - 11A
 ```rb
 Periodoxical.generate(
   time_zone: 'America/Los_Angeles',
-  start_date: '2024-06-3',
+  starting_from: '2024-06-03',
   limit: 4,
   days_of_week: %(mon),
   time_blocks: [
@@ -393,11 +417,11 @@ This can be visualized as:
 ```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: [
@@ -456,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,
@@ -491,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],

data/lib/periodoxical/validation.rb

@@ -96,8 +96,8 @@ 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

data/lib/periodoxical/version.rb

@@ -1,3 +1,3 @@
 module Periodoxical
-  VERSION = "0.9.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,7 +40,7 @@ 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']
@@ -65,8 +65,8 @@ 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,
@@ -92,8 +92,8 @@ 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) }
@@ -174,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
@@ -205,6 +209,7 @@ module Periodoxical
     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]),
@@ -224,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
 
@@ -232,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
@@ -324,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.
@@ -373,6 +378,29 @@ module Periodoxical
       @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`.
@@ -410,5 +438,25 @@ module Periodoxical
 
       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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: periodoxical
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Steven Li