class Fugit::Cron

Constants

FREQUENCY_CACHE
MAXDAYS
MAX_ITERATION_COUNT
SLOTS
SPECIALS

Attributes

hours[R]
minutes[R]
monthdays[R]
months[R]
original[R]
seconds[R]
timezone[R]
weekdays[R]
zone[R]

Public Class Methods

do_parse(s) click to toggle source
# File lib/fugit/cron.rb, line 48
def do_parse(s)

  parse(s) ||
  fail(ArgumentError.new("invalid cron string #{s.inspect}"))
end
new(original) click to toggle source
# File lib/fugit/cron.rb, line 27
def new(original)

  parse(original)
end
parse(s) click to toggle source
# File lib/fugit/cron.rb, line 32
      def parse(s)

        return s if s.is_a?(self)

        s = SPECIALS[s] || s

        return nil unless s.is_a?(String)

#p s; Raabro.pp(Parser.parse(s, debug: 3), colors: true)
        h = Parser.parse(s)

        return nil unless h

        self.allocate.send(:init, s, h)
      end

Public Instance Methods

==(o) click to toggle source
# File lib/fugit/cron.rb, line 423
def ==(o)

  o.is_a?(::Fugit::Cron) && o.to_a == to_a
end
Also aliased as: eql?
brute_frequency(year=2017) click to toggle source

Mostly used as a next_time sanity check. Avoid for “business” use, it's slow.

2017 is a non leap year (though it is preceded by a leap second on 2016-12-31)

Nota bene: cron with seconds are not supported.

# File lib/fugit/cron.rb, line 321
def brute_frequency(year=2017)

  FREQUENCY_CACHE["#{to_cron_s}|#{year}"] ||=
    begin

      deltas = []

      t = EtOrbi.make_time("#{year}-01-01") - 1
      t0 = nil
      t1 = nil

      loop do
        t1 = next_time(t)
        deltas << (t1 - t).to_i if t0
        t0 ||= t1
        break if deltas.any? && t1.year > year
        break if t1.year - t0.year > 7
        t = t1
      end

      Frequency.new(deltas, t1 - t0)
    end
end
day_match?(nt) click to toggle source
# File lib/fugit/cron.rb, line 198
def day_match?(nt)

  return weekday_match?(nt) || monthday_match?(nt) \
    if @weekdays && @monthdays
      #
      # From `man 5 crontab`
      #
      # Note: The day of a command's execution can be specified
      # by two fields -- day of month, and day of week.
      # If both fields are restricted (ie, are not *), the command will be
      # run when either field matches the current time.
      # For example, ``30 4 1,15 * 5'' would cause a command to be run
      # at 4:30 am on the 1st and 15th of each month, plus every Friday.
      #
      # as seen in gh-5 and gh-35

  return false unless weekday_match?(nt)
  return false unless monthday_match?(nt)

  true
end
eql?(o)
Alias for: ==
hash() click to toggle source
# File lib/fugit/cron.rb, line 429
def hash

  to_a.hash
end
hour_match?(nt) click to toggle source
# File lib/fugit/cron.rb, line 151
def hour_match?(nt); ( ! @hours) || @hours.include?(nt.hour); end
match?(t) click to toggle source
# File lib/fugit/cron.rb, line 220
def match?(t)

  t = Fugit.do_parse_at(t).translate(@timezone)

  month_match?(t) && day_match?(t) &&
  hour_match?(t) && min_match?(t) && sec_match?(t)
end
min_match?(nt) click to toggle source
# File lib/fugit/cron.rb, line 152
def min_match?(nt); ( ! @minutes) || @minutes.include?(nt.min); end
month_match?(nt) click to toggle source
# File lib/fugit/cron.rb, line 150
def month_match?(nt); ( ! @months) || @months.include?(nt.month); end
monthday_match?(nt) click to toggle source
# File lib/fugit/cron.rb, line 187
def monthday_match?(nt)

  return true if @monthdays.nil?

  last = (TimeCursor.new(self, nt).inc_month.time - 24 * 3600).day + 1

  @monthdays
    .collect { |d| d < 1 ? last + d : d }
    .include?(nt.day)
