Module: Cybertrain::Cron

Defined in:
cybertrain/cron.rb

Overview

Five-field cron expressions (minute, hour, day of month, month, day of week) and the next run of one in a TimeZone.

Each field takes *, n, a-b, */n, a-b/n, a/n (a through the field’s end, every n) and lists of those joined with ,. Months take the names jan-dec and days of week sun-sat, in any case; day of week 0 and 7 are both Sunday. The @hourly-style shortcuts are not accepted. When both the day of month and the day of week are restricted (neither starts with *) a day matches if either does, as in cron.

Cron.next_after reads the zone’s wall clock minute by minute in UTC time, so a wall time that a spring transition skips never matches, and across an autumn fold an expression with a fixed hour runs once (at the earlier instant) while one whose hour field starts with * runs at both occurrences of the repeated hour (Vixie cron’s rule: 30 * * * * keeps its hourly cadence).

Examples:

The next 09:00 on a weekday in Tokyo

expr = Cybertrain::Cron.parse("0 9 * * mon-fri")
tokyo = Cybertrain::TimeZone.find("Asia/Tokyo")
Cybertrain::Cron.next_after(expr, Time.current.to_i, tokyo) # => epoch seconds

Defined Under Namespace

Classes: Expression

Class Method Summary collapse

Class Method Details

.next_after(expr, epoch, zone) ⇒ Integer

The first minute strictly after epoch whose wall-clock time in zone matches expr. A wall time a forward transition skips never matches; across a backward transition (a fold) an expression whose hour field starts with * runs at both occurrences of the repeated wall time, and one with a fixed hour runs only at a wall time later than epoch’s (so the repeated hour, already passed, is not run again).

Walks UTC minutes, jumping to the next local midnight when the day is ruled out and to the next local hour when the hour is, so a yearly expression costs about a step per day; a jump that would cross a change of the zone’s offset is taken a minute at a time instead.

Parameters:

Returns:

  • (Integer) —

    UTC epoch seconds, on a minute boundary

Raises:

  • (ArgumentError) —

    when nothing matches within five years



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
# File 'cybertrain/cron.rb', line 177

def self.next_after(expr, epoch, zone)
  start = epoch.to_i
  last_local = zone.utc_to_local(start)
  last_local -= last_local % 60
  fixed_hour = !expr.cron_hour_star?
  t = start - start % 60 + 60
  limit = start + SEARCH_DAYS * 86_400
  while t <= limit
    local = zone.utc_to_local(t)
    f = TimeZone.epoch_to_civil(local)
    into_day = f[3] * 3600 + f[4] * 60
    step = 60
    if !expr.cron_day?(f[1], f[2], f[6])
      step = jump(zone, t, 86_400 - into_day)
      step = jump(zone, t, 3600 - f[4] * 60) if step == 60
    elsif !expr.cron_hour?(f[3])
      step = jump(zone, t, 3600 - f[4] * 60)
    elsif expr.cron_minute?(f[4])
      return t unless fixed_hour && local - local % 60 <= last_local
    end
    t += step
  end
  reason = "no run in the #{SEARCH_DAYS / 365} years after #{utc_stamp(start)}"
  refuse(expr.expression_text, reason)
  -1
end

.parse(text) ⇒ Expression

Parses a five-field expression.

Parameters:

  • text (String) —

    such as "*/15 9-17 * * mon-fri"

Returns:

Raises:

  • (ArgumentError) —

    cron "<text>": <what is wrong> for a field count other than five, an @ shortcut, a value out of range, a step of 0, a name the field does not know, a range that runs backwards, an empty list entry, or an expression that can never match (0 0 31 2 *)



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
# File 'cybertrain/cron.rb', line 133

def self.parse(text)
  s = text.to_s
  fields = cron_words(s)
  if s.strip.start_with?("@")
    refuse(s, "the @ shortcuts are not accepted; write the five fields")
  end
  if fields.size != 5
    reason = "expected 5 fields (minute hour day-of-month month day-of-week), got #{fields.size}"
    refuse(s, reason)
  end
  no_names = Array.new(0) { "" }
  minutes = field_values(s, fields[0], "minute", 0, 59, no_names, 0)
  hours = field_values(s, fields[1], "hour", 0, 23, no_names, 0)
  days = field_values(s, fields[2], "day of month", 1, 31, no_names, 0)
  months = field_values(s, fields[3], "month", 1, 12, MONTH_NAMES, 1)
  wdays = field_values(s, fields[4], "day of week", 0, 7, WDAY_NAMES, 0)
  hour_star = fields[1].start_with?("*")
  dom_star = fields[2].start_with?("*")
  dow_star = fields[4].start_with?("*")
  # Both restricted: a matching day of week makes any month possible.
  if (dom_star || dow_star) && !day_fits_month?(days, months)
    reason = "day of month #{fields[2]} never falls in the months allowed"
    refuse(s, reason)
  end
  Expression.new(s, minutes, hours, days, months, wdays, hour_star, dom_star, dow_star)
end