fugit 1.12.3 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f588451db0cf7643afd0ecd89313863b4ca89913872547f0dd8342343fec1b57
-  data.tar.gz: a0832d2aecbe4b158a3deef01ac7c230cd8de3ff2c3dc5a1da4e871a516d27c6
+  metadata.gz: 15c7da961f6616177b4837e7db2b8d2cbef8a73af0e39d482bbde88ca927d420
+  data.tar.gz: bdb787682ba39f3bd873c935378d7097291ff275c9c2443a4bf42990e71dfa92
 SHA512:
-  metadata.gz: 5fca6043aef60a7c895b991f364714f1d26f3ef0922d477fc624a4f4cdc51dc948542fca4638567e2416fa4ff4c75e267f03991d7624f2515745d8e8be203314
-  data.tar.gz: 8ddb37f7d0f961dc341757fff83ef1cf844df7a7ffc7aaedc1eed0dca6fea4be217029e2a266cb8ce774303e174f4e27713854b4058cf6f12b3c2aa6eb78d1ca
+  metadata.gz: c920de689a07b8e5b082afa2d67ff26a2ad3422e0a35afc0c02fee71d92d6a76da391d7ec6d03e55d62cbc1a46cbf1296bccb4a37ec9df9d72f35d3e4ecaf0ad
+  data.tar.gz: 11694200215f7506f64f862d7f63e86b3fc79be5ad4a4ddfe9278143c40991bcd2c89356e9e314d5caad125b0b26623daf3da64ee2e92b49ca1480b59fc220f3

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 # CHANGELOG.md
 
 
+## fugit 1.13.0 released 2026-07-10
+
+* Random values support in cron string `"10 ~ * * *"` gh-121 Nicols Bachschmidt
+
+
 ## fugit 1.12.3 released 2026-07-01
 
 * Wrap-around for weekday ranges with step value, gh-119 Nicolas Bachschmidt

data/CREDITS.md

@@ -8,7 +8,7 @@
 * Mark R. James, https://github.com/mrj, AM vs America/Los_Angeles, gh-113
 * Tejas Bubane, https://github.com/tejasbubane, r3.4 in test matrix, gh-109
 * Luis Castillo, https://github.com/lekastillo, nice_hash gh-108
-* Geremia Taglialatela, https://github.com/tagliala, gh-105 gh-107
+* Geremia Taglialatela, https://github.com/tagliala, gh-105 gh-107 gh-122
 * https://github.com/personnumber3377, gh-104 Fugit.parse choke on long input
 * Michael Scrivo, https://github.com/mscrivo, gh-103
 * Benjamin Darcet, https://github.com/bdarcet gh-95 gh-96 et-orbi #rweek

data/README.md