end
next_time(from=::EtOrbi::EoTime.now) click to toggle source

See gh-15 and tst/iteration_count.rb

Initially set to 1024 after seeing the worst case for next_time at 167 iterations, I placed it at 2048 after experimenting with gh-18 and noticing some > 1024 for some experiments. 2048 should be ok.

# File lib/fugit/cron.rb, line 237
def next_time(from=::EtOrbi::EoTime.now)

  from = ::EtOrbi.make_time(from)
  sfrom = from.strftime('%F|%T')
  ifrom = from.to_i

  i = 0
  t = TimeCursor.new(self, from.translate(@timezone))
    #
    # the translation occurs in the timezone of
    # this Fugit::Cron instance

  zfrom = t.time.strftime('%z|%Z')

  loop do

    fail RuntimeError.new(
      "too many loops for #{@original.inspect} #next_time, breaking, " +
      "cron expression most likely invalid (Feb 30th like?), " +
      "please fill an issue at https://git.io/fjJC9"
    ) if (i += 1) > MAX_ITERATION_COUNT

    (ifrom == t.to_i) && (t.inc(1); next)
    month_match?(t) || (t.inc_month; next)
    day_match?(t) || (t.inc_day; next)
    hour_match?(t) || (t.inc_hour; next)
    min_match?(t) || (t.inc_min; next)
    sec_match?(t) || (t.inc_sec; next)

    tt = t.time
    st = tt.strftime('%F|%T')
    zt = tt.strftime('%z|%Z')
      #
    if st == sfrom && zt != zfrom
      from, sfrom, zfrom, ifrom = tt, st, zt, t.to_i
      next
    end
      #
      # when transitioning out of DST, this prevents #next_time from
      # yielding the same literal time twice in a row, see gh-6

    break
  end

  t.time.translate(from.zone)
    #
    # the answer time is in the same timezone as the `from`
    # starting point
end
previous_time(from=::EtOrbi::EoTime.now) click to toggle source
# File lib/fugit/cron.rb, line 287
def previous_time(from=::EtOrbi::EoTime.now)

  from = ::EtOrbi.make_time(from)

  i = 0
  t = TimeCursor.new(self, (from - 1).translate(@timezone))

  loop do

    fail RuntimeError.new(
      "too many loops for #{@original.inspect} #previous_time, breaking, " +
      "cron expression most likely invalid (Feb 30th like?), " +
      "please fill an issue at https://git.io/fjJCQ"
    ) if (i += 1) > MAX_ITERATION_COUNT

    month_match?(t) || (t.dec_month; next)
    day_match?(t) || (t.dec_day; next)
    hour_match?(t) || (t.dec_hour; next)
    min_match?(t) || (t.dec_min; next)
    sec_match?(t) || (t.dec_sec; next)
    break
  end

  t.time.translate(from.zone)
end
rough_frequency() click to toggle source
# File lib/fugit/cron.rb, line 351
def rough_frequency

  slots = SLOTS
    .collect { |k, v0, v1|
      a = (k == :days) ? rough_days : instance_variable_get("@#{k}")
      [ k, v0, v1, a ] }

  slots.each do |k, v0, _, a|
    next if a == [ 0 ]
    break if a != nil
    return v0 if a == nil
  end

  slots.each do |k, v0, v1, a|
    next unless a && a.length > 1
    return (a + [ a.first + v1 ])
      .each_cons(2)
      .collect { |a0, a1| a1 - a0 }
      .select { |d| d > 0 } # weed out zero deltas
      .min * v0
  end

  slots.reverse.each do |k, v0, v1, a|
    return v0 * v1 if a && a.length == 1
  end

  1 # second
