cron_calc 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65bbd980a990785461ad8513755d5ef1effc8d14f4dac4205bf0381f4489bbcd
-  data.tar.gz: 116ac513ff00017a519997d1399748faa95284b2171e6f11c5097a25b10525ee
+  metadata.gz: aebec718fd55bb74df49580abe4309a41ad0246b2c266a143f9dfac807cd436e
+  data.tar.gz: 1b47dea7541f369800f1f816fdf2160e0721de4a4f8bcdd9434c0b77fdf85876
 SHA512:
-  metadata.gz: 70d5d114af61a0430a52b8ef0fc06caecc693fe8f632472814f4335543b038ba6c94565069f831ee7486a8633e015e8833c65b6f1ba2814832a7bb5e4352c9fb
-  data.tar.gz: cb5b23e742052e1b76035721214c28c2a9ce162b70d7c1d60bb308e378db36318c3e4ceac9e65b4a7dc779c1cc710109880f8b921f00580df77bf5f1cc8d3539
+  metadata.gz: f6f3349709b4a5babb3d2267f7e8cf1a7e2e51d9a118044e67743cc02b31d34bf5d637b068e825afe9f10c24e34c97a906730363a2c1c309eb003408b2c48586
+  data.tar.gz: fd80e141fd67e56adb122b6acf2dbbeff5572e69868212c749d1f6d67c422d70790a9910cec991a2ef328841f8fea17e2214c6276761124f5e4630f04c613557

data/CHANGELOG.md

@@ -1,6 +1,16 @@
+## [1.0.0] - 2023-12-28
+
+- Add support for predefined definitions
+- Add support for joining ,-
+
+## [0.4.0] - 2023-12-22
+
+- Added support for named months and wdays
+- Keyword arguments: before:, after:
+
 ## [0.3.0] - 2023-12-22
 
-- Added support for DOWs
+- Added support for DOWs (wdays)
 
 ## [0.2.0] - 2023-12-19
 

data/README.md

@@ -1,6 +1,11 @@
 # CronCalc
 
-CronCalc: A Ruby gem for calculating and analyzing scheduled CRON job occurrences and timings within specified intervals.
+**CronCalc**: A Ruby gem for calculating CRON job occurrences. With this gem, you can easily determine when a cron job will occur by providing a cron expression. Key features include the ability to **calculate occurrences**:
+- **Within a specified period**: Find out all the times your cron job will run during a particular timeframe.
+- **After a given date**: Determine the next set of occurrences after a specific starting point.
+- **Before a given date**: Discover when your cron job ran or would have run before a certain date.
+
+This tool can be used for scheduling, forecasting, and analyzing tasks in systems that use cron for job scheduling.
 
 ## Installation
 
@@ -22,8 +27,9 @@ Now, you can use one of three methods `#in`, `#next`, `#last` to determine cron
 ### Using `#in`
 
 Calculates cron job occurrences within a given time period.\
-@param period [Range] The time period for which to calculate cron job occurrences.\
-@return [Array<Time>] An array of Time instances representing each occurrence.
+**Parameters:**
+- `period` - a Range object defining the start and end times for the calculation.\
+
 
 ```ruby
     period = Time.new(2024, 1, 1, 0, 0)..Time.new(2024, 1, 4, 0, 0)
@@ -35,10 +41,10 @@ Calculates cron job occurrences within a given time period.\
 ### Using `#next`
 
 Calculates the next 'n' occurrences of the cron job from a given start time.\
-@param count [Integer] The number of occurrences to calculate. Defaults to `1`.\
-@param period_start [Time] The start time from which to calculate occurrences. Defaults to `Time.now`.\
-@param max_years [Integer] The maximum number of years to consider for the period. Defaults to `5`.\
-@return [Array<Time>] An array of the next 'n' occurrences.
+**Parameters:**
+- `count` - (optional, Integer) The number of occurrences to calculate. Defaults to 1.
+- `after:` - (optional, Time, keyword argument) The start time from which to calculate occurrences. If not provided, defaults to the current time (Time.now).
+- `max_years` - (optional, Integer, keyword argument) The maximum number of years to search for future occurrences. Defaults to 5.
 
 ```ruby
     cron_calc.next
@@ -47,31 +53,41 @@ Calculates the next 'n' occurrences of the cron job from a given start time.\
     cron_calc.next(3)
     # => [2023-12-20 05:05:00 +0100, 2023-12-21 05:05:00 +0100, 2023-12-22 05:05:00 +0100]
 
-    cron_calc.next(2, Time.new(2024, 1, 1, 0, 0))
+    cron_calc.next(2, after: Time.new(2024, 1, 1, 0, 0))
     # => [2024-01-01 05:05:00 +0100, 2024-01-02 05:05:00 +0100]
 ```
 
 ### Using `#last`
 
 Calculates the last 'n' occurrences of the cron job until a given end time.\
