acute 1.0.0

data/lib/acute/resolve.rb

@@ -0,0 +1,245 @@
+require_relative "grammar"
+require_relative "assumption"
+require_relative "calendar"
+
+module Acute
+  # Tree plus context to readings, the main one first. Every convention (the D-rules) lives under resolve/.
+  #
+  # Inside resolve, times are local wall seconds (Zone's "local"), so day and month arithmetic is plain
+  # Integer maths; the readings are converted to UTC once, at the end.
+  # @api private
+  module Resolve
+    G = Grammar
+    # begin and end are epochs, end exclusive, either nil when open; dst is the code of a DST adjustment made
+    # to begin, if any; point is the D1 point of a part of day; frac the fraction of a second an instant was written with (D47)
+    Reading = Struct.new(:begin, :end, :grain, :dst, :point, :frac)
+    # The same in local wall seconds. An instant ("now", "in 3 hours", a time with an offset) also carries its
+    # UTC in ub and ue, so a wall time the clocks repeat keeps the side it is on; dst is the DST adjustment
+    # made converting ub from a zone named in the text (D47)
+    Span = Struct.new(:b, :e, :grain, :point, :ub, :ue, :dst)
+
+    APPROXIMATE = Assumption.for(:approximate)
+    FIXED_OFFSET = Assumption.for(:fixed_offset)
+    AMBIGUOUS_ZONE = Assumption.for(:ambiguous_zone)
+    WEEKDAY_MISMATCH = Assumption.for(:weekday_mismatch)
+
+    # An empty Array when nothing fits ("feb 30")
+    # A reading the resolver gave up on (Period::LIMIT) is a Failure with failure: true, otherwise no readings
+    def self.call(node, ctx, failure: false)
+      list = spans(node, ctx)
+      if list.empty? && !(date = Periodic.unfiltered(node)).equal?(node)
+        list = mismatch(node, date, ctx)
+      end
+      readings(list, ctx)
+    rescue Period::Limit
+      # A rescue costs nothing until something raises, where a catch costs every parse
+      failure ? Failure.new(:business_day_limit, 0, 0) : []
+    end
+
+    # D37, D43: a weekday that fits none of a date's coming readings may fit the one just gone ("Thu Aug 10"
+    # said on 16 Aug 2006); failing that, the date wins ("Sat, Sep 21" when that is a Tuesday). No other
+    # year is searched for.
+    def self.mismatch(node, date, ctx)
+      unless ctx.past?
+        ctx.past = :back
+        list = spans(node, ctx)
+        ctx.past = false
+        return list unless list.empty?
+      end
+      list = spans(date, ctx)
+      # D37: a weekday that fits one of the date's readings picks it ("Sat 16th" said on Wednesday the 16th)
+      wday = node
+      wday = wday.outer until G::Weekday === wday.inner
+      fit = list.select { |s| (s.b.div(Period::DAY) + 4) % 7 == wday.inner.wday }
+      unless fit.empty?
+        ctx.unnote(Periodic::SAME_DAY) || ctx.unnote(Periodic::SAME_DAY_PASSED) if fit.size < list.size
+        return fit
+      end
+      ctx.note(WEEKDAY_MISMATCH) unless list.empty?
+      list
+    end
+
+    def self.spans(node, ctx)
+      case G::KIND[node.class]
+      when :clock then Clock.bare(node, ctx)
+      when :day_ref then Day.whole(node, ctx)
+      when :now
+        t = ctx.now_local
+        [Span.new(t, t + 1, :second, nil, ctx.now, ctx.now + 1)]
+      when :date then Dates.spans(node, ctx)
+      when :within then within(node, ctx)
+      when :rel then Rel.spans(node, ctx)
+      when :shift then Shift.spans(node, ctx)
+      when :counted then Shift.counted(node, ctx)
+      when :closest then Shift.closest(node, ctx)
+      when :range then Ranges.spans(node, ctx)
+      when :open then Ranges.open(node, ctx)
+      when :lasting then Ranges.lasting(node, ctx)
+      when :holding then Resolve.spans(node.node, ctx).map { |s| Period.unit(node.unit, ctx, s.b) } # D19
+      when :fuzzy then Fuzzy.spans(node, ctx)
+      when :fiscal then Period.fiscal(node, ctx)
+      when :years then Dates.years(node, ctx)
+      when :approx
+        ctx.note(APPROXIMATE) # D14: the exact time, flagged
+        spans(node.node, ctx)
+      when :zoned then zoned(node, ctx)
+      else Periodic.bare(node, ctx)
+      end
+    end
+
+    # "friday 3pm" repeats weekly, so it is found like a weekday; "tomorrow 3pm" is 3pm inside each reading of
+    # tomorrow
+    def self.within(node, ctx)
+      return today_in(node.outer.year, ctx) if G::Date === node.outer && node.outer.year && !node.outer.month && today?(node.inner)
+      if (cyc = Periodic.cycle(node.outer))
+        return Periodic.bare(node, ctx, cyc)
+      end
+      if G::Shift === node.outer && !node.outer.anchor && (r = shifted(node, ctx))
+        return r
+      end
+      outers = spans(node.outer, ctx)
+      if outers.size == 1
+        out = Periodic.inside(node.inner, node.outer, outers[0], ctx)
+        return out unless this_passed?(node, out, ctx)
+        # D21: "this saturday at noon" said after noon on Saturday has passed, so it is found as "this (saturday at noon)"
+        return Rel.periodic(:this, G::Within.new(node.inner, node.outer.node), ctx)
+      end
+      out = []
+      outers.each do |s|
+        Periodic.inside(node.inner, node.outer, s, ctx).each { |x| out << x unless out.any? { |o| o.b == x.b && o.e == x.e } }
+      end
+      # D37, D44: a weekday that fits both orders of a numeric date picks the locale's ("Friday 7/6")
+      if out.size > 1 && G::Weekday === node.inner && G::Date === node.outer && node.outer.sep
+        ctx.unnote(Dates::ORDER)
+        return out.take(1)
+      end
+      out
+    end
+
+    # D44: a recurring day beside a shift from now is the one in its own cycle that holds the shifted instant:
+    # "thanksgiving in 9 months", "3 months ago saturday"; an ordinal's is the shift's unit when that is
+    # coarser: "first monday in 2 years"
+    def self.shifted(node, ctx)
+      cyc = Periodic.cycle(node.inner)
+      return if !cyc || cyc == :day
+      unit = node.outer.unit
+      unit = cyc unless ordinal?(node.inner) && G::UNIT_SIZE[unit] > G::UNIT_SIZE[cyc]
+      t = Shift.spans(node.outer, ctx)[0].b
+      Periodic.inside(node.inner, nil, Period.span(unit, ctx, Period.index(unit, ctx, t)), ctx)
+    end
+
+    def self.this_passed?(node, out, ctx)
+      o = node.outer
+      G::Rel === o && o.word == :this && G::Clock === node.inner && !ctx.past && !out.empty? &&
+        out[0].e <= ctx.now_local && Periodic.cycle(o.node) && Periodic.cycle(o.node) != :day
+    end
+
+    def self.today?(node)
+      (G::DayRef === node && node.offset == 0) || (G::Rel === node && node.word == :this && G::Unit === node.node && node.node.unit == :day)
+    end
+
+    # D48: "this day 1800" is today's date in that year
+    def self.today_in(year, ctx)
+      md = Calendar.civil_from_days(ctx.today) % 10_000
+      m = md / 100
+      d = md % 100
+      return [] if d > Calendar.days_in_month(year, m)
+      [Day.day(Calendar.days_from_civil(year, m, d))]
+    end
+
+    def self.ordinal?(node)
+      case node
+      when G::Nth then true
+      when G::Within then ordinal?(node.outer)
+      when G::Fuzzy then ordinal?(node.node)
+      else false
+      end
+    end
+
+    # D18: an offset in the text wins over the zone, and fixes the instant; D29: a numeric one makes the time
+    # machine-written
+    def self.zoned(node, ctx)
+      off = node.offset
+      return named_zone(node, Zone.for(off.name), ctx) if Symbol === off
+      return ambiguous_zone(node, off, ctx) unless Integer === off
+      ctx.note(FIXED_OFFSET)
+      ctx.machine = node.numeric
+      inner = ctx.in_zone(Zone.fixed(off)) { spans(node.node, ctx) }
+      ctx.machine = false
+      zone = ctx.zone
+      inner.map do |s|
+        ub = s.b && s.b - off
+        ue = s.e && s.e - off
+        if ub && ue && !s.point && (home = zone.steady_offset(ub, ue))
+          Span.new(ub + home, ue + home, s.grain, nil, ub, ue)
+        else
+          Span.new(ub && ctx.local(ub), ue && ctx.local(ue), s.grain, s.point && ctx.local(s.point - off), ub, ue)
+        end
+      end
+    end
+
+    # D44: under an IANA name in the text the wall times are that zone's, with its own clock changes
+    def self.named_zone(node, zone, ctx)
+      ctx.note(FIXED_OFFSET)
+      inner = ctx.in_zone(zone) { spans(node.node, ctx) }
+      inner.map do |s|
+        ctx.dst = nil
+        ub = s.ub || (s.b && zone.local_to_utc(s.b, ctx, ctx.dst_policy))
+        dst = s.ub ? s.dst : ctx.dst
+        ue = s.ue || (s.e && zone.local_to_utc(s.e, ctx, ctx.dst_policy))
+        point = s.point && zone.local_to_utc(s.point, ctx, ctx.dst_policy)
+        Span.new(ub && ctx.local(ub), ue && ctx.local(ue), s.grain, point && ctx.local(point), ub, ue, dst)
+      end
+    end
+
+    # D38: each of an ambiguous abbreviation's offsets in order; in the country it leads with, the first alone
+    def self.ambiguous_zone(node, offs, ctx)
+      home = offs[0]
+      offs = offs.drop(1) if String === home
+      return zoned(G::Zoned.new(node.node, offs[0], false), ctx) if home == ctx.locale.country
+      ctx.note(AMBIGUOUS_ZONE)
+      offs.flat_map { zoned(G::Zoned.new(node.node, _1, false), ctx) }
+    end
+
+    def self.readings(spans, ctx)
+      zone = ctx.zone
+      frac = ctx.frac
+      out = []
+      spans.each do |s|
+        b = s.b
+        e = s.e
+        point = s.point
+        if !s.ub && !s.ue && b && e && (!point || (point >= b && point <= e)) && (off = zone.steady_offset(b, e))
+          b -= off
+          e -= off
+          point -= off if point
+          dst = nil
+        else
+          ctx.dst = nil
+          b = s.ub || (b && zone.local_to_utc(b, ctx, ctx.dst_policy))
+          dst = s.ub ? s.dst : ctx.dst
+          e = s.ue || (e && zone.local_to_utc(e, ctx, ctx.dst_policy))
+          # a start the clocks skipped moved forward by the gap, past the end: it keeps its length
+          e = b + (s.e - s.b) if b && e && e <= b
+          point &&= zone.local_to_utc(point, ctx, ctx.dst_policy)
+        end
+        next if !out.empty? && out.any? { |o| o.begin == b && o.end == e }
+        out << Reading.new(b, e, s.grain, dst, point, frac && e && b && e - b == 1 ? frac : nil)
+      end
+      out
+    end
+  end
+end
+
+require_relative "resolve/period"
+require_relative "resolve/clock"
+require_relative "resolve/day"
+require_relative "resolve/dates"
+require_relative "resolve/named"
+require_relative "resolve/periodic"
+require_relative "resolve/nth"
+require_relative "resolve/rel"
+require_relative "resolve/shift"
+require_relative "resolve/ranges"
+require_relative "resolve/fuzzy"
+require_relative "resolve/recur"

