cron_calc 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5757a8135782488cf246c22cd72ccc0aa04e00d06a726203df41205c0df79ef8
-  data.tar.gz: d33394dd5136e58f41a4ea7d8e6759d5e51326e61bb9bc4303d9778d6f85de60
+  metadata.gz: 65bbd980a990785461ad8513755d5ef1effc8d14f4dac4205bf0381f4489bbcd
+  data.tar.gz: 116ac513ff00017a519997d1399748faa95284b2171e6f11c5097a25b10525ee
 SHA512:
-  metadata.gz: 708988f704dee9a33f9331c3508485c2bcc45d7184fac956c590dad69e468e8eabb282a863d391f13f655c1816ef2aae62e77b8d66db755cec4122530ddde178
-  data.tar.gz: 4dfc4c4c89ea7e983d95837dfb014992c2916b0cb54d731cb2f95441687cddf94bfeb90133cc180fddd4e3a96d23254819c8ec416db1498200270a67c291af5b
+  metadata.gz: 70d5d114af61a0430a52b8ef0fc06caecc693fe8f632472814f4335543b038ba6c94565069f831ee7486a8633e015e8833c65b6f1ba2814832a7bb5e4352c9fb
+  data.tar.gz: cb5b23e742052e1b76035721214c28c2a9ce162b70d7c1d60bb308e378db36318c3e4ceac9e65b4a7dc779c1cc710109880f8b921f00580df77bf5f1cc8d3539

data/CHANGELOG.md

@@ -1,5 +1,12 @@
-## [Unreleased]
+## [0.3.0] - 2023-12-22
 
-## [0.1.0] - 2023-11-27
+- Added support for DOWs
+
+## [0.2.0] - 2023-12-19
+
+- Added #next method
+- Added #last method
+
+## [0.1.0] - 2023-12-18
 
 - Initial release

data/README.md

@@ -4,25 +4,74 @@ CronCalc: A Ruby gem for calculating and analyzing scheduled CRON job occurrence
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Install the gem by executing:
 
-Install the gem and add to the application's Gemfile by executing:
+    $ gem install cron_calc
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+## Usage
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+After installing `cron_calc` you can initialize `CronCalc` with the CRON string.
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+    require 'cron_calc'
+    cron_calc = CronCalc.new('5 5 * * *')
+```
 
-## Usage
+Now, you can use one of three methods `#in`, `#next`, `#last` to determine cron job occurrencies within specified period.
+
+### 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.
+
+```ruby
+    period = Time.new(2024, 1, 1, 0, 0)..Time.new(2024, 1, 4, 0, 0)
+    cron_calc.in(period)
+
+    # => [2024-01-01 05:05:00 +0100, 2024-01-02 05:05:00 +0100, 2024-01-03 05:05:00 +0100]
+```
+
+### 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.
+
+```ruby
+    cron_calc.next
+    # => [2023-12-20 05:05:00 +0100]
+
+    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))
+    # => [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.
 
-TODO: Write usage instructions here
+```ruby
+    cron_calc.last
+    # => [2023-12-19 05:05:00 +0100]
 
