acute 1.0.0

data/lib/acute/rule/expand.rb

@@ -0,0 +1,401 @@
+require "date"
+
+module Acute
+  class Rule
+    # @api private
+    MAX_OCCURRENCES = 1_000 # R19
+    STEPS = 100_000 # R19
+
+    # R16: the next occurrence after `after` (by default the now the rule was read at), or with n the next n as an
+    # Array: Times in the rule's zone, or Dates for a rule of whole days. nil or fewer when the rule ends; nil past a
+    # limit (R19), which next! explains.
+    def next(n = nil, after: now)
+      out = listing(n || 1, after)
+      return if Failure === out
+      n ? out : out[0]
+    end
+
+    def next!(n = nil, after: now)
+      out = raising(listing(n || 1, after))
+      n ? out : out[0]
+    end
+
+    # R16: the occurrences from `from` up to `to`, `to` left out. A Date stands for its whole day.
+    def between(from, to)
+      out = window(from, to)
+      out unless Failure === out
+    end
+
+    def between!(from, to) = raising(window(from, to))
+
+    # R16: every occurrence in order, lazily, from DTSTART or after `after`. It ends with the rule, or when R19's
+    # steps pass without one.
+    def each(after: nil)
+      return enum_for(:each, after: after) unless block_given?
+      x = expander
+      x.walk(after.nil? ? x.first : x.after(after)) do |o|
+        yield x.out(o)
+        x.refill
+      end
+      self
+    rescue Expand::Exhausted
+      self
+    end
+
+    private
+
+    def expander = Expand.new(@parts, @zone, @start, @timed, @count, @until, @exdates, @dst)
+
+    def raising(out)
+      raise Explain.error(out, "") if Failure === out
+      out
+    end
+
+    def listing(n, after)
+      raise ArgumentError, "n must be an Integer of 0 or more, got #{n.inspect}" unless Integer === n && n >= 0
+      return Failure.new(:occurrence_limit, 0, 0) if n > MAX_OCCURRENCES
+      out = []
+      return out if n == 0
+      x = expander
+      x.walk(x.after(after)) do |o|
+        out << x.out(o)
+        break if out.size == n
+      end
+      out
+    rescue Expand::Exhausted
+      Failure.new(:step_limit, 0, 0)
+    end
+
+    def window(from, to)
+      x = expander
+      lo, hi = x.span(from, to)
+      out = []
+      x.walk(lo) do |o|
+        break unless x.before?(o, hi)
+        return Failure.new(:occurrence_limit, 0, 0) if out.size == MAX_OCCURRENCES
+        out << x.out(o)
+      end
+      out
+    rescue Expand::Exhausted
+      Failure.new(:step_limit, 0, 0)
+    end
+
+    # R17: RFC 5545 expansion of a Rule, one call's worth. An occurrence is [utc, wall] when the rule is timed, else
+    # a day number; walk yields them in order.
+    class Expand
+      DAY = 86_400
+      SUB = { hourly: 3600, minutely: 60, secondly: 1 }.freeze
+      MARGIN = 2 * 3600 # more than any clock change, so a period starting the local day before is looked at
+      EPOCH_JD = 2_440_588
+      NONE = [].freeze
+      Notes = Struct.new(:dst)
+      class Exhausted < StandardError; end
+
+      def initialize(parts, zone, start, timed, count, until_, exdates, dst)
+        @zone = Zone.for(zone)
+        @freq = parts.freq
+        @interval = parts.interval
+        @start = start
+        @timed = timed
+        @count = count
+        @until = until_
+        @exdates = exdates
+        @dst = dst
+        @policy = dst == :reject ? nil : dst
+        @notes = Notes.new
+        @steps = STEPS
+        @d0 = timed ? start.div(DAY) : start
+        @month = parts.month
+        @monthdays = parts.monthdays
+        @days = parts.days
+        @nths = parts.nths
+        @setpos = parts.setpos
+        @secs = parts.secs.empty? && timed && !SUB[@freq] ? [start % DAY] : parts.secs.sort
+        derive
+        @anchor = @zone.local_to_utc(start, @notes, @policy) if timed
+      end
+
+      def first = @timed ? @anchor : @d0
+
+      def refill = @steps = STEPS
+
+      # The lowest occurrence after x: an instant after it, or a day still under way at it (R2); a Date is its
+      # whole day
+      def after(x)
+        if plain_date?(x)
+          day = x.jd - EPOCH_JD + 1
+          return @timed ? day_start(day) : day
+        end
+        t = epoch(x).floor
+        @timed ? t + 1 : local_day(t)
+      end
+
+      # [lowest, past the highest] of the occurrences from `from` up to `to`; a day counts when any of it is
+      def span(from, to)
+        lo = if plain_date?(from)
+               day = from.jd - EPOCH_JD
+               @timed ? day_start(day) : day
+             else
+               t = epoch(from).ceil
+               @timed ? t : local_day(t)
+             end
+        hi = if plain_date?(to)
+               day = to.jd - EPOCH_JD + 1
+               @timed ? day_start(day) : day
+             else
+               t = epoch(to).ceil
+               @timed ? t : local_day(t - 1) + 1
+             end
+        [lo, hi]
+      end
+
+      def before?(o, hi) = @timed ? o[0] < hi : o < hi
+
+      def out(o) = @timed ? Time.at(o[0], in: @zone.offset_at(o[0])) : ::Date.jd(o + EPOCH_JD)
+
+      def walk(lo, &) = SUB[@freq] ? sub_walk(lo, &) : day_walk(lo, &)
+
+      private
+
+      # R17: a part the rule doesn't name comes from DTSTART, as RFC 5545 says
+      def derive
+        ymd = Calendar.civil_from_days(@d0)
+        bare = @monthdays.empty? && @days.empty? && @nths.empty?
+        case @freq
+        when :weekly
+          @days = [Calendar.weekday(@d0)] if @days.empty?
+        when :monthly
+          @monthdays = [ymd % 100] if bare
+        when :yearly
+          if bare
+            @month ||= ymd / 100 % 100
+            @monthdays = [ymd % 100]
+          end
+        end
+      end
+
+      def plain_date?(x) = Date === x && !(DateTime === x)
+
+      def epoch(x)
+        return x.to_r if Time === x
+        return x.to_time.to_r if x.respond_to?(:to_time)
+        raise ArgumentError, "expected a Time or a Date, got #{x.class}"
+      end
+
+      def local_day(t) = (t + @zone.offset_at(t)).div(DAY)
+
+      def day_start(day) = @zone.local_to_utc(day * DAY, @notes)
+
+      def spend(n)
+        raise Exhausted if (@steps -= n) < 0
+      end
+
+      # Daily to yearly: period k is the interval's k-th day, week (from Monday), month or year after DTSTART's
+      def day_walk(lo)
+        k = @count ? 0 : first_period(lo)
+        n = 0
+        loop do
+          list = period(k)
+          spend(list.size + 1)
+          if @timed
+            return if @until && (@first - 1) * DAY > @until
+            zoned(list).each do |utc, wall|
+              next if wall < @start
+              return nil if @until && utc > @until
+              return nil if @count && (n += 1) > @count
+              yield [utc, wall] unless utc < lo || @exdates.include?(wall)
+            end
+          else
+            return if @until && @first > @until
+            list.each do |day|
+              next if day < @start
+              return nil if @until && day > @until
+              return nil if @count && (n += 1) > @count
+              yield day unless day < lo || @exdates.include?(day)
+            end
+          end
+          k += 1
+        end
+      end
+
+      # The period holding lo's day, or the last one before it, so a jump skips what comes before lo
+      def first_period(lo)
+        day = @timed ? local_day(lo - MARGIN) : lo
+        i = case @freq
+            when :daily then day - @d0
+            when :weekly then (monday(day) - monday(@d0)) / 7
+            when :monthly then month_index(day) - month_index(@d0)
+            else year(day) - year(@d0)
+            end
+        k = i.div(@interval)
+        k < 0 ? 0 : k
+      end
+
+      # Period k's candidates in order, after BYSETPOS: wall seconds when timed, else days
+      def period(k)
+        step = k * @interval
+        days = case @freq
+               when :daily
+                 @first = @d0 + step
+                 day_ok?(@first) ? [@first] : NONE
+               when :weekly
+                 @first = monday(@d0) + 7 * step
+                 list = @days.map { @first + (_1 + 6) % 7 }.sort
+                 @month ? list.select { month_of(_1) == @month } : list
+               when :monthly
+                 y, m = (month_index(@d0) + step).divmod(12)
+                 @first = Calendar.days_from_civil(y, m + 1, 1)
+                 @month && @month != m + 1 ? NONE : in_month(@first, Calendar.days_in_month(y, m + 1))
+               else
+                 y = year(@d0) + step
+                 @first = Calendar.year_start(y)
+                 if @month
+                   in_month(Calendar.days_from_civil(y, @month, 1), Calendar.days_in_month(y, @month))
+                 elsif @monthdays.empty?
+                   by_weekday(@first, Calendar.year_start(y + 1)).sort.uniq # RFC 5545: an ordinal counts in the year
+                 else
+                   (1..12).flat_map { in_month(Calendar.days_from_civil(y, _1, 1), Calendar.days_in_month(y, _1)) }
+                 end
+               end
+        list = @timed ? days.flat_map { |d| @secs.map { d * DAY + _1 } } : days
+        @setpos ? @setpos.filter_map { list[_1 > 0 ? _1 - 1 : _1] }.uniq.sort : list
+      end
+
+      # R18: wall times to [utc, wall] by the dst: policy; :reject leaves out a skipped or repeated time
+      def zoned(walls)
+        shifted = false
+        out = []
+        walls.each do |w|
+          @notes.dst = nil
+          utc = @zone.local_to_utc(w, @notes, @policy)
+          if @notes.dst
+            next if @dst == :reject
+            shifted = true
+          end
+          out << [utc, w]
+        end
+        return out unless shifted && out.size > 1
+        # A skipped time moved forward can land on a later one, which it then is
+        out.sort_by!(&:first)
+        out.uniq!(&:first)
+        out
+      end
+
+      # R18: hourly and finer step in elapsed time from DTSTART (D23)
+      def sub_walk(lo)
+        unit = SUB[@freq]
+        step = unit * @interval
+        a = @anchor
+        if @secs.empty? && every_day?
+          k = lo <= a ? 0 : (lo - a + step - 1).div(step) # each step is one occurrence, so k is also the count
+          loop do
+            spend(1)
+            t = a + k * step
+            return if @count && k >= @count
+            return if @until && t > @until
+            wall = t + @zone.offset_at(t)
+            yield [t, wall] unless @exdates.include?(wall)
+            k += 1
+          end
+        end
+        p0 = a - @start % unit # the start of DTSTART's hour, minute or second
+        n = 0
+        day = (@count ? @d0 : [local_day(lo - MARGIN), @d0].max) - 1
+        loop do
+          day += 1
+          spend(1)
+          s0 = day_start(day)
+          return if @until && s0 > @until
+          next unless day_ok?(day)
+          if @secs.empty?
+            s1 = day_start(day + 1)
+            t = s0 <= a ? a : a + (s0 - a + step - 1).div(step) * step
+            while t < s1
+              spend(1)
+              return if @until && t > @until
+              return if @count && (n += 1) > @count
+              wall = t + @zone.offset_at(t)
+              yield [t, wall] unless t < lo || @exdates.include?(wall)
+              t += step
+            end
+          else
+            zoned(@secs.map { day * DAY + _1 }).each do |t, wall|
+              spend(1)
+              next if t < a || !((t - p0).div(unit) % @interval).zero?
+              return nil if @until && t > @until
+              return nil if @count && (n += 1) > @count
+              yield [t, wall] unless t < lo || @exdates.include?(wall)
+            end
+          end
+        end
+      end
+
+      def every_day? = @month.nil? && @monthdays.empty? && @days.empty? && @nths.empty?
+
+      # BYMONTH, BYMONTHDAY and BYDAY as limits on one day
+      def day_ok?(d)
+        return true if every_day?
+        ymd = Calendar.civil_from_days(d)
+        m = ymd / 100 % 100
+        return false if @month && @month != m
+        dim = Calendar.days_in_month(ymd / 10_000, m)
+        unless @monthdays.empty?
+          md = ymd % 100
+          return false unless @monthdays.any? { (_1 > 0 ? _1 : dim + _1 + 1) == md }
+        end
+        first = d - ymd % 100 + 1
+        (@days.empty? && @nths.empty?) || weekday_ok?(d, first, first + dim)
+      end
+
+      # A month's days: BYMONTHDAY, limited by BYDAY, or BYDAY alone
+      def in_month(first, dim)
+        z = first + dim
+        list = if @monthdays.empty?
+                 by_weekday(first, z)
+               else
+                 days = @monthdays.filter_map do |md|
+                   x = md > 0 ? md : dim + md + 1
+                   first + x - 1 if x >= 1 && x <= dim
+                 end
+                 @days.empty? && @nths.empty? ? days : days.select { weekday_ok?(_1, first, z) }
+               end
+        list.size > 1 ? list.sort.uniq : list
+      end
+
+      # The days from a up to z on a BYDAY weekday, an ordinal one counted within them
+      def by_weekday(a, z)
+        out = []
+        @days.each do |w|
+          d = a + (w - Calendar.weekday(a)) % 7
+          while d < z
+            out << d
+            d += 7
+          end
+        end
+        @nths.each do |n, w|
+          d = n > 0 ? a + (w - Calendar.weekday(a)) % 7 + 7 * (n - 1) : z - 1 - (Calendar.weekday(z - 1) - w) % 7 - 7 * (-n - 1)
+          out << d if d >= a && d < z
+        end
+        out
+      end
+
+      def weekday_ok?(d, a, z)
+        w = Calendar.weekday(d)
+        @days.include?(w) || @nths.any? { |n, nw| nw == w && (n > 0 ? (d - a) / 7 + 1 == n : (z - 1 - d) / 7 + 1 == -n) }
+      end
+
+      def monday(d) = d - (d + 3) % 7
+
+      def month_of(d) = Calendar.civil_from_days(d) / 100 % 100
+
+      def month_index(d)
+        ymd = Calendar.civil_from_days(d)
+        ymd / 10_000 * 12 + ymd / 100 % 100 - 1
+      end
+
+      def year(d) = Calendar.civil_from_days(d) / 10_000
+    end
+
+    private_constant :Expand
+  end
+end

data/lib/acute/rule.rb

@@ -0,0 +1,232 @@
+require "json"
+require "date"
+
+module Acute
+  # A repeating time as an iCalendar rule (RFC 5545): a DTSTART, an RRULE and any EXDATE (R1). Frozen and
+  # Ractor-shareable.
+  class Rule
+    DAYS = Ractor.make_shareable(%w[SU MO TU WE TH FR SA])
+    DAY_NAMES = Ractor.make_shareable(%w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday])
+    MONTH_NAMES = Ractor.make_shareable(%w[_ January February March April May June July August September October November December])
+    ORDINALS = Ractor.make_shareable(%w[_ first second third fourth fifth])
+    UNITS = Ractor.make_shareable({ secondly: "second", minutely: "minute", hourly: "hour", daily: "day", weekly: "week",
+                                    monthly: "month", yearly: "year" })
+    DAY = 86_400
+
+    # What repeats: secs are seconds of the day, sorted, each hour said with each minute said (R4)
+    # @api private
+    Parts = Struct.new(:freq, :interval, :month, :monthdays, :days, :nths, :setpos, :secs) do
+      def on?(day)
+        ymd = Calendar.civil_from_days(day)
+        m = ymd / 100 % 100
+        return false if month && month != m
+        d = ymd % 100
+        wday = Calendar.weekday(day)
+        dim = Calendar.days_in_month(ymd / 10_000, m) unless monthdays.empty? && nths.empty? && !setpos
+        return false unless monthdays.empty? || monthdays.any? { |md| md > 0 ? md == d : dim + md + 1 == d }
+        return false unless nths.empty? || nths.any? { |n, w| w == wday && (n > 0 ? (d - 1) / 7 + 1 == n : (dim - d) / 7 + 1 == -n) }
+        return false unless days.empty? || days.include?(wday)
+        return true unless setpos
+        picked = (1..dim).select { |x| days.include?(Calendar.weekday(day - d + x)) }
+        setpos.any? { |n| picked[n > 0 ? n - 1 : n] == d }
+      end
+    end
+
+    # text: the input it was read from; zone: the zone its wall times are in
+    attr_reader :text, :zone
+
+    # @api private: rules come from recurrence and from_cron.
+    # start: local wall seconds when timed, else a day number; until_: a UTC epoch when timed, else a day number;
+    # exdates: as start; dst: the dst: policy occurrences follow (R18); now: the epoch it was read at
+    def initialize(parts, zone, start, timed, count, until_, exdates, started, dst = nil, now:, text:)
+      @parts = parts
+      @zone = zone
+      @start = start
+      @timed = timed
+      @count = count
+      @until = until_
+      @exdates = exdates
+      @started = started
+      @dst = dst
+      @now = now
+      @text = -text
+      Ractor.make_shareable(self)
+    end
+
+    def kind = :rule
+
+    # The now it was read at, in its zone: where next counts from (R16)
+    def now = Time.at(@now, in: Zone.for(@zone).offset_at(@now))
+
+    def rrule
+      p = @parts
+      out = ["FREQ=#{p.freq.upcase}"]
+      out << "INTERVAL=#{p.interval}" if p.interval > 1
+      out << "BYMONTH=#{p.month}" if p.month
+      out << "BYMONTHDAY=#{p.monthdays.join(",")}" unless p.monthdays.empty?
+      byday = p.nths.map { |n, w| "#{n}#{DAYS[w]}" } + sorted_days.map { DAYS[_1] }
+      out << "BYDAY=#{byday.join(",")}" unless byday.empty?
+      out << "BYSETPOS=#{p.setpos.join(",")}" if p.setpos
+      unless p.secs.empty?
+        out << "BYHOUR=#{p.secs.map { _1 / 3600 }.uniq.join(",")}"
+        out << "BYMINUTE=#{p.secs.map { _1 / 60 % 60 }.uniq.sort.join(",")}"
+        out << "BYSECOND=#{p.secs[0] % 60}" if p.secs[0] % 60 != 0
+      end
+      out << "COUNT=#{@count}" if @count
+      out << "UNTIL=#{@timed ? Time.at(@until).utc.strftime("%Y%m%dT%H%M%SZ") : ymd(@until)}" if @until
+      out.join(";")
+    end
+
+    # A Time in the zone when the rule has a clock, else a Date
+    def dtstart
+      return ::Date.new(*civil(@start)) unless @timed
+      utc = Zone.for(@zone).local_to_utc(@start, Notes.new)
+      Time.at(utc, in: Zone.for(@zone).offset_at(utc))
+    end
+
+    def to_ical
+      lines = ["DTSTART#{form}:#{stamp(@start)}", "RRULE:#{rrule}"]
+      lines << "EXDATE#{form}:#{@exdates.map { stamp(_1) }.join(",")}" unless @exdates.empty?
+      lines.join("\n")
+    end
+
+    def to_s
+      p = @parts
+      if (window = steps)
+        return "#{window}#{tail}" if p.freq == :daily && p.interval == 1
+        return "#{window} on #{weekdays(plural: true)}#{tail}" if p.freq == :weekly && p.interval == 1 && !p.days.empty?
+      end
+      out = +if !p.nths.empty?
+               "the #{list(p.nths.sort_by(&:first).map { ordinal(_1[0]) })} #{DAY_NAMES[p.nths[0][1]]} of #{every("month")}"
+             elsif p.setpos
+               "the #{list(p.setpos.map { ordinal(_1) })} weekday of #{every("month")}"
+             elsif p.month
+               "#{every("year")} on #{MONTH_NAMES[p.month]} #{p.monthdays[0]}"
+             elsif !p.monthdays.empty?
+               "the #{list(p.monthdays.map { _1 == -1 ? "last day" : nth(_1) })} of #{every("month")}"
+             elsif !p.days.empty?
+               "#{every(nil)} #{weekdays}"
+             else
+               every(UNITS[p.freq])
+             end
+      if window then out << " #{window}"
+      elsif !p.secs.empty? then out << " at #{list(p.secs.map { Describe.clock(_1) })}"
+      end
+      out << tail
+    end
+
+    def to_h
+      line, reason = cron_or_reason
+      { kind: "rule", text: @text, description: to_s, rrule: rrule, dtstart: @timed ? dtstart.iso8601 : dtstart.to_s,
+        zone: @zone, ical: to_ical, cron: line, cron_reason: reason }
+    end
+
+    def to_json(*args) = to_h.to_json(*args)
+
+    def as_json(*) = JSON.parse(to_json)
+
+    def ==(other) = Rule === other && other.to_ical == to_ical
+
+    alias eql? ==
+
+    def hash = to_ical.hash
+
+    def inspect = "#<Acute::Rule #{to_ical.tr("\n", " ")}>"
+
+    private
+
+    Notes = Struct.new(:dst)
+    FINE = { hourly: true, minutely: true, secondly: true }.freeze
+    private_constant :DAY, :FINE, :DAYS, :DAY_NAMES, :MONTH_NAMES, :ORDINALS, :UNITS, :Notes
+
+    # The count, start and end, as to_s ends with them
+    def tail
+      out = +""
+      out << " #{@count} times" if @count
+      out << " starting #{date(@timed ? @start.div(DAY) : @start)}" if @started
+      out << " until #{@timed ? until_local : date(@until)}" if @until
+      out << " except #{list(exceptions)}" unless @exdates.empty?
+      out
+    end
+
+    # R4: several minutes past the hour, evenly spaced through a window of the day, as "every 15 minutes from
+    # 9am to 6pm", its end left out (R27); nil for one minute, two times, or times no step reaches
+    def steps
+      secs = @parts.secs
+      return if secs.size < 3 || secs.map { _1 / 60 % 60 }.uniq.size < 2
+      step = secs[1] - secs[0]
+      return unless 3600 % step == 0 && secs.each_cons(2).all? { _2 - _1 == step }
+      stop = secs[-1] + step >= DAY ? "midnight" : Describe.clock(secs[-1] + step)
+      "every #{step / 60} minutes from #{Describe.clock(secs[0])} to #{stop}"
+    end
+
+    def form = @timed ? ";TZID=#{@zone}" : ";VALUE=DATE"
+
+    def stamp(t)
+      return ymd(t) unless @timed
+      s = t % DAY
+      format("%sT%02d%02d%02d", ymd(t.div(DAY)), s / 3600, s / 60 % 60, s % 60)
+    end
+
+    def ymd(day) = format("%08d", Calendar.civil_from_days(day))
+
+    def civil(day)
+      x = Calendar.civil_from_days(day)
+      [x / 10_000, x / 100 % 100, x % 100]
+    end
+
+    def date(day)
+      y, m, d = civil(day)
+      "#{Result::MONTHS[m - 1]} #{d}, #{y}"
+    end
+
+    # R12: the excepted dates. On an hourly or finer rule a day keeps each excepted time unless they are all
+    # of that day's occurrences, so it reads back to the same EXDATEs.
+    def exceptions
+      return @exdates.map { date(@timed ? _1.div(DAY) : _1) }.uniq unless FINE[@parts.freq]
+      @exdates.group_by { _1.div(DAY) }.flat_map do |day, walls|
+        walls.sort == day_walls(day) ? date(day) : walls.map { "#{date(day)} #{Describe.clock(_1 % DAY)}" }
+      end
+    end
+
+    # The wall times this rule, without its exceptions, occurs at on a local day
+    def day_walls(day)
+      base = Rule.new(@parts, @zone, @start, @timed, @count, @until, [], @started, @dst, now: @now, text: @text)
+      lead = Time.at(day * DAY - 15 * 3600)
+      base.each(after: lead).lazy.map { _1.to_i + _1.utc_offset }.select { _1 >= day * DAY }
+          .take_while { _1 < (day + 1) * DAY }.to_a.uniq
+    end
+
+    # The day an UNTIL ends, or the instant when it isn't a day's last second (R10)
+    def until_local
+      t = @until + Zone.for(@zone).offset_at(@until)
+      t % DAY == DAY - 1 ? date(t.div(DAY)) : "#{date(t.div(DAY))} #{Describe.clock(t % DAY)}"
+    end
+
+    def sorted_days = @parts.days.sort_by { (_1 + 6) % 7 }
+
+    def weekdays(plural: false)
+      days = sorted_days
+      s = plural ? "s" : ""
+      return "weekday#{s}" if days == [1, 2, 3, 4, 5]
+      return "weekend#{s}" if days == [6, 0]
+      list(days.map { |day| "#{DAY_NAMES[day]}#{s}" })
+    end
+
+    # "every month", "every other week", "every 3 days"; unit nil for weekdays, which take the interval in weeks
+    def every(unit)
+      n = @parts.interval
+      return "every" if unit.nil? && n == 1
+      return "every #{unit}".rstrip if n == 1
+      return "every other #{unit}".rstrip if n == 2
+      unit ? "every #{n} #{unit}s" : "every #{n} weeks on"
+    end
+
+    def ordinal(n) = n == -1 ? "last" : n < 0 ? "#{ORDINALS[-n]} to last" : ORDINALS[n]
+
+    def nth(n) = "#{n}#{n % 100 / 10 == 1 ? "th" : { 1 => "st", 2 => "nd", 3 => "rd" }.fetch(n % 10, "th")}"
+
+    def list(items) = items.size == 1 ? items[0] : "#{items[0..-2].join(", ")} and #{items[-1]}"
+  end
+end
+require_relative "rule/cron"

data/lib/acute/tables/assumptions.rb

@@ -0,0 +1,39 @@
+# GENERATED by bin/generate from data/assumptions.yml; do not edit
+# frozen_string_literal: true
+
+module Acute
+  module Tables
+    ASSUMPTIONS = {
+      bare_hour_window: ["D4", "no am/pm given: 6-11 read as am, 12 and 1-5 as pm; the other half of the day is an alternative", "no am/pm: 6-11 am, 12-5 pm; the other is an alternative"].freeze,
+      next_occurrence: ["D23", "that time has passed today, so it means the next one", "that time has passed today, so the next one"].freeze,
+      previous_occurrence: ["D23", "that time is still to come today, so in past context it means the previous one", "still to come today, so looking back, the previous one"].freeze,
+      equal_to_now: ["D36", "that time is now", "that is now"].freeze,
+      twelve_oclock: ["D30", "a time in the 12 o'clock hour without am/pm is read as pm", "the 12 o'clock hour without am/pm is pm"].freeze,
+      midnight_end_of_day: ["D6", "midnight with a day means the end of that day; its start is an alternative", "midnight is the day's end; its start is an alternative"].freeze,
+      machine_time: ["D29", "seconds were given, so the time is read as 24-hour", "seconds given, so read as 24-hour"].freeze,
+      tomorrow_after_midnight: ["D35", "\"tomorrow\" said before 04:00 means the coming day first; the calendar tomorrow is an alternative", "\"tomorrow\" before 4am: today; next day is an alternative"].freeze,
+      dst_repeated_time: ["D23", "that wall time happens twice as clocks go back; the earlier one is used", "occurs twice as clocks go back; the earlier is used"].freeze,
+      dst_skipped_time: ["D23", "that wall time doesn't exist as clocks go forward; it is moved forward by the gap", "skipped as clocks go forward; moved on by the gap"].freeze,
+      approximate: ["D14", "the time was given as approximate; the exact time is returned", "approximate time; the exact time is given"].freeze,
+      fixed_offset: ["D18", "the text names a zone or offset, which wins over the zone given", "the text's zone wins over the zone given"].freeze,
+      ambiguous_zone: ["D38", "the zone abbreviation names more than one zone; each one's offset is a reading, in order", "ambiguous zone abbreviation; each zone is a reading"].freeze,
+      numeric_date_order: ["D10", "a numeric date is read in the locale's order; the other order is an alternative", "numeric date in locale order; the other is an alternative"].freeze,
+      part_of_day_point: ["D1", "a part of the day is a range; its time is a representative point", "a part of the day is a range; time is a point in it"].freeze,
+      weekend_friday_evening: ["D8", "the weekend is Saturday 00:00 to Monday 00:00; from Friday 18:00 is an alternative", "weekend is Sat-Sun; from Friday 6pm is an alternative"].freeze,
+      meteorological_season: ["D3", "seasons are meteorological (three whole months) for the locale's hemisphere", "seasons are whole months, for the locale's hemisphere"].freeze,
+      century_from_00: ["D12", "a century runs from its 00 year, as most people count it; the 01-to-00 reading is an alternative", "a century starts at year 00; from 01 is an alternative"].freeze,
+      decade_or_century: ["D12", "a decade at a century's start (\"the 2000s\") is the decade; the whole century is an alternative", "the decade is used; the whole century is an alternative"].freeze,
+      season_year: ["D3", "a season that runs over New Year belongs to the year it starts in; the one ending in that year is an alternative", "season by its start year; the end year is an alternative"].freeze,
+      range_under_way: ["D11", "the range is under way, so it means the current one; the coming one is an alternative", "under way, so the current one; the next is an alternative"].freeze,
+      same_day_or_next: ["D11", "that day is today, so it means today; the next one is an alternative", "that day is today; the next one is an alternative"].freeze,
+      same_day_passed: ["D11", "that day is today but today's has passed (or, said looking back, has not come yet), so the other one comes first; today's is an alternative", "the next (or previous) one first; today's is an alternative"].freeze,
+      next_two_readings: ["D20", "\"next\" can mean the coming one or the one after; both are given, the coming one first", "\"next\": the coming one; the one after is an alternative"].freeze,
+      this_passed: ["D21", "that one has passed in the current period, so the next one comes first; the passed one is an alternative", "passed, so the next one; the passed one is an alternative"].freeze,
+      rolling_window: ["D31", "a span counted from now; whole calendar units are alternatives", "counted from now; calendar units are alternatives"].freeze,
+      zone_inferred: [nil, "no zone was given; the zone comes from now, Time.zone or the system", "no zone given, so a default zone is used"].freeze,
+      weekday_mismatch: ["D37", "the weekday given doesn't fall on that date, so the date is used", "the weekday doesn't match the date; the date is used"].freeze,
+      also_duration: ["D45", "the text also reads as a length of time, which Acute.duration gives; read takes the time", "also reads as a length of time; this is the time"].freeze,
+      unknown_words_skipped: ["D22", "strict: false skipped words acute doesn't know; this is the first time in the rest of the text", "skipped unknown words; first time in the rest"].freeze,
+    }.freeze
+  end
+end