end
sec_match?(nt) click to toggle source
# File lib/fugit/cron.rb, line 153
def sec_match?(nt); ( ! @seconds) || @seconds.include?(nt.sec); end
to_a() click to toggle source
# File lib/fugit/cron.rb, line 408
def to_a

  [ @seconds, @minutes, @hours, @monthdays, @months, @weekdays ]
end
to_cron_s() click to toggle source
# File lib/fugit/cron.rb, line 55
def to_cron_s

  @cron_s ||= [
    @seconds == [ 0 ] ? nil : (@seconds || [ '*' ]).join(','),
    (@minutes || [ '*' ]).join(','),
    (@hours || [ '*' ]).join(','),
    (@monthdays || [ '*' ]).join(','),
    (@months || [ '*' ]).join(','),
    (@weekdays || [ [ '*' ] ]).map { |d| d.compact.join('#') }.join(','),
    @timezone ? @timezone.name : nil
      ].compact.join(' ')
end
to_h() click to toggle source
# File lib/fugit/cron.rb, line 413
def to_h

  { seconds: @seconds,
    minutes: @minutes,
    hours: @hours,
    monthdays: @monthdays,
    months: @months,
    weekdays: @weekdays }
end
weekday_hash_match?(nt, hsh) click to toggle source
# File lib/fugit/cron.rb, line 155
def weekday_hash_match?(nt, hsh)

  phsh, nhsh = nt.wday_in_month

  if hsh > 0
    hsh == phsh # positive wday, from the beginning of the month
  else
    hsh == nhsh # negative wday, from the end of the month, -1 == last
  end
end
weekday_match?(nt) click to toggle source
# File lib/fugit/cron.rb, line 171
def weekday_match?(nt)

  return true if @weekdays.nil?

  wd, hom = @weekdays.find { |d, _| d == nt.wday }

  return false unless wd
  return true if hom.nil?

  if hom.is_a?(Array)
    weekday_modulo_match?(nt, hom)
  else
    weekday_hash_match?(nt, hom)
  end
end
weekday_modulo_match?(nt, mod) click to toggle source
# File lib/fugit/cron.rb, line 166
def weekday_modulo_match?(nt, mod)

  (nt.rweek + mod[1]) % mod[0] == 0
end

Protected Instance Methods

compact(key) click to toggle source
# File lib/fugit/cron.rb, line 555
def compact(key)

  arr = instance_variable_get(key)

  return instance_variable_set(key, nil) if arr.include?(nil)
    # reductio ad astrum

  arr.uniq!
  arr.sort!
end
compact_month_days() click to toggle source
# File lib/fugit/cron.rb, line 436
def compact_month_days

  return true if @months == nil || @monthdays == nil

  ms, ds =
    @months.inject([ [], [] ]) { |a, m|
      @monthdays.each { |d|
        next if d > MAXDAYS[m]
        a[0] << m; a[1] << d }
      a }
  @months = ms.uniq
  @monthdays = ds.uniq

  @months.any? && @monthdays.any?
end
determine_hours(arr) click to toggle source
# File lib/fugit/cron.rb, line 576
def determine_hours(arr)
  @hours = arr
    .inject([]) { |a, h| a.concat(expand(0, 23, h)) }
    .collect { |h| h == 24 ? 0 : h }
  compact(:@hours)
end
determine_minutes(arr) click to toggle source
# File lib/fugit/cron.rb, line 571
def determine_minutes(arr)
  @minutes = arr.inject([]) { |a, m| a.concat(expand(0, 59, m)) }
  compact(:@minutes)
end
determine_monthdays(arr) click to toggle source
# File lib/fugit/cron.rb, line 583
def determine_monthdays(arr)
  @monthdays = arr.inject([]) { |a, d| a.concat(expand(1, 31, d)) }
  compact(:@monthdays)
end
determine_months(arr) click to toggle source
# File lib/fugit/cron.rb, line 588
def determine_months(arr)
  @months = arr.inject([]) { |a, m| a.concat(expand(1, 12, m)) }
  compact(:@months)