-@param count [Integer] The number of past occurrences to calculate.\
-@param period_end [Time] The end time until which to calculate occurrences.\
-@param max_years [Integer] The maximum number of years to consider for the period.\
-@return [Array<Time>] An array of the last 'n' occurrences.
+**Parameters:**
+- `count` - (optional, Integer) The number of occurrences to calculate. Defaults to 1.
+- `before:` - (optional, Time, keyword argument) The end time from which to calculate past occurrences. If not provided, defaults to the current time (Time.now).
+- `max_years` - (optional, Integer, keyword argument) The maximum number of years to search backward for past occurrences. Defaults to 5.
 
 ```ruby
     cron_calc.last
     # => [2023-12-19 05:05:00 +0100]
 
-    cron_calc.last(4, Time.new(2024, 1, 1, 0, 0))
+    cron_calc.last(4, before: Time.new(2024, 1, 1, 0, 0))
     # => [2023-12-31 05:05:00 +0100, 2023-12-30 05:05:00 +0100, 2023-12-29 05:05:00 +0100, 2023-12-28 05:05:00 +0100]
 ```
 
-## Unsupported features
+### Other examples
+
+```ruby
+    # You can omit the count parameter
+    CronCalc.new('5 5 */5 * SUN').last(before: Time.new(2020, 1, 1, 0, 0))
+    # => [2019-12-01 05:05:00 +0100]
+
+    # You can combine ',' and '-'
+    CronCalc.new('5 5 5-7,10 FEB *').next(5)
+    # => [2024-02-05 05:05:00 +0100, 2024-02-06 05:05:00 +0100, 2024-02-07 05:05:00 +0100, 2024-02-10 05:05:00 +0100, 2025-02-05 05:05:00 +0100]
 
-- Named DOW and months (SUN-SAT, JAN-DEC)
-- Joining characters , - /
-- Predefined definitions (@yearly, @monthly, @weekly, @daily, @midnight, @hourly)
+    # You can use predefined definitions like @daily, @monthly, etc.
+    CronCalc.new('@monthly').next(3, after: Time.new(2024, 1, 1, 0, 0))
+    # => [2024-01-01 00:00:00 +0100, 2024-02-01 00:00:00 +0100, 2024-03-01 00:00:00 +0100]
+```
 
 ## Contributing
 

data/lib/cron_calc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CronCalc
-  VERSION = '0.3.0'
+  VERSION = '1.0.0'
 end

data/lib/cron_calc.rb

@@ -7,6 +7,33 @@ require 'time'
 module CronCalc
   class Error < StandardError; end
 
+  RANGE = {
+    minutes: 0..59,
+    hours: 0..23,
+    days: 1..31,
+    months: 1..12,
+    wdays: 0..6
+  }.freeze
+
+  WDAYS = {
+    'SUN' => '0', 'MON' => '1', 'TUE' => '2', 'WED' => '3',
+    'THU' => '4', 'FRI' => '5', 'SAT' => '6'
+  }.freeze
+
+  MONTHS = {
+    'JAN' => '1', 'FEB' => '2', 'MAR' => '3', 'APR' => '4',
+    'MAY' => '5', 'JUN' => '6', 'JUL' => '7', 'AUG' => '8',
+    'SEP' => '9', 'OCT' => '10', 'NOV' => '11', 'DEC' => '12'
+  }.freeze
+
+  PREDEFINED_DEFINITIONS = {
+    '@yearly' => '0 0 1 1 *', '@annually' => '0 0 1 1 *',
+    '@monthly' => '0 0 1 * *',
+    '@weekly' => '0 0 * * 0',
+    '@daily' => '0 0 * * *', '@midnight' => '0 0 * * *',
+    '@hourly' => '0 * * * *'
+  }.freeze
+
   def self.new(cron_string)
     Parser.new(cron_string)
   end
@@ -17,19 +44,12 @@ module CronCalc
   class Parser
     attr_reader :cron_string, :cron_parts
 
-    RANGE = {
-      minutes: 0..59,
-      hours: 0..23,
-      days: 1..31,
-      months: 1..12,
-      dows: 0..7
-    }.freeze
-
     def initialize(cron_string)
       @cron_string = cron_string
 
       raise 'Cron expression is not supported or invalid' unless cron_string_valid?
 
+      @cron_string = normalize_with(cron_string, PREDEFINED_DEFINITIONS) if @cron_string.start_with? '@'
       @cron_parts = split_cron_string
     end
 
@@ -42,24 +62,24 @@ module CronCalc
 
     # Calculates the next 'n' occurrences of the cron job from a given start time.
     # @param count [Integer] The number of occurrences to calculate.
-    # @param period_start [Time] The start time from which to calculate occurrences.
+    # @param after [Time] The start time from which to calculate occurrences.
     # @param max_years [Integer] The maximum number of years to consider for the period.
     # @return [Array<Time>] An array of the next 'n' occurrences.
-    def next(count = 1, period_start = Time.now, max_years = 5)
+    def next(count = 1, after: Time.now, max_years: 5)
       occurrences(
-        period_start..(period_start + (60 * 60 * 24 * 365 * max_years)),
+        after..(after + (60 * 60 * 24 * 365 * max_years)),
         count
       )
     end
 
     # Calculates the last 'n' occurrences of the cron job until a given end time.
     # @param count [Integer] The number of past occurrences to calculate.
-    # @param period_end [Time] The end time until which to calculate occurrences.
+    # @param before [Time] The end time until which to calculate occurrences.
     # @param max_years [Integer] The maximum number of years to consider for the period.
     # @return [Array<Time>] An array of the last 'n' occurrences.
-    def last(count = 1, period_end = Time.now, max_years = 5)
+    def last(count = 1, before: Time.now, max_years: 5)
       occurrences(
-        (period_end - (60 * 60 * 24 * 365 * max_years))..period_end,
+        (before - (60 * 60 * 24 * 365 * max_years))..before,
         count,
         reverse: true
       )
@@ -69,7 +89,7 @@ module CronCalc
 
     def occurrences(period, count = nil, reverse: false)
       time_combinations = generate_time_combinations(period, reverse).lazy
-      wdays = parse_cron_part(:dows)
+      wdays = parse_cron_part(:wdays)
 
       time_combinations.each_with_object([]) do |(year, month, day, hour, minute), occ|
         break occ if count && occ.length == count
@@ -94,8 +114,8 @@ module CronCalc
         minutes: splitted[0],
         hours: splitted[1],
         days: splitted[2],
-        months: splitted[3],
-        dows: splitted[4]
+        months: normalize_with(splitted[3], MONTHS),
+        wdays: normalize_with(splitted[4], WDAYS)
       }
     end
 
@@ -103,31 +123,40 @@ module CronCalc
       %i[minutes hours days months].map { |unit| parse_cron_part(unit) }
     end
 
-    # rubocop:disable Metrics
     def parse_cron_part(time_unit)
       range = RANGE[time_unit]
       part = cron_parts[time_unit]
 
-      case part
+      if part.include?(',')
+        part.split(',').flat_map { |e| parse_single_element(e, range) }.uniq.sort
+      else
+        parse_single_element(part, range)
+      end
+    end
+
+    def parse_single_element(element, range)
+      case element
       when '*'
         range.to_a
-      when /,/
-        part.split(',').map(&:to_i)
       when /-/
-        (part.split('-').first.to_i..part.split('-').last.to_i).to_a
+        (element.split('-').first.to_i..element.split('-').last.to_i).to_a
       when %r{/}
-        range.step(part.split('/').last.to_i).to_a
+        range.step(element.split('/').last.to_i).to_a
       else
-        [part.to_i]
+        [element.to_i]
       end
     end
-    # rubocop:enable Metrics
+
+    def normalize_with(string, mapping)
+      mapping.inject(string) { |str, (k, v)| str.gsub(k, v) }
+    end
 
     def cron_string_valid?
+      predefined = /\A@(yearly|annually|monthly|weekly|daily|midnight|hourly)\z/
       # rubocop:disable Layout/LineLength
-      regex = %r{\A(\*|([0-5]?\d)(,([0-5]?\d))*|(\*/\d+)|(\d+-\d+)) (\*|([01]?\d|2[0-3])(,([01]?\d|2[0-3]))*|(\*/\d+)|(\d+-\d+)) (\*|([12]?\d|3[01])(,([12]?\d|3[01]))*|(\*/\d+)|(\d+-\d+)) (\*|([1-9]|1[0-2])(,([1-9]|1[0-2]))*|(\*/\d+)|(\d+-\d+)) (\*|([0-6])(,([0-6]))*|(\*/[0-6]+)|([0-6]-[0-6]))\z}
+      standard = %r{\A(\*|(\*/[0-5]?\d)|([0-5]?\d)(-(?:[0-5]?\d))?(,([0-5]?\d)(-(?:[0-5]?\d))?)*) (\*|(\*/[01]?\d|2[0-3])|([01]?\d|2[0-3])(-(?:[01]?\d|2[0-3]))?(,([01]?\d|2[0-3])(-(?:[01]?\d|2[0-3]))?)*|(\*/\d+)) (\*|(\*/[12]?\d|3[01])|([12]?\d|3[01])(-(?:[12]?\d|3[01]))?(,([12]?\d|3[01])(-(?:[12]?\d|3[01]))?)*|(\*/\d+)) (\*|(\*/[1-9]|1[0-2])|(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|[1-9]|1[0-2])(-(?:JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|[1-9]|1[0-2]))?(,(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|[1-9]|1[0-2])(-(?:JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|[1-9]|1[0-2]))?)*|(\*/\d+)) (\*|(\*/[0-6])|(SUN|MON|TUE|WED|THU|FRI|SAT|[0-6])(-(?:SUN|MON|TUE|WED|THU|FRI|SAT|[0-6]))?(,(SUN|MON|TUE|WED|THU|FRI|SAT|[0-6])(-(?:SUN|MON|TUE|WED|THU|FRI|SAT|[0-6]))?)*|(\*/[0-6]+))\z}
       # rubocop:enable Layout/LineLength
-      cron_string.match?(regex)
+      cron_string.match?(predefined) || cron_string.match?(standard)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cron_calc
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Jakub Miziński
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-12-22 00:00:00.000000000 Z
+date: 2023-12-28 00:00:00.000000000 Z
 dependencies: []
 description: |-
   Calculates cron job occurrences within a specified period