fugit 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0099e4aa474e4886e99da33f4b76abd19f259d3a6eb64cd2bfe12f99f6256a23'
-  data.tar.gz: 38c3fbe7b620cc6460f1b7b7d3e96298400c82d7dec7ef9d4b543925dff6e74a
+  metadata.gz: d32bc8cbff08c0ca8fe2c2037454ca76c208878f26d71398cd46a93729958248
+  data.tar.gz: ce7d21ce4265c59def186f0e28271def0b74724c99c46814443182039f26cba1
 SHA512:
-  metadata.gz: 75e41e393e779e06ec6280e6e2065877b4771fcca8b63307af13f7fe2407fc9a1fef75eca5a690fe9f3cec6b791deaa4c8b23c925326b24753c5ae8197d5a5bd
-  data.tar.gz: e9ac1c2b0412a9e2549257b1d73490f4319335c847a6faff212dd8c8a9cbaa52787617491d76648763efbd24caffc39a91e08f06910970905dc810ef9fec36cc
+  metadata.gz: fe8facb5f36dd89ec4e03994c6474f3a6e8de371f05322b8c7983d2d9d8769889b475e35a2d0bcc74fb04b59f96ca857a16ffb6a3db50db41a36beff48c57c39
+  data.tar.gz: d928deee88172c20c15e6960bddfd30b77f3eb7fb0e0edd322baa9ce54932fe476afc7a21985fe3cc65dff3507acd29540f88b51ae27f3e458d060f083a11628

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 # CHANGELOG.md
 
 
+## fugit 1.10.0 released 2024-02-22
+
+* Implement `Fugit::Cron#within(time_start, time_end)`
+* Implement `Fugit::Cron#within(time_range)`
+* Implement iterator-returning `Fugit::Cron#next` and `#prev`
+
+
 ## fugit 1.9.0 released 2023-10-24
 
 * Let nat parse "last", gh-88

data/LICENSE.txt

@@ -1,5 +1,5 @@
 
-Copyright (c) 2017-2023, John Mettraux, jmettraux+flor@gmail.com
+Copyright (c) 2017-2024, John Mettraux, jmettraux+flor@gmail.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -26,17 +26,21 @@ The intersection of those two projects is where fugit is born:
 * [parse-cron](https://github.com/siebertm/parse-cron) - parses cron expressions and calculates the next occurrence after a given date
 * [ice_cube](https://github.com/seejohnrun/ice_cube) - Ruby date recurrence library
 * [ISO8601](https://github.com/arnau/ISO8601) - Ruby parser to work with ISO8601 dateTimes and durations
+* [chrono](https://github.com/r7kamura/chrono) - a chain of logics about chronology
+* [CronCalc](https://github.com/mizinsky/cron_calc) - calculates cron job occurrences
+* [Recurrence](https://github.com/fnando/recurrence) - a simple library to handle recurring events
 * ...
 
 ### Projects using fugit
 
 * [arask](https://github.com/Ebbe/arask) - "Automatic RAils taSKs" uses fugit to parse cron strings
 * [sidekiq-cron](https://github.com/ondrejbartas/sidekiq-cron) - recent versions of Sidekiq-Cron use fugit to parse cron strings
-* [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) -
+* [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) - as seen above
 * [flor](https://github.com/floraison/flor) - used in the [cron](https://github.com/floraison/flor/blob/master/doc/procedures/cron.md) procedure
 * [que-scheduler](https://github.com/hlascelles/que-scheduler) - a reliable job scheduler for [que](https://github.com/chanks/que)
 * [serial_scheduler](https://github.com/grosser/serial_scheduler) - ruby task scheduler without threading
 * [delayed_cron_job](https://github.com/codez/delayed_cron_job) - an extension to Delayed::Job that allows you to set cron expressions for your jobs
+* [GoodJob](https://github.com/bensheldon/good_job) - a multithreaded, Postgres-based, Active Job backend for Ruby on Rails
 * ...
 
 ## `Fugit.parse(s)`
@@ -92,7 +96,7 @@ As `Fugit.parse(s)` returns nil when it doesn't grok its input, and `Fugit.do_pa
 
 Sometimes you know a cron expression or an "every" natural expression will come in and you want to discard the rest.
 
-```
+```ruby
 require 'fugit'
 
 Fugit.parse_cronish('0 0 1 jan *').class             # ==> ::Fugit::Cron
@@ -122,8 +126,44 @@ c = Fugit::Cron.new('0 0 * *  sun')
 
 p Time.now  # => 2017-01-03 09:53:27 +0900
 
-p c.next_time      # => 2017-01-08 00:00:00 +0900
-p c.previous_time  # => 2017-01-01 00:00:00 +0900
+p c.next_time.to_s      # => 2017-01-08 00:00:00 +0900
+p c.previous_time.to_s  # => 2017-01-01 00:00:00 +0900
+
+p c.next_time(Time.parse('2024-06-01')).to_s
+  # => "2024-06-02 00:00:00 +0900"
+p c.previous_time(Time.parse('2024-06-01')).to_s
+  # => "2024-05-26 00:00:00 +0900"
+    #
+    # `Fugit::Cron#next_time` and `#previous_time` accept a "start time"
+
+c = Fugit.parse_cron('0 12 * * mon#2')
+
+  # `#next` and `#prev` return Enumerable instances
+  #
+c.next(Time.parse('2024-02-16 12:00:00'))
+  .take(3)
+  .map(&:to_s)
+    # => [ '2024-03-11 12:00:00',
+    #      '2024-04-08 12:00:00',
+    #      '2024-05-13 12:00:00' ]
+c.prev(Time.parse('2024-02-16 12:00:00'))
+  .take(3)
+  .map(&:to_s)
+    # => [ '2024-02-12 12:00:00',
+    #      '2024-01-08 12:00:00',
+    #      '2023-12-11 12:00:00' ]
+
+  # `#within` accepts a time range and returns an array of Eo::EoTime
+  # instances that correspond to the occurrences of the cron within
+  # the time range
+  #
+c.within(Time.parse('2024-02-16 12:00')..Time.parse('2024-08-01 12:00'))
+  .map(&:to_s)
+    # => [ '2024-03-11 12:00:00',
+    #      '2024-04-08 12:00:00',
+    #      '2024-05-13 12:00:00',
+    #      '2024-06-10 12:00:00',
+    #      '2024-07-08 12:00:00' ]
 
 p c.brute_frequency  # => [ 604800, 604800, 53 ]
                      #    [ delta min, delta max, occurrence count ]
@@ -268,6 +308,18 @@ c.match?('2019-01-08')  # => false, since (rweek + 1) % 2 == 1
 `tue%x+y` matches if Tuesday and `current_date.rweek + y % x == 0`
 
 
+### the second extension
+
+Fugit accepts cron strings with five elements, `minute hour day-of-month month day-of-week`, the standard cron format or six elements `second minute hour day-of-month month day-of-week`.
+
+```ruby
+c = Fugit.parse('* * * * *') # every minute
+c = Fugit.parse('5 * * * *') # every hour at minute 5
+c = Fugit.parse('* * * * * *') # every second
+c = Fugit.parse('5 * * * * *') # every minute at second 5
+```
+
+
 ## `Fugit::Duration`
 
 A class `Fugit::Duration` to parse duration strings (vanilla [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) ones and [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ones).
@@ -401,7 +453,8 @@ Fugit::Nat.parse('every day at 16:15 and 18:30', multi: true)
     # ==> [ '15 16 * * *', '30 18 * * *' ] (two Fugit::Cron instances)
 
 Fugit::Nat.parse('every day at 16:15 and 18:30', multi: :fail)
-  # ==> ArgumentError: multiple crons in "every day at 16:15 and 18:30" (15 16 * * * | 30 18 * * *)
+  # ==> ArgumentError: multiple crons in "every day at 16:15 and 18:30"
+  #     (15 16 * * * | 30 18 * * *)
 Fugit::Nat.parse('every day at 16:15 nada 18:30', multi: true)
   # ==> nil
 ```

data/lib/fugit/cron.rb

@@ -318,6 +318,53 @@ module Fugit
       t.time.translate(from.zone)
     end
 
+    # Used by Fugit::Cron#next and Fugit::Cron#prev
+    #
+    class CronIterator include ::Enumerable
+      attr_reader :cron, :start, :current, :direction
+      def initialize(cron, direction, start)
+        @cron = cron
+        @start = start
+        @current = start.dup
+        @direction = direction
+      end
+      def each
+        loop do
+          yield(@current = @cron.send(@direction, @current))
+        end
+      end
+    end
+
+    # Returns an ::Enumerable instance that yields each "next time" in
+    # succession
+    #
+    def next(from=::EtOrbi::EoTime.now)
+
+      CronIterator.new(self, :next_time, from)
+    end
+
+    # Returns an ::Enumerable instance that yields each "previous time" in
+    # succession
+    #
+    def prev(from=::EtOrbi::EoTime.now)
+
+      CronIterator.new(self, :previous_time, from)
+    end
+
+    # Returns an array of EtOrbi::EoTime instances that correspond to
+    # the occurrences of the cron within the given time range
+    #
+    def within(time_range, time_end=nil)
+
+      sta, ned =
+        time_range.is_a?(::Range) ? [ time_range.begin, time_range.end ] :
+        [ ::EtOrbi.make_time(time_range), ::EtOrbi.make_time(time_end) ]
+
+      CronIterator
+        .new(self, :next_time, sta)
+        .take_while { |eot| eot.to_t < ned }
+    end
+
     # Mostly used as a #next_time sanity check.
     # Avoid for "business" use, it's slow.
     #

data/lib/fugit.rb

@@ -3,7 +3,7 @@
 
 module Fugit
 
-  VERSION = '1.9.0'
+  VERSION = '1.10.0'
 end
 
 require 'time'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fugit
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - John Mettraux
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-23 00:00:00.000000000 Z
+date: 2024-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: raabro