end
determine_seconds(arr) click to toggle source
# File lib/fugit/cron.rb, line 566
def determine_seconds(arr)
  @seconds = (arr || [ 0 ]).inject([]) { |a, s| a.concat(expand(0, 59, s)) }
  compact(:@seconds)
end
determine_timezone(z) click to toggle source
# File lib/fugit/cron.rb, line 618
def determine_timezone(z)

  @zone, @timezone = z
end
determine_weekdays(arr) click to toggle source
# File lib/fugit/cron.rb, line 593
def determine_weekdays(arr)

  @weekdays = []

  arr.each do |a, z, sl, ha, mo| # a to z, slash, hash, and mod
    if ha || mo
      @weekdays << [ a, ha || mo ]
    elsif sl
      ((a || 0)..(z || (a ? a : 6))).step(sl < 1 ? 1 : sl)
        .each { |i| @weekdays << [ i ] }
    elsif z
      z = z + 7 if a > z
      (a..z).each { |i| @weekdays << [ (i > 6) ? i - 7 : i ] }
    elsif a
      @weekdays << [ a ]
    #else
    end
  end

  @weekdays.each { |wd| wd[0] = 0 if wd[0] == 7 } # turn sun7 into sun0
  @weekdays.uniq!
  @weekdays.sort!
  @weekdays = nil if @weekdays.empty?
end
expand(min, max, r) click to toggle source
# File lib/fugit/cron.rb, line 497
def expand(min, max, r)

  sta, edn, sla = r

  sla = nil if sla == 1 # don't get fooled by /1

  edn = max if sla && edn.nil?

  return [ nil ] if sta.nil? && edn.nil? && sla.nil?
  return [ sta ] if sta && edn.nil?

  sla = 1 if sla == nil
  sta = min if sta == nil
  edn = max if edn == nil || edn < 0 && sta > 0

  range(min, max, sta, edn, sla)
end
init(original, h) click to toggle source
# File lib/fugit/cron.rb, line 479
def init(original, h)

  @original = original
  @cron_s = nil # just to be sure

  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_timezone(h[:tz])

  return nil unless compact_month_days

  self
end
range(min, max, sta, edn, sla) click to toggle source
# File lib/fugit/cron.rb, line 515
def range(min, max, sta, edn, sla)

  fail ArgumentError.new(
    'both start and end must be negative in ' +
    { min: min, max: max, sta: sta, edn: edn, sla: sla }.inspect
  ) if (sta < 0 && edn > 0) || (edn < 0 && sta > 0)

  a = []

  omin, omax = min, max
  min, max = -max, -1 if sta < 0

  cur = sta

  loop do

    a << cur
    break if cur == edn

    cur += 1
    if cur > max
      cur = min
      edn = edn - max - 1 if edn > max
    end

    fail RuntimeError.new(
      "too many loops for " +
      { min: omin, max: omax, sta: sta, edn: edn, sla: sla }.inspect +
      " #range, breaking, " +
      "please fill an issue at https://git.io/fjJC9"
    ) if a.length > 2 * omax
      # there is a #uniq afterwards, hence the 2* for 0-24 and friends
  end

  a.each_with_index
    .select { |e, i| i % sla == 0 }
    .collect(&:first)
    .uniq
end
rough_days() click to toggle source
# File lib/fugit/cron.rb, line 452
def rough_days

  return nil if @weekdays == nil && @monthdays == nil

  months = (@months || (1..12).to_a)

  monthdays = months
    .product(@monthdays || [])
    .collect { |m, d|
      d = 31 + d if d < 0
      (m - 1) * 30 + d } # rough

  weekdays = (@weekdays || [])
    .collect { |d, w|
      w ?
      d + (w - 1) * 7 :
      (0..3).collect { |ww| d + ww * 7 } }
    .flatten
  weekdays = months
    .product(weekdays)
    .collect { |m, d| (m - 1) * 30 + d } # rough

  (monthdays + weekdays).sort
end