@@ -486,6 +486,29 @@ Here's the output:
 ```
 
 
+### the random extension
+
+Fugit accepts the `~` character to specify a range from which a random value is picked. Either or both the start and the end of the range may be omitted.
+
+```ruby
+'~ * * * *'    # every hour on a random minute
+'~29 * * * *'  # every hour on a random minute between 0 and 29
+'30~ * * * *'  # every hour on a random minute between 30 and 59
+'~/10 * * * *' # every 10 minutes starting on a random minute between 0 and 9
+'0 12 * * 1~5' # every week at noon on a random workday
+```
+
+You may customize how random values are generated by adding the `:random` option with a boolean or an object that implements the `#rand` method.
+
+```ruby
+Fugit.parse('~ * * * *', random: false)        # on a non-random minute ==> '0 * * * *'
+Fugit.parse('~ * * * *', random: true)         # on a random minute (default)
+Fugit.parse('~ * * * *', random: SecureRandom) # on a cryptographically secure random minute
+```
+
+Please note that the random values are determined at parse time. So `"~29 * * * *"` at parse time could become `"17 * * * *"` for example and go on triggering every hour at minute 17, until a new parsing occurs and another (or the same) minute is picked. This aligns with the OpenBSD [`man 5 crontab`](https://man.openbsd.org/crontab.5), OpenBSD `crond` rolling the dice at load time.
+
+
 ### 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`.

data/fugit.gemspec

@@ -45,6 +45,7 @@ Time tools for flor and the floraison project. Cron parsing and occurrence compu
 
   s.add_development_dependency 'rspec', '~> 3.8'
   s.add_development_dependency 'chronic', '~> 0.10'
+  s.add_development_dependency 'ostruct'
 
   s.require_path = 'lib'
 end

data/lib/fugit/cron.rb

@@ -29,7 +29,7 @@ module Fugit
         parse(original)
       end
 
-      def parse(s)
+      def parse(s, opts={})
 
         return s if s.is_a?(self)
         return nil unless s.is_a?(String)
@@ -48,12 +48,12 @@ module Fugit
 #p s; Raabro.pp(Parser.parse(s, debug: 3), colors: true)
         h = Parser.parse(s)
 
-        self.allocate.send(:init, s0, h)
+        self.allocate.send(:init, s0, h, opts)
       end
 
-      def do_parse(s)
+      def do_parse(s, opts={})
 
-        parse(s) ||
+        parse(s, opts) ||
         fail(ArgumentError.new("invalid cron string #{trunc(s)}"))
       end
 
@@ -559,7 +559,7 @@ module Fugit
 
     FREQUENCY_CACHE = {}
 
-    def init(original, h)
+    def init(original, h, opts)
 
       return nil unless h
 
@@ -568,12 +568,12 @@ module Fugit
       @day_and = h[:&]
 
       valid =
-        determine_seconds(h[:sec]) &&
-        determine_minutes(h[:min]) &&
-        determine_hours(h[:hou]) &&
-        determine_monthdays(h[:dom]) &&
-        determine_months(h[:mon]) &&
-        determine_weekdays(h[:dow]) &&
+        determine_seconds(h[:sec], opts) &&
+        determine_minutes(h[:min], opts) &&
+        determine_hours(h[:hou], opts) &&
+        determine_monthdays(h[:dom], opts) &&
+        determine_months(h[:mon], opts) &&
+        determine_weekdays(h[:dow], opts) &&
         determine_timezone(h[:tz])
 
       return nil unless valid
@@ -582,9 +582,9 @@ module Fugit
       self
     end
 
-    def expand(min, max, r)
+    def expand(min, max, opts, r)
 
-      sta, edn, sla = r
+      sta, edn, sep, sla = r
 
       #return false if sla && sla > max
         #
@@ -593,6 +593,11 @@ module Fugit
 
       return false if sla && sla < 1
 
+      if sep == :tilde
+        sta = random(min, max, sta, edn, sla, opts)
+        edn = nil unless sla
+      end
+
       edn = max if sla && edn.nil?
 
       return nil if sta.nil? && edn.nil? && sla.nil?
@@ -605,6 +610,24 @@ module Fugit
       range(min, max, sta, edn, sla)
     end
 
+    def random(min, max, sta, edn, sla, opts)
+
+      sta = min if sta.nil?
+      edn = max if edn.nil?
+
+      random = opts.fetch(:random, true)
+      random = Random if random == true
+      return sta unless random
+
+      n = edn - sta + 1
+      n = max - min + 1 + n if n <= 0
+      n = sla if sla && sla < n
+
+      r = sta + random.rand(n)
+      r = r + min - max - 1 if r > max
+      r
+    end
+
     def range(min, max, sta, edn, sla)
 
       return [ nil ] if sta == min && edn == max && sla == 1
@@ -647,13 +670,13 @@ module Fugit
         .uniq
     end
 
-    def do_determine(key, arr, min, max)
+    def do_determine(key, arr, min, max, opts)
 
       null = false
 
       r = arr
         .collect { |v|
-          expand(min, max, v) }
+          expand(min, max, opts, v) }
         .flatten(1)
         .collect { |e|
           return false if e == false
@@ -664,31 +687,36 @@ module Fugit
       r.uniq.sort
     end
 
-    def determine_seconds(arr)
-      (@seconds = do_determine(:seconds, arr || [ 0 ], 0, 59)) != false
+    def determine_seconds(arr, opts)
+      (@seconds = do_determine(:seconds, arr || [ 0 ], 0, 59, opts)) != false
     end
 
-    def determine_minutes(arr)
-      (@minutes = do_determine(:minutes, arr, 0, 59)) != false
+    def determine_minutes(arr, opts)
+      (@minutes = do_determine(:minutes, arr, 0, 59, opts)) != false
     end
 
-    def determine_hours(arr)
-      (@hours = do_determine(:hours, arr, 0, 23)) != false
+    def determine_hours(arr, opts)
+      (@hours = do_determine(:hours, arr, 0, 23, opts)) != false
     end
 
-    def determine_monthdays(arr)
-      (@monthdays = do_determine(:monthdays, arr, 1, 31)) != false
+    def determine_monthdays(arr, opts)
+      (@monthdays = do_determine(:monthdays, arr, 1, 31, opts)) != false
     end
 
-    def determine_months(arr)
-      (@months = do_determine(:months, arr, 1, 12)) != false
+    def determine_months(arr, opts)
+      (@months = do_determine(:months, arr, 1, 12, opts)) != false
     end
 
-    def determine_weekdays(arr)
+    def determine_weekdays(arr, opts)
 
       @weekdays = []
 
-      arr.each do |a, z, sl, ha, mo| # a to z, slash, hash, and mod
+      arr.each do |a, z, sp, sl, ha, mo| # a to z, seperator, slash, hash, and mod
+        if sp == :tilde
+          a = random(0, 6, a, z, sl, opts)
+          z = nil unless sl
+        end
+
         if ha || mo
           @weekdays << [ a, ha || mo ]
         elsif sl
@@ -759,7 +787,8 @@ module Fugit
 
       def s(i); rex(nil, i, /[ \t]+/); end
       def star(i); str(nil, i, '*'); end
-      def hyphen(i); str(nil, i, '-'); end
+      def hyphen(i); str(:hyphen, i, '-'); end
+      def tilde(i); str(:tilde, i, '~'); end
       def comma(i); rex(nil, i, /,([ \t]*,)*/); end
       def comma?(i); rex(nil, i, /([ \t]*,)*/); end
       def and?(i); rex(nil, i, /&?/); end
@@ -787,12 +816,19 @@ module Fugit
       def r_mon(i); seq(nil, i, :mon, :_mon, '?'); end
       def r_dow(i); seq(nil, i, :dow, :_dow, '?'); end
 
+      # t: tilde range
+      def t_mos(i); seq(nil, i, :mos, '?', :tilde, :mos, '?'); end
+      def t_hou(i); seq(nil, i, :hou, '?', :tilde, :hou, '?'); end
+      def t_dom(i); seq(nil, i, :dom, '?', :tilde, :dom, '?'); end
+      def t_mon(i); seq(nil, i, :mon, '?', :tilde, :mon, '?'); end
+      def t_dow(i); seq(nil, i, :dow, '?', :tilde, :dow, '?'); end
+
       # sor: star or range
-      def sor_mos(i); alt(nil, i, :star, :r_mos); end
-      def sor_hou(i); alt(nil, i, :star, :r_hou); end
-      def sor_dom(i); alt(nil, i, :star, :r_dom); end
-      def sor_mon(i); alt(nil, i, :star, :r_mon); end
-      def sor_dow(i); alt(nil, i, :star, :r_dow); end
+      def sor_mos(i); alt(nil, i, :star, :t_mos, :r_mos); end
+      def sor_hou(i); alt(nil, i, :star, :t_hou, :r_hou); end
+      def sor_dom(i); alt(nil, i, :star, :t_dom, :r_dom); end
+      def sor_mon(i); alt(nil, i, :star, :t_mon, :r_mon); end
+      def sor_dow(i); alt(nil, i, :star, :t_dow, :r_dow); end
 
       # sorws: star or range with[out] slash
       def sorws_mos(i); seq(nil, i, :sor_mos, :slash, '?'); end
@@ -872,12 +908,16 @@ module Fugit
 
       def rewrite_elt(k, t)
 
-        at, zt, slt, hat, mot = nil; t.subgather(nil).each do |tt|
+        at, zt, spt, slt, hat, mot = nil
+
+        t.subgather(nil).each do |tt|
           case tt.name
           when :slash then slt = tt
           when :hash then hat = tt
           when :mod then mot = tt
-          else if at; zt ||= tt; else; at = tt; end
+          when :hyphen then spt = tt
+          when :tilde then spt = tt
+          else if spt; zt ||= tt; else; at = tt; end
           end
         end
 
@@ -891,11 +931,12 @@ module Fugit
 
         a = at ? rewrite_bound(k, at) : nil
         z = zt ? rewrite_bound(k, zt) : nil
+        sp = spt ? spt.name : nil
 
         #a, z = z, a if a && z && a > z
           # handled downstream since gh-27
 
-        [ a, z, sl, ha, mo ]
+        [ a, z, sp, sl, ha, mo ]
       end
 
       def rewrite_entry(t)

data/lib/fugit/nat.rb

@@ -710,7 +710,7 @@ module Fugit
             e.uniq.sort_by(&letters_last).collect(&:to_s).join(',') }
           .join(' ')
 