data/lib/acute/result.rb

@@ -0,0 +1,128 @@
+require "date"
+require "json"
+require_relative "calendar"
+
+module Acute
+  # A parsed time or span. Frozen; epochs are kept as Integers and each Time is built when asked for, so a parse
+  # that only wants one field pays for no others.
+  class Result
+    # @api private
+    DAY_GRAINS = %i[day weekend week month quarter season year decade century].freeze
+    # @api private
+    MONTHS = Ractor.make_shareable(%w[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])
+    WEEKDAYS = Ractor.make_shareable(%w[Sun Mon Tue Wed Thu Fri Sat])
+    NO_ASSUMPTIONS = [].freeze
+    GRAIN_SECONDS = { second: 1, minute: 60, hour: 3600 }.freeze
+    private_constant :DAY_GRAINS, :NO_ASSUMPTIONS, :GRAIN_SECONDS
+
+    attr_reader :text, :grain, :assumptions
+
+    # @api private: results come from the calls. readings: the main reading first; the rest become alternatives.
+    # matched: the part of the text used (A12)
+    def initialize(text, readings, zone, assumptions, matched = nil)
+      main = readings[0]
+      @text = text
+      @matched = matched
+      @readings = readings.freeze
+      @point = main.point || main.begin || main.end
+      @begin_epoch = main.begin
+      @end_epoch = main.end
+      @grain = main.grain
+      @frac = main.frac
+      @zone = zone
+      @assumptions = assumptions
+      freeze
+    end
+
+    def kind = :time
+
+    def matched = @matched || @text
+
+    def time = at(@point, @frac)
+
+    def begin = @begin_epoch && at(@begin_epoch, @frac)
+
+    def end = @end_epoch && at(@end_epoch, @frac)
+
+    def range = self.begin...self.end
+
+    def zone = @zone.name
+
+    # The local date of the start, or of the time when the start is open, at any grain
+    def date
+      ymd = Calendar.civil_from_days(local(@begin_epoch || @point).div(86_400))
+      Date.new(ymd / 10_000, ymd / 100 % 100, ymd % 100)
+    end
+
+    def alternatives
+      @readings.drop(1).map! { |r| Result.new(@text, [r], @zone, NO_ASSUMPTIONS, @matched) }.freeze
+    end
+
+    def ambiguous? = @readings.size > 1
+
+    def instant? = !span?
+
+    # A day or longer, a part of the day, a clock range, or open at one end
+    def span? = DAY_GRAINS.include?(@grain) || open? || @end_epoch - @begin_epoch > GRAIN_SECONDS.fetch(@grain, 1)
+
+    def open? = @begin_epoch.nil? || @end_epoch.nil?
+
+    def iso8601 = span? ? "#{iso(self.begin) || ".."}/#{iso(self.end) || ".."}" : iso(time)
+
+    def to_h
+      {
+        kind: "time", text: @text, time: iso(time), begin: iso(self.begin), end: iso(self.end),
+        grain: @grain.to_s, zone: zone,
+        assumptions: @assumptions.map { |a| { code: a.code.to_s, rule: a.rule, message: a.message } },
+        alternatives: alternatives.map { |r| { time: iso(r.time), begin: iso(r.begin), end: iso(r.end), grain: r.grain.to_s } }
+      }
+    end
+
+    def to_json(*args) = to_h.to_json(*args)
+
+    # String keys, as JSON.parse would give
+    def as_json(*) = JSON.parse(to_json)
+
+    # en-US: "Sun, Oct 18, 2026, 9am EDT", or "Sun, Oct 18, 2026, all day"
+    def to_s
+      local = local(@point)
+      days = local.div(86_400)
+      ymd = Calendar.civil_from_days(days)
+      date = "#{WEEKDAYS[Calendar.weekday(days)]}, #{MONTHS[ymd / 100 % 100 - 1]} #{ymd % 100}, #{ymd / 10_000}"
+      return "#{date}, all day" if DAY_GRAINS.include?(@grain)
+
+      secs = local - days * 86_400
+      hour = secs / 3600
+      clock = (hour % 12 == 0 ? 12 : hour % 12).to_s
+      seconds = @grain == :second && (secs % 60 != 0 || @frac)
+      clock << format(":%02d", secs / 60 % 60) if secs % 3600 != 0 || seconds
+      clock << format(":%02d", secs % 60) if seconds
+      clock << decimals(@frac) if @frac
+      "#{date}, #{clock}#{hour < 12 ? "am" : "pm"} #{@zone.abbreviation_at(@point)}"
+    end
+
+    def inspect = "#<Acute::Result #{self}>"
+
+    private
+
+    def local(epoch) = epoch + @zone.offset_at(epoch)
+
+    def at(epoch, frac = nil)
+      t = Time.at(epoch, in: @zone.offset_at(epoch))
+      frac ? t + frac : t
+    end
+
+    def iso(t)
+      return unless t
+      return t.strftime("%FT%T%:z") if t.subsec == 0
+      "#{t.strftime("%FT%T")}#{decimals(t.subsec)}#{t.strftime("%:z")}"
+    end
+
+    # ".345": the fewest digits that give a fraction of a second exactly
+    def decimals(frac)
+      n = 1
+      n += 1 until (frac * 10**n).denominator == 1
+      format(".%0*d", n, frac * 10**n)
+    end
+  end
+end

