README.md in fugit-1.9.0 vs README.md in fugit-1.10.0
- old
+ new
@@ -24,21 +24,25 @@
* [chronic](https://github.com/mojombo/chronic) - a pure Ruby natural language date parser
* [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)`
The simplest way to use fugit is via `Fugit.parse(s)`.
@@ -90,11 +94,11 @@
## parse_cronish and do_parse_cronish
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
Fugit.parse_cronish('every saturday at noon').class # ==> ::Fugit::Cron
@@ -120,13 +124,49 @@
# or
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 ]
p c.rough_frequency # => 7 * 24 * 3600 (7d rough frequency)
p c.match?(Time.parse('2017-08-06')) # => true
@@ -266,10 +306,22 @@
`sun%2` matches if Sunday and `current_date.rweek % 2 == 0`
`tue%3+2` matches if Tuesday and `current_date.rweek + 2 % 3 == 0`
`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).
Provides duration arithmetic tools.
@@ -399,10 +451,11 @@
Fugit::Nat.parse('every day at 16:15 and 18:30', multi: true)
.collect(&:to_cron_s)
# ==> [ '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
```
`multi: true` indicates to `Fugit::Nat` that an array of `Fugit::Cron` instances is expected as a result.