-        c = Fugit::Cron.parse(s)
+        c = Fugit::Cron.parse(s, opts)
 
         if opts[:strict]
           restrict(a, c)

data/lib/fugit/parse.rb

@@ -6,13 +6,13 @@ module Fugit
 
   class << self
 
-    def parse_cron(s); ::Fugit::Cron.parse(s); end
+    def parse_cron(s, opts={}); ::Fugit::Cron.parse(s, opts || {}); end
     def parse_duration(s); ::Fugit::Duration.parse(s); end
     def parse_nat(s, opts={}); ::Fugit::Nat.parse(s, opts || {}); end
     def parse_at(s, opts={}); ::Fugit::At.parse(s, opts || {}); end
     def parse_in(s); parse_duration(s); end
 
-    def do_parse_cron(s); ::Fugit::Cron.do_parse(s); end
+    def do_parse_cron(s, opts={}); ::Fugit::Cron.do_parse(s, opts || {}); end
     def do_parse_duration(s); ::Fugit::Duration.do_parse(s); end
     def do_parse_nat(s, opts={}); ::Fugit::Nat.do_parse(s, opts || {}); end
     def do_parse_at(s); ::Fugit::At.do_parse(s); end
@@ -22,7 +22,7 @@ module Fugit
 
       opts[:at] = opts[:in] if opts.has_key?(:in)
 