data/lib/acute/rule/cron.rb

@@ -0,0 +1,222 @@
+module Acute
+  class Rule
+    # Standard 5-field cron, both ways (R20–R26): minute hour day-of-month month day-of-week, Sunday 0
+    module Cron
+      DAY = 86_400
+      MONTHS = Ractor.make_shareable(%w[jan feb mar apr may jun jul aug sep oct nov dec])
+      WEEKDAYS = Ractor.make_shareable(%w[sun mon tue wed thu fri sat])
+      # name, first value, last value, the names for them, where a name's index counts from
+      FIELDS = Ractor.make_shareable([["minute", 0, 59], ["hour", 0, 23], ["day of the month", 1, 31], ["month", 1, 12, MONTHS, 1],
+                                      ["day of the week", 0, 7, WEEKDAYS, 0]])
+      MACROS = Ractor.make_shareable({ "@yearly" => "0 0 1 1 *", "@annually" => "0 0 1 1 *", "@monthly" => "0 0 1 * *",
+                                       "@weekly" => "0 0 * * 0", "@daily" => "0 0 * * *", "@midnight" => "0 0 * * *",
+                                       "@hourly" => "0 * * * *" })
+      # Anchored, with every repeat bounded and nothing nested, so a match can't backtrack
+      ITEM = %r{\A(?:(\*)|(\w{1,3})(?:-(\w{1,3}))?)(?:/(\d{1,3}))?\z}
+      # Quartz's last (L, 5L), nearest weekday (15W, LW), nth weekday (1#2) and no value (?)
+      NONSTANDARD = /[#?]|\A(?:\d{0,2}l|\d{1,2}w|lw)\z/
+      # first, last, whether steps are written: weekdays are listed, so the weekend is 0,6 and not */6
+      WRITE = Ractor.make_shareable([[0, 59, true], [0, 23, true], [1, 31, true], [1, 12, true], [0, 6, false]])
+      FINE = { minutely: 60, hourly: 3600 }.freeze
+
+      # A Rule, or [code, message, character range] (R25)
+      def self.read(line, now, zone, dst)
+        raise ArgumentError, "a cron line must be a String, got #{line.class}" unless String === line
+        ctx = Context.new(now, zone, :future, nil, nil, nil, nil, true, dst) # R18: occurrences follow dst:
+        return [:too_long, "longer than #{MAX_LENGTH} bytes", 0...0] if line.bytesize > MAX_LENGTH
+        return [:invalid_cron, "a cron line is plain ASCII", 0...0] unless line.valid_encoding? && line.ascii_only?
+        text = line.strip.downcase
+        lead = line.length - line.lstrip.length
+        whole = lead...(lead + text.length)
+        if text.start_with?("@")
+          return [:unsupported_cron, "@reboot runs at boot, not at a time", whole] if text == "@reboot"
+          text = MACROS[text] or return [:invalid_cron, "#{line.strip.inspect} is not a cron macro", whole]
+          lead = nil
+        end
+        fields = []
+        text.scan(/\S+/) { fields << [Regexp.last_match[0], Regexp.last_match.begin(0)] }
+        return [:invalid_cron, "a cron line has 5 fields, this has #{fields.size}", whole] unless fields.size == 5
+        sets = fields.each_with_index.map do |(f, at), i|
+          set = field(f, *FIELDS[i])
+          return [*set, lead ? (lead + at)...(lead + at + f.length) : whole] if Symbol === set[0]
+          set
+        end
+        sunday = sets[4].pop # R25: 7 is Sunday too
+        sets[4][0] ||= sunday
+        out = build(sets, fields[2][0].start_with?("*"), fields[4][0].start_with?("*"), ctx, line)
+        Rule === out ? out : [*out, whole]
+      end
+
+      # The field's values as an Array of booleans indexed by value, or [code, message]
+      def self.field(text, name, low, high, names = nil, base = 0)
+        set = Array.new(high + 1, false)
+        text.split(",", -1).each do |item|
+          return [:unsupported_cron, "#{item.upcase.inspect} is not standard cron: no L, W, # or ?"] if item.match?(NONSTANDARD)
+          m = ITEM.match(item) or return [:invalid_cron, "#{item.inspect} is not a #{name}"]
+          step = m[4]&.to_i
+          return [:invalid_cron, "a step of #{m[4]} doesn't fit the #{name}"] if step && (step < 1 || step > high - low + 1)
+          if m[1]
+            a = low
+            b = high
+          else
+            a = value(m[2], low, high, names, base) or return [:invalid_cron, "#{m[2].inspect} is not a #{name} (#{low}-#{high})"]
+            b = m[3] ? value(m[3], low, high, names, base) : a
+            return [:invalid_cron, "#{m[3].inspect} is not a #{name} (#{low}-#{high})"] unless b
+            return [:invalid_cron, "#{item.inspect} runs backwards"] if b < a
+            return [:invalid_cron, "a step needs a range or *: #{item.inspect}"] if step && !m[3] # Vixie
+          end
+          a.step(b, step || 1) { set[_1] = true }
+        end
+        set
+      end
+
+      def self.value(text, low, high, names, base)
+        n = if text.match?(/\A\d{1,2}\z/) then text.to_i
+            elsif names && (i = names.index(text)) then i + base
+            end
+        n if n && n >= low && n <= high
+      end
+
+      # R25, R26: cron's fields as the shapes acute's own rules take
+      def self.build(sets, dom_star, dow_star, ctx, line)
+        minutes, hours, doms, months, dows = sets.map { |s| (0...s.size).select { s[_1] } }
+        all_doms = doms.size == 31
+        all_dows = dows.size == 7
+        # R26: with neither field starting with *, cron runs on a day either one matches (Vixie)
+        if !dom_star && !dow_star && !all_doms && !all_dows
+          return [:unsupported_cron, "cron runs when the day of the month or the day of the week matches; a rule can't say or"]
+        elsif !dom_star && !dow_star
+          all_doms = all_dows = true
+        elsif !all_doms && !all_dows
+          return [:unsupported_cron, "a rule can't hold a day of the month on given weekdays"]
+        end
+        all_months = months.size == 12
+        every_day = all_doms && all_dows && all_months
+
+        if every_day && hours.size == 24 && (n = grid(minutes, 0, 59)) && n < 60
+          return fine(:minutely, n, ctx, line)
+        elsif every_day && minutes == [0] && (n = grid(hours, 0, 23)) && n < 24
+          return fine(:hourly, n, ctx, line)
+        end
+        secs = hours.flat_map { |h| minutes.map { h * 3600 + _1 * 60 } } # R25: each hour with each minute (R4)
+        step = grid(months, 1, 12, offset: true)
+        parts = if every_day then [:daily, 1, nil, [], []]
+                elsif all_doms && all_months then [:weekly, 1, nil, [], dows]
+                elsif all_dows && step && step < 12 then [:monthly, step, nil, doms, []] # R23: every n months
+                elsif all_dows && months.size == 1 && doms.size == 1 then [:yearly, 1, months[0], doms, []]
+                end
+        return [:unsupported_cron, "a rule can't hold those days and months together"] unless parts
+        rule = Parts.new(*parts, [], nil, secs)
+        start = first(rule, rule.interval > 1 && months, ctx) or return [:invalid_cron, "the line never runs"]
+        Rule.new(rule, ctx.zone.name, start, true, nil, nil, [], false, ctx.dst_policy, now: ctx.now, text: line)
+      end
+
+      # The step n when values are every nth through high, from low or (offset) from less than n past it, and n
+      # divides the field evenly so the step doesn't restart short (R23); else nil
+      def self.grid(values, low, high, offset: false)
+        size = high - low + 1
+        n = values.size > 1 ? values[1] - values[0] : size
+        n if size % n == 0 && (offset ? values[0] - low < n : values[0] == low) && values == values[0].step(high, n).to_a
+      end
+
+      # R23: a step finer than a day starts on cron's grid, counted from the top of the hour
+      def self.fine(freq, n, ctx, line)
+        step = n * FINE[freq]
+        local = ctx.local(ctx.now)
+        start = (local + step - 1).div(step) * step
+        Rule.new(Parts.new(freq, n, nil, [], [], [], nil, []), ctx.zone.name, start, true, nil, nil, [], false,
+                 ctx.dst_policy, now: ctx.now, text: line)
+      end
+
+      # R2: the first run on or after now, as local wall seconds; with a step of months, only in those months
+      def self.first(rule, months, ctx)
+        today = ctx.local(ctx.now).div(DAY)
+        (today...(today + Resolve::Recur::SEARCH)).each do |day|
+          next unless rule.on?(day) && (!months || months.include?(Calendar.civil_from_days(day) / 100 % 100))
+          rule.secs.each { |s| return day * DAY + s if ctx.zone.local_to_utc(day * DAY + s, ctx) >= ctx.now }
+        end
+        nil
+      end
+
+      # R20: the shortest way to write a field: *, */n, a-high/n, then runs and single values
+      def self.write(values, low, high, steps)
+        return "*" if values.size == high - low + 1
+        if steps && values.size > 1
+          n = values[1] - values[0]
+          if n > 1 && values[0] - low < n && values == values[0].step(high, n).to_a
+            return "*/#{n}" if values[0] == low
+            return "#{values[0]}-#{high}/#{n}" if values.size > 2
+          end
+        end
+        values.slice_when { _2 != _1 + 1 }.map { |run| run.size > 2 ? "#{run[0]}-#{run[-1]}" : run.join(",") }.join(",")
+      end
+    end
+
+    def self.from_cron(line, now: nil, zone: nil, dst: nil)
+      out = Cron.read(line, now, zone, dst)
+      Rule === out ? out : nil
+    end
+
+    def self.from_cron!(line, now: nil, zone: nil, dst: nil)
+      out = Cron.read(line, now, zone, dst)
+      raise ParseError.new(out[1], code: out[0], position: out[2]) unless Rule === out
+      out
+    end
+
+    def cron = cron_or_reason[0]
+
+    def cron_reason = cron_or_reason[1]
+
+    private
+
+    def cant(what) = [nil, "cron can't express #{what.inspect}"]
+
+    # [line, nil] or [nil, reason]: R20–R24
+    def cron_or_reason
+      p = @parts
+      return cant("until") if @until # R21
+      return cant("#{@count} times") if @count
+      return cant("starting") if @started
+      return cant("except") unless @exdates.empty?
+      return cant("the #{list(p.nths.sort_by(&:first).map { ordinal(_1[0]) })} #{DAY_NAMES[p.nths[0][1]]}") unless p.nths.empty? # R24
+      return cant("the #{list(p.setpos.map { ordinal(_1) })} weekday") if p.setpos
+      return cant("the last day") if p.monthdays.any?(&:negative?)
+      return cant(every("second")) if p.freq == :secondly
+      return [nil, "cron has no seconds"] if p.secs.any? { _1 % 60 != 0 }
+
+      n = p.interval
+      fine = Cron::FINE[p.freq]
+      unit = UNITS[p.freq]
+      if fine && p.secs.empty? # R23
+        step = n * fine
+        return cant(every(unit)) unless 3600 % step == 0 || (step % 3600 == 0 && DAY % step == 0)
+        minute = step < 3600 ? (0...60).step(step / 60).to_a : [0]
+        hours = step < 3600 ? (0...24).to_a : (0...24).step(step / 3600).to_a
+        return [cron_line([minute, hours, (1..31).to_a, (1..12).to_a, (0..6).to_a]), nil]
+      end
+      return cant(every(p.days.empty? ? unit : nil).delete_suffix(" on")) if n > 1 && !(p.freq == :monthly && 12 % n == 0) # R23
+      minute = p.secs.empty? ? [0] : p.secs.map { _1 / 60 % 60 }.uniq.sort # R22
+      hours = p.secs.empty? ? [0] : p.secs.map { _1 / 3600 }
+
+      day = @timed ? @start.div(DAY) : @start
+      ymd = Calendar.civil_from_days(day)
+      doms = (1..31).to_a
+      months = (1..12).to_a
+      dows = (0..6).to_a
+      case p.freq
+      when :weekly then dows = p.days.empty? ? [Calendar.weekday(day)] : p.days.sort
+      when :monthly
+        doms = p.monthdays.empty? ? [ymd % 100] : p.monthdays.sort
+        months = months.select { (_1 - ymd / 100 % 100) % n == 0 }
+      when :yearly
+        doms = p.month ? p.monthdays : [ymd % 100]
+        months = [p.month || ymd / 100 % 100]
+      end
+      [cron_line([minute, hours, doms, months, dows]), nil]
+    end
+
+    def cron_line(sets) = sets.zip(Cron::WRITE).map { |v, w| Cron.write(v.uniq, *w) }.join(" ")
+
+    private_constant :Cron
+  end
+end