-## Development
+    cron_calc.last(4, 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]
+```
 
-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.
+## Unsupported features
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- Named DOW and months (SUN-SAT, JAN-DEC)
+- Joining characters , - /
+- Predefined definitions (@yearly, @monthly, @weekly, @daily, @midnight, @hourly)
 
 ## Contributing
 

data/cron_calc.gemspec

@@ -8,8 +8,9 @@ Gem::Specification.new do |spec|
   spec.authors = ['Jakub Miziński']
   spec.email = ['jakubmizinski@gmail.com']
 
-  spec.summary = 'calculates cron job occurrences'
-  spec.description = 'calculates cron job occurrences within a specified period'
+  spec.summary = 'Calculates cron job occurrences'
+  spec.description = 'Calculates cron job occurrences within a specified period
+                      or determines next/last "n" occurrences based on a specified time.'
   spec.homepage = 'https://github.com/mizinsky/cron_calc'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 2.6.0'
@@ -30,10 +31,4 @@ Gem::Specification.new do |spec|
   spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
-
-  # Uncomment to register a new dependency of your gem
-  spec.add_dependency 'rspec', '~> 3.12'
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
 end

data/lib/cron_calc/version.rb

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

data/lib/cron_calc.rb

@@ -7,41 +7,85 @@ require 'time'
 module CronCalc
   class Error < StandardError; end
 
-  def self.new(cron_string, period)
-    Parser.new(cron_string, period)
+  def self.new(cron_string)
+    Parser.new(cron_string)
   end
 
   # The Parser class provides functionality to parse and calculate occurrences
   # of cron jobs within a given time period. It interprets cron strings and
   # calculates when cron jobs will occur
   class Parser
-    attr_reader :cron_string, :cron_parts, :period
+    attr_reader :cron_string, :cron_parts
 
     RANGE = {
       minutes: 0..59,
       hours: 0..23,
       days: 1..31,
-      months: 1..12
+      months: 1..12,
+      dows: 0..7
     }.freeze
 
-    def initialize(cron_string, period)
+    def initialize(cron_string)
       @cron_string = cron_string
-      @period = period
+
+      raise 'Cron expression is not supported or invalid' unless cron_string_valid?
+
       @cron_parts = split_cron_string
     end
 
-    def occurrences
-      raise 'Cron expression is not supported or invalid' unless cron_string_valid?
+    # 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.
+    def in(period)
+      occurrences(period)
+    end
+
+    # 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 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)
+      occurrences(
+        period_start..(period_start + (60 * 60 * 24 * 365 * max_years)),
+        count
+      )
+    end
 
-      minutes, hours, days, months, years = parse_cron_expression
+    # 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.
+    def last(count = 1, period_end = Time.now, max_years = 5)
+      occurrences(
+        (period_end - (60 * 60 * 24 * 365 * max_years))..period_end,
+        count,
+        reverse: true
+      )
+    end
+
+    private
+
+    def occurrences(period, count = nil, reverse: false)
+      time_combinations = generate_time_combinations(period, reverse).lazy
+      wdays = parse_cron_part(:dows)
+
+      time_combinations.each_with_object([]) do |(year, month, day, hour, minute), occ|
+        break occ if count && occ.length == count
 
-      years.product(months, days, hours, minutes).each_with_object([]) do |(year, month, day, hour, minute), occ|
         time = Time.new(year, month, day, hour, minute)
-        occ << time if Date.valid_date?(year, month, day) && period.include?(time)
+        occ << time if Date.valid_date?(year, month, day) && period.include?(time) && wdays.include?(time.wday)
       end
     end
 
-    private
+    def generate_time_combinations(period, reverse)
+      minutes, hours, days, months = parse_cron_expression
+      years = (period.min.year..period.max.year).to_a
+
+      combinations = years.product(months, days, hours, minutes)
+      reverse ? combinations.reverse : combinations
+    end
 
     def split_cron_string
       splitted = cron_string.split
@@ -50,12 +94,13 @@ module CronCalc
         minutes: splitted[0],
         hours: splitted[1],
         days: splitted[2],
-        months: splitted[3]
+        months: splitted[3],
+        dows: splitted[4]
       }
     end
 
     def parse_cron_expression
-      %i[minutes hours days months].map { |unit| parse_cron_part(unit) } << (period.min.year..period.max.year).to_a
+      %i[minutes hours days months].map { |unit| parse_cron_part(unit) }
     end
 
     # rubocop:disable Metrics
@@ -80,7 +125,7 @@ module CronCalc
 
     def cron_string_valid?
       # 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+)) \*\z}
+      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}
       # rubocop:enable Layout/LineLength
       cron_string.match?(regex)
     end

metadata

@@ -1,30 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: cron_calc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jakub Miziński
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-12-18 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.12'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.12'
-description: calculates cron job occurrences within a specified period
+date: 2023-12-22 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Calculates cron job occurrences within a specified period
+                        or determines next/last "n" occurrences based on a specified time.
 email:
 - jakubmizinski@gmail.com
 executables: []
@@ -64,8 +52,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.1
 signing_key: 
 specification_version: 4
-summary: calculates cron job occurrences
+summary: Calculates cron job occurrences
 test_files: []