-      (opts[:cron] != false && parse_cron(s)) || # 542ms 616ms
+      (opts[:cron] != false && parse_cron(s, opts || {})) || # 542ms 616ms
       (opts[:duration] != false && parse_duration(s)) || # 645ms # 534ms
       (opts[:nat] != false && parse_nat(s, opts || {})) || # 2s # 35s
       (opts[:at] != false && parse_at(s, opts || {})) || # 568ms 622ms
@@ -54,14 +54,14 @@ module Fugit
 
     def parse_cronish(s, opts={})
 
-      r = parse_cron(s) || parse_nat(s, opts)
+      r = parse_cron(s, opts) || parse_nat(s, opts)
 
       r.is_a?(::Fugit::Cron) ? r : nil
     end
 
     def do_parse_cronish(s, opts={})
 
-      parse_cronish(s) ||
+      parse_cronish(s, opts) ||
       fail(ArgumentError.new("not cron or 'natural' cron string: #{s.inspect}"))
     end
 

data/lib/fugit.rb

@@ -3,7 +3,7 @@
 
 module Fugit
 
-  VERSION = '1.12.3'
+  VERSION = '1.13.0'
 end
 
 require 'time'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fugit
 version: !ruby/object:Gem::Version
-  version: 1.12.3
+  version: 1.13.0
 platform: ruby
 authors:
 - John Mettraux
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: raabro
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Time tools for flor and the floraison project. Cron parsing and occurrence
   computing. Timestamps and more.
 email: