acute 1.0.0

data/lib/acute/cli.rb

@@ -0,0 +1,168 @@
+require "optparse"
+require_relative "../acute"
+
+module Acute
+  # exe/acute: one phrase from the arguments, or one per line from stdin (D45)
+  # @api private
+  class CLI
+    CLOCK_GRAINS = %i[second minute hour].freeze
+    # the library's DST hints name its Ruby option; the command's name its flag
+    DST_HINTS = { dst_skipped_time: "--dst earlier, later or compatible picks an instant for it",
+                  dst_repeated_time: "--dst earlier or later picks one" }.freeze
+
+    def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr) = new(stdin, stdout, stderr).run(argv)
+
+    def initialize(stdin, stdout, stderr)
+      @stdin = stdin
+      @out = stdout
+      @err = stderr
+      @json = false
+      @next = nil
+      @options = {}
+    end
+
+    def run(argv)
+      return mcp(argv.drop(1)) if argv.first == "mcp"
+      args = options.parse(argv)
+      return say(@say) if @say
+      @parser = Acute.with(**@options)
+      return phrase(args.join(" ")) if args.any?
+      return usage if @stdin.tty?
+      @out.sync = true
+      @stdin.each_line.map { _1.b.strip.empty? || line(_1.chomp) }.all? ? 0 : 1
+    rescue OptionParser::ParseError, ArgumentError => e
+      @err.puts "acute: #{Acute.visible(e.message.scrub)}"
+      2
+    end
+
+    private
+
+    def options
+      OptionParser.new do |o|
+        o.banner = "Usage: acute [options] PHRASE\n       acute [options] < phrases.txt   (one per line)\n       " \
+                   "acute mcp [options]             (an MCP server: acute mcp --help)"
+        o.on("--json", "Print JSON (JSON Lines for stdin)") { @json = true }
+        o.on("--next N", Integer, "A rule's first N occurrences, 1–#{Rule::MAX_OCCURRENCES}") do |n|
+          raise OptionParser::InvalidArgument, n.to_s unless (1..Rule::MAX_OCCURRENCES).cover?(n)
+          @next = n
+        end
+        o.on("--now TIME", "Now, in ISO 8601 (default: the clock)") { @options[:now] = _1 }
+        o.on("--zone ZONE", "IANA zone or offset (default: the system's)") { @options[:zone] = _1 }
+        o.on("--locale LOCALE", "en-US, en-GB, en-AU… (default: from the zone)") { @options[:locale] = _1 }
+        o.on("--context CONTEXT", %w[future past], "future or past") { @options[:context] = _1.to_sym }
+        o.on("--week-start DAY", %w[sunday monday], "sunday or monday") { @options[:week_start] = _1.to_sym }
+        o.on("--hemisphere SIDE", %w[north south], "north or south, for seasons") { @options[:hemisphere] = _1.to_sym }
+        o.on("--fiscal-year-start MONTH", Integer, "1–12") { @options[:fiscal_year_start] = _1 }
+        o.on("--lenient", "Skip unknown words (strict: false)") { @options[:strict] = false }
+        o.on("--dst POLICY", %w[compatible earlier later reject], "compatible, earlier, later or reject") { @options[:dst] = _1.to_sym }
+        o.on("--holidays REGION", "A holidays-gem region, such as us (needs the gem)") { @options[:holidays] = _1 }
+        o.on("--year-bias YEARS", Integer, "Two-digit years: the 100 from this many years ago (default 50)") { @options[:year_bias] = _1 }
+        o.on("-v", "--version") { @say = Acute::VERSION }
+        o.on("-h", "--help") { @say = o.to_s }
+      end
+    end
+
+    # The options an operator fixes for every call. now is always the clock; the model may pass zone per call.
+    def mcp(argv)
+      options = {}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: acute mcp [options]\n" \
+                   "Serves acute's tools to an MCP client over stdio: one JSON-RPC message per line."
+        o.on("--zone ZONE", "IANA zone or offset when a call names none (default: the system's)") { options[:zone] = _1 }
+        o.on("--locale LOCALE", "en-US, en-GB, en-AU… (default: from the zone)") { options[:locale] = _1 }
+        o.on("--context CONTEXT", %w[future past], "Default for calls that give none: future or past") { options[:context] = _1.to_sym }
+        o.on("--week-start DAY", %w[sunday monday], "sunday or monday") { options[:week_start] = _1.to_sym }
+        o.on("-h", "--help") { return say(o.to_s) }
+      end
+      extra = parser.parse(argv)
+      raise OptionParser::NeedlessArgument, extra.join(" ") if extra.any?
+      require_relative "mcp"
+      server = MCP.new(Tool.new(**options), log: @err)
+      @stdin.binmode
+      server.serve(@stdin, @out)
+      0
+    end
+
+    def say(text)
+      @out.puts text
+      0
+    end
+
+    def usage
+      @err.puts options
+      2
+    end
+
+    # A single phrase that fails exits 1 with parse!'s reason
+    def phrase(text)
+      value = reading(text)
+      return show(value) || 0 if value
+      @parser.parse!(text)
+    rescue ParseError => e
+      @json ? @out.puts(failure(e, text)) : @err.puts("acute: #{e.message}")
+      1
+    end
+
+    def line(text)
+      value = reading(text)
+      return show(value, batch: true) || true if value
+      @parser.parse!(text)
+    rescue ParseError => e
+      @out.puts @json ? failure(e, text) : "error: #{e.message}"
+      false
+    end
+
+    # schema/failure.json, as the tools give it, plus the input line, which a tool never echoes. Like the tools, a
+    # position over the whole phrase is left out.
+    def failure(e, text)
+      text = text.dup.force_encoding(Encoding::UTF_8).scrub
+      json = { kind: "failure", text:, code: e.code.to_s, error: e.message }
+      json[:position] = [e.position.begin, e.position.end] unless whole?(e.position, text)
+      json[:hint] = DST_HINTS.fetch(e.code, e.hint) if e.hint
+      JSON.generate(json)
+    end
+
+    def whole?(span, text) = text[0...span.begin].strip.empty? && text[span.end..].to_s.strip.empty?
+
+    # --next asks for a rule, so a phrase that isn't one fails with recurrence!'s reason
+    def reading(text) = @next ? @parser.recurrence!(text) : @parser.read(text)
+
+    # A rule is several lines, joined into one for stdin's one line per phrase
+    def show(value, batch: false)
+      return @out.puts(@json ? value.to_json : echo(value)) unless Rule === value
+      at = @next && occurrences(value)
+      return @out.puts(at ? value.to_h.merge(next: at.map(&:iso8601)).to_json : value.to_json) if @json
+      lines = [value.to_s, *value.to_ical.lines(chomp: true)]
+      lines << "cron: #{value.cron} (CRON_TZ=#{value.zone})" if value.cron
+      lines.concat(at.map { occurrence(_1, value.zone) }) if at
+      @out.puts batch ? lines.join("   ") : lines
+    end
+
+    # The rule's first n occurrences, DTSTART's included: the Date before it starts the search
+    def occurrences(rule) = rule.next!(@next, after: rule.dtstart.to_date - 1)
+
+    def occurrence(at, zone)
+      text = @parser.describe(at, zone: zone, style: :calendar)
+      Time === at ? "#{text} #{Zone.for(zone).abbreviation_at(at.to_i)}" : text
+    end
+
+    # "Fri, Oct 23, 3pm EDT   (also: Fri, Oct 16, 3pm)"
+    def echo(value)
+      return @parser.describe(value) if Duration === value
+      text = described(value)
+      return text unless value.ambiguous?
+      said = abbreviation(value)
+      "#{text}   (also: #{value.alternatives.map { described(_1, said) }.join("; ")})"
+    end
+
+    # A time of day names its zone, unless describe already did or the echo already has
+    def described(r, said = nil)
+      text = @parser.describe(r, zone: r.zone, style: :calendar)
+      abbr = abbreviation(r)
+      return text if abbr.nil? || abbr == said || text.end_with?(abbr) || text.match?(/[+-]\d\d:\d\d\z/)
+      "#{text} #{abbr}"
+    end
+
+    def abbreviation(r) = CLOCK_GRAINS.include?(r.grain) ? Zone.for(r.zone).abbreviation_at(r.time.to_i) : nil
+  end
+end

data/lib/acute/context.rb

@@ -0,0 +1,205 @@
+require "date"
+require_relative "calendar"
+require_relative "zone"
+require_relative "assumption"
+require_relative "locale"
+require_relative "holidays"
+
+module Acute
+  # Everything a parse depends on besides the text: now, the zone and the direction. It also collects the
+  # assumptions the resolver makes, so it is built fresh for every parse.
+  # @api private
+  class Context
+    ISO = /\A(\d{4})-(\d\d)-(\d\d)(?:[T ](\d\d):(\d\d)(?::(\d\d)(?:\.\d+)?)?)?(Z|[+-]\d\d:?\d\d)?\z/
+
+    # TZ may start with POSIX's ":", and /etc/localtime may link into posix/ or right/, or to a zone the shipped
+    # data doesn't hold: only a name acute ships is used, so a parse without zone: never raises for it
+    def self.system_zone(tz = ENV["TZ"], link = "/etc/localtime")
+      tz = tz&.delete_prefix(":")
+      return tz if tz && Zone.known?(tz)
+      name = File.readlink(link)[%r{zoneinfo/(?:posix/|right/)?(.+)\z}, 1]
+      name && Zone.known?(name) ? name : "UTC"
+    rescue SystemCallError
+      "UTC"
+    end
+
+    SYSTEM_ZONE = system_zone.freeze
+    ZONE_INFERRED = Assumption.for(:zone_inferred)
+    NO_NOTES = [].freeze
+
+    WEEK_STARTS = { sunday: 0, monday: 1 }.freeze
+    HEMISPHERES = { north: false, south: true }.freeze
+    DST_POLICIES = { compatible: nil, earlier: :earlier, later: :later, reject: :reject }.freeze
+    YEAR_BIAS = 50
+
+    attr_reader :now, :now_local, :zone, :today, :now_secs, :notes, :fiscal_year_start, :strict, :dst_policy,
+                :holidays, :year_bias
+    # past: true in past context; :back while resolve looks back for the most recent one, which adds no
+    # alternatives of its own (D44)
+    attr_accessor :dst, :past, :machine
+    # D47: the fraction of a second a clock in the text was written with
+    attr_accessor :frac
+
+    # The zone a TimeWithZone, or a Time made with a TZInfo zone, brings with it
+    def self.carried_zone(now)
+      if now.respond_to?(:time_zone) then now.time_zone.tzinfo
+      elsif now.is_a?(Time) && Zone.tzinfo?(now.zone) then now.zone
+      end
+    end
+
+    def initialize(now, zone, context, locale = nil, week_start = nil, hemisphere = nil, fiscal_year_start = nil,
+                   strict = true, dst = nil, holidays = nil, business_days = nil, year_bias = nil)
+      @past = case context
+              when :future then false
+              when :past then true
+              else raise OptionError.new("context: must be :future or :past", option: :context, value: context)
+              end
+      if zone
+        @zone = Zone.for(zone)
+      else
+        @zone = Zone.for(Context.carried_zone(now) || rails_zone || SYSTEM_ZONE)
+        @inferred = true
+      end
+      @now = Time === now ? now.to_i : epoch(now)
+      self.zone = @zone
+      @locale_zone = @zone.name
+      @strict = strict
+      @year_bias = YEAR_BIAS
+      # Most parses give none of the other options, and then skip their checks
+      return unless locale || week_start || hemisphere || fiscal_year_start || strict != true || dst || holidays || business_days || year_bias
+      options(now, zone, context, locale, week_start, hemisphere, fiscal_year_start, strict, dst, holidays, business_days, year_bias)
+    end
+
+    def fresh = Context.new(*@args).tap { _1.budget = budget }
+
+    # D49: the business days this call may still count, shared with the contexts it makes for each piece (T17)
+    attr_writer :budget
+
+    def budget = @budget ||= Resolve::Period::Budget.new
+
+    # D47: the days business-day counts step over, or nil for Monday to Friday. The built-in holidays only name
+    # days; a holidays: given is taken as days off.
+    def business_days = @business_days || (@holidays && (budget.workdays ||= Holidays.workdays(@holidays)))
+
+    # Under a zone named in the text, today and now_secs move with it; returns the block's value
+    def in_zone(zone)
+      home = @zone
+      now_local = @now_local
+      self.zone = zone
+      out = yield
+      @zone = home
+      @now_local = now_local
+      @today = now_local / 86_400
+      @now_secs = now_local - @today * 86_400
+      out
+    end
+
+    private def zone=(zone)
+      @zone = zone
+      @now_local = local = @now + zone.offset_at(@now)
+      @today = local / 86_400
+      @now_secs = local - @today * 86_400
+    end
+
+    # The wall time of an instant, in local seconds
+    def local(utc) = utc + @zone.offset_at(utc)
+
+    # Found only when a phrase needs it, from the zone given rather than one named in the text
+    def locale = @locale ||= Locale.for_zone(@locale_zone)
+
+    def week_start = @week_start ||= locale.week_start
+
+    def south = @south.nil? ? (@south = locale.south) : @south
+
+    def past? = @past
+
+    def note(assumption)
+      if @notes
+        @notes << assumption unless @notes.include?(assumption)
+      else
+        @notes = [assumption]
+      end
+    end
+
+    def unnote(assumption) = @notes&.delete(assumption)
+
+    # The main reading's assumptions: the rules applied, then its DST adjustment, then the zone
+    def assumptions(main)
+      dst = main.dst unless @dst_policy # D47: a policy the caller chose is not an assumption
+      return NO_NOTES unless @notes || dst || @inferred
+      list = @notes || []
+      list << Assumption.for(dst) if dst
+      list << ZONE_INFERRED if @inferred
+      list.freeze
+    end
+
+    private
+
+    def options(now, zone, context, locale, week_start, hemisphere, fiscal_year_start, strict, dst, holidays, business_days, year_bias)
+      raise OptionError.new("strict: must be true or false", option: :strict, value: strict) unless strict == true || strict == false
+      @locale = Locale.for(locale) if locale
+      @week_start = week_start && choice(:week_start, week_start, WEEK_STARTS, ":sunday or :monday")
+      @south = hemisphere && choice(:hemisphere, hemisphere, HEMISPHERES, ":north or :south")
+      @fiscal_year_start = fiscal_year_start && whole(:fiscal_year_start, fiscal_year_start, 1..12, "a month, 1 to 12")
+      unless strict
+        # Lenient parsing resolves each piece it tries in a fresh context
+        @args = [now || Time.at(@now), zone, context, locale, week_start, hemisphere, fiscal_year_start, strict, dst,
+                 holidays, business_days, year_bias]
+      end
+      @dst_policy = dst && choice(:dst, dst, DST_POLICIES, ":compatible, :earlier, :later or :reject")
+      @holidays = holidays && Holidays.for(holidays)
+      if business_days
+        unless business_days.respond_to?(:business_day?)
+          raise OptionError.new("business_days: must answer business_day?(date)", option: :business_days,
+value: business_days)
+        end
+        @business_days = business_days
+      end
+      @year_bias = whole(:year_bias, year_bias, 0..99, "a number of years, 0 to 99") if year_bias
+    end
+
+    def choice(option, value, table, allowed)
+      key = (Symbol === value || (String === value && value.valid_encoding?)) && value.to_sym
+      table.fetch(key) { raise OptionError.new("#{option}: must be #{allowed}", option: option, value: value) }
+    end
+
+    def whole(option, value, range, allowed)
+      n = Integer === value ? value : (String === value && Integer(value, 10, exception: false))
+      return n if n && range.cover?(n)
+      raise OptionError.new("#{option}: must be #{allowed}", option: option, value: value)
+    end
+
+    def rails_zone
+      Time.zone&.tzinfo if defined?(ActiveSupport::TimeZone) && Time.respond_to?(:zone)
+    end
+
+    def epoch(now)
+      case now
+      when nil then Time.now.to_i
+      when Time then now.to_i
+      when DateTime then now.to_time.to_i
+      when Date then @zone.local_to_utc((now.jd - 2_440_588) * 86_400, self)
+      when String then iso_epoch(now)
+      else
+        return now.to_i if now.respond_to?(:time_zone)
+        raise OptionError.new("now: must be a Time, Date or ISO 8601 String", option: :now, value: now)
+      end
+    end
+
+    def iso_epoch(str)
+      m = str.valid_encoding? && ISO.match(str) or raise OptionError.new("now: #{Acute.quote(str)} is not ISO 8601", option: :now, value: str)
+      y, mo, d, h, mi, s = m.captures.first(6).map(&:to_i)
+      offset = m[7]&.delete(":")
+      # an offset is within ±23:59, as a zone's is
+      unless mo.between?(1, 12) && d.between?(1, Calendar.days_in_month(y, mo)) && h < 24 && mi < 60 && s < 60 &&
+             (offset.nil? || offset == "Z" || (offset[1, 2].to_i < 24 && offset[3, 2].to_i < 60))
+        raise OptionError.new("now: #{Acute.quote(str)} is not a valid time", option: :now, value: str)
+      end
+      local = Calendar.days_from_civil(y, mo, d) * 86_400 + h * 3600 + mi * 60 + s
+      return @zone.local_to_utc(local, self) unless offset
+      return local if offset == "Z"
+      sign = offset.start_with?("-") ? -1 : 1
+      local - sign * (offset[1, 2].to_i * 3600 + offset[3, 2].to_i * 60)
+    end
+  end
+end

data/lib/acute/describe.rb

@@ -0,0 +1,316 @@
+module Acute
+  def self.describe(value, now: nil, zone: nil, context: :future, locale: nil, week_start: nil, hemisphere: nil,
+                    fiscal_year_start: nil, strict: true, dst: nil, holidays: nil, business_days: nil, year_bias: nil,
+                    style: :relative)
+    raise OptionError.new("style: must be :relative or :calendar", option: :style, value: style) unless Describe::STYLES.include?(style)
+    zone ||= value.zone if Result === value
+    ctx = Context.new(now, zone, context, locale, week_start, hemisphere, fiscal_year_start, strict, dst, holidays,
+                      business_days, year_bias)
+    return Describe.duration(value) if Duration === value
+    return value.to_s if Rule === value
+    # strict: is left out: what describe writes always reads back strictly
+    opts = { now: Time.at(ctx.now), zone: zone || ctx.zone.name, context: context, locale: locale,
+             week_start: week_start, hemisphere: hemisphere, fiscal_year_start: fiscal_year_start, dst: dst,
+             holidays: holidays, business_days: business_days, year_bias: year_bias }
+    Describe.new(value, style == :calendar, ctx, opts).text
+  end
+
+  # English that Acute.parse reads back as the value given (D45). Candidates come most natural first; each is
+  # parsed with the same now, zone and options, and the first that gives the value as its only reading wins.
+  # The last candidates write the date, the year, the zone and finally ISO 8601, which always read back.
+  # @api private
+  class Describe
+    STYLES = %i[relative calendar].freeze
+    MONTHS = Result::MONTHS
+    WEEKDAYS = Result::WEEKDAYS
+    MONTH_NAMES = Ractor.make_shareable(%w[January February March April May June July August September October
+                                           November December])
+    DAY_NAMES = Ractor.make_shareable(%w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday])
+    PARTS = Ractor.make_shareable(%w[morning afternoon evening night])
+    SEASONS = Ractor.make_shareable(%w[spring summer autumn winter])
+    DAY = 86_400
+
+    # Hours, minutes and seconds carried upward ("5400s" is "1h 30m"); never into days, which DST can stretch (D23)
+    def self.duration(d)
+      p = d.parts
+      return d.to_s unless p.keys.intersect?(%i[hours minutes seconds])
+      total = p.fetch(:hours, 0) * 3600 + p.fetch(:minutes, 0) * 60 + p.fetch(:seconds, 0)
+      h, rest = total.divmod(3600)
+      m, s = rest.divmod(60)
+      Duration.new(**p.except(:hours, :minutes, :seconds), hours: h, minutes: m, seconds: s).to_s
+    end
+
+    # "9am", "9:30am", "9:00:30am", "12am" for midnight
+    def self.clock(secs, meridiem = true)
+      h = secs / 3600
+      m = secs / 60 % 60
+      s = secs % 60
+      out = (h % 12 == 0 ? 12 : h % 12).to_s
+      out << format(":%02d", m) if m != 0 || s != 0
+      out << format(":%02d", s) if s != 0
+      out << (h < 12 ? "am" : "pm") if meridiem
+      out
+    end
+
+    # A value as the span it stands for: an instant, or begin and end with either open
+    Target = Struct.new(:b, :e, :point, :instant) do
+      def self.for(value, ctx)
+        case value
+        when Result
+          new(value.begin&.to_i, value.end&.to_i, value.time.to_i, value.instant?)
+        when Range then range(value, ctx)
+        when Date then range(value..value, ctx)
+        when DateTime, Time then new(nil, nil, value.to_time.to_i, true)
+        else
+          raise ArgumentError, "expected a Result, Time, Date, Range or Duration, got #{value.class}" unless value.respond_to?(:time_zone)
+          new(nil, nil, value.to_time.to_i, true)
+        end
+      end
+
+      # The end is exclusive, as in a Result; a Date end includes its day unless the range excludes it
+      def self.range(r, ctx)
+        b = edge(r.begin, false, ctx)
+        e = edge(r.end, !r.exclude_end?, ctx)
+        raise ArgumentError, "a range needs at least one end" unless b || e
+        raise ArgumentError, "the range runs backwards or is empty (a day the zone skipped is empty)" if b && e && e <= b
+        new(b, e, nil, false)
+      end
+
+      def self.edge(x, through, ctx)
+        case x
+        when nil then nil
+        when DateTime, Time then x.to_time.to_i
+        when Date then ctx.zone.local_to_utc((x.jd - 2_440_588 + (through ? 1 : 0)) * DAY, ctx)
+        else
+          raise ArgumentError, "a range's ends must be Times or Dates, got #{x.class}" unless x.respond_to?(:time_zone)
+          x.to_time.to_i
+        end
+      end
+    end
+
+    def initialize(value, calendar, ctx, opts)
+      @calendar = calendar
+      @ctx = ctx
+      @zone = ctx.zone
+      @opts = opts
+      @today = ctx.today
+      @day_first = ctx.locale.day_first
+      t = Target.for(value, ctx)
+      @b, @e, @point, @instant = t.b, t.e, t.point, t.instant
+    end
+
+    def text
+      found = to_enum(:candidates).find { fits?(_1) }
+      return found if found
+      return @last unless @point && !@instant
+      # No part of the day says this span's point, so the span alone is written
+      @point = nil
+      to_enum(:candidates).find { fits?(_1) } || @last
+    end
+
+    private
+
+    def fits?(text)
+      @last = text
+      r = Acute.parse(text, **@opts)
+      return false unless r && !r.ambiguous?
+      return !r.span? && r.time.to_i == @point if @instant
+      r.begin&.to_i == @b && r.end&.to_i == @e && (@point.nil? || r.time.to_i == @point)
+    end
+
+    def candidates(&)
+      return instant(@point, &) if @instant
+      return before(&) unless @b
+      return after(&) unless @e
+      part_of_day(&) if @point && @point != @b
+      aligned?(@b) && aligned?(@e) ? days(&) : span(&)
+    end
+
+    def instant(p)
+      unless @calendar
+        yield "now" if p == @ctx.now
+        w = day_word(day_of(p))
+        yield "#{w} at #{clock(secs_of(p))}" if w
+      end
+      dated(p) { yield _1 }
+    end
+
+    # "Sun, Oct 18, 9am", then with the year, its zone's abbreviation, its offset, and ISO 8601
+    def dated(p)
+      d = day_of(p)
+      c = clock(secs_of(p))
+      yield "#{date(d, false)}, #{c}"
+      at = "#{date(d, true)}, #{c}"
+      yield at
+      yield "#{at} #{@zone.abbreviation_at(p)}"
+      yield "#{at} #{offset(p)}"
+      yield iso(p)
+    end
+
+    def days_named(d)
+      if !@calendar && (w = day_word(d))
+        yield w
+      end
+      yield date(d, false)
+      yield date(d, true)
+    end
+
+    def after
+      if aligned?(@b)
+        d = day_of(@b)
+        days_named(d) { yield "#{_1} onwards" }
+        days_named(d - 1) { yield "after #{_1}" }
+      end
+      yield "after #{clock(secs_of(@b))}" unless @calendar
+      dated(@b) do |x|
+        yield "after #{x}"
+        yield "#{x} onwards"
+      end
+    end
+
+    def before
+      days_named(day_of(@e)) { yield "before #{_1}" } if aligned?(@e)
+      yield "before #{clock(secs_of(@e))}" unless @calendar
+      dated(@e) { yield "before #{_1}" }
+    end
+
+    # "tonight", "tomorrow morning", "Sun, Oct 18, morning": a part of the day with its point
+    def part_of_day
+      d = day_of(@point)
+      unless @calendar
+        if d == @today
+          yield "tonight"
+          PARTS.each { yield "this #{_1}" }
+        end
+        yield "last night" if d == @today - 1
+        if (w = day_word(d))
+          PARTS.each { yield "#{w} #{_1}" }
+        end
+      end
+      [false, true].each { |year| PARTS.each { |part| yield "#{date(d, year)}, #{part}" } }
+    end
+
+    # Whole days: a day, a named period, or the first and last days
+    def days(&)
+      d1 = day_of(@b)
+      d2 = day_of(@e)
+      return days_named(d1, &) if d2 - d1 == 1
+      y1, m1, dd1 = ymd(d1)
+      y2, m2, dd2 = ymd(d2)
+      months = (y2 - y1) * 12 + m2 - m1
+      if d2 - d1 == 7 && Calendar.weekday(d1) == @ctx.week_start
+        relative("week", &)
+        yield "the week of #{md(d1, false)}"
+        yield "the week of #{md(d1, true)}"
+      elsif dd1 == 1 && dd2 == 1
+        if months == 1
+          relative("month", &)
+          yield MONTH_NAMES[m1 - 1]
+          yield "#{MONTH_NAMES[m1 - 1]} #{y1}"
+        elsif months == 3
+          if m1 % 3 == 1
+            relative("quarter", &)
+            yield "Q#{m1 / 3 + 1}"
+            yield "Q#{m1 / 3 + 1} #{y1}"
+          end
+          SEASONS.each { yield "#{_1} #{y1}" }
+        elsif m1 == 1 && m2 == 1
+          if months == 12
+            relative("year", &)
+            yield y1.to_s
+          end
+          yield "the #{y1}s" if months == 120 && y1 % 10 == 0
+          yield "#{y1} – #{y2 - 1}"
+        end
+      end
+      yield "#{md(d1, false)} – #{md(d2 - 1, false)}"
+      yield "#{md(d1, true)} – #{md(d2 - 1, true)}"
+      yield "#{iso(@b)} – #{iso(@e)}"
+    end
+
+    def relative(unit)
+      return if @calendar
+      yield "this #{unit}"
+      yield "next #{unit}"
+      yield "last #{unit}"
+    end
+
+    # A span with clock times: "today, 2–5pm", "since Oct 10, 2pm", "Oct 10, 2pm – Oct 17, 2pm"
+    def span
+      d1 = day_of(@b)
+      s1 = secs_of(@b)
+      s2 = secs_of(@e)
+      d2 = day_of(@e)
+      c1 = clock(s1)
+      c2 = clock(s2)
+      if !@calendar && @e == @ctx.now
+        days_named(d1) { yield "since #{_1}" } if aligned?(@b)
+        yield "since #{md(d1, false)}, #{c1}"
+        dated(@b) { yield "since #{_1}" }
+      end
+      if d2 == d1 || (d2 == d1 + 1 && aligned?(@e))
+        short = s2 != 0 && (s1 < 43_200) == (s2 < 43_200) ? "#{clock(s1, false)}–#{c2}" : "#{c1}–#{c2}"
+        days_named(d1) do |x|
+          yield "#{x}, #{short}"
+          yield "#{x}, #{c1} – #{c2}"
+        end
+      end
+      if !@calendar && (w1 = day_word(d1)) && (w2 = day_word(d2))
+        yield "#{w1}, #{c1} – #{w2}, #{c2}"
+      end
+      yield "#{md(d1, false)}, #{c1} – #{md(d2, false)}, #{c2}"
+      yield "#{md(d1, true)}, #{c1} – #{md(d2, true)}, #{c2}"
+      yield "#{md(d1, true)}, #{c1} #{@zone.abbreviation_at(@b)} – #{md(d2, true)}, #{c2} #{@zone.abbreviation_at(@e)}"
+      yield "#{iso(@b)} – #{iso(@e)}"
+    end
+
+    # "today", "tomorrow", "yesterday", "Friday" up to six days ahead, "last Friday" up to six back
+    def day_word(d)
+      case d - @today
+      when 0 then "today"
+      when 1 then "tomorrow"
+      when -1 then "yesterday"
+      when 2..6 then DAY_NAMES[Calendar.weekday(d)]
+      when -6..-2 then "last #{DAY_NAMES[Calendar.weekday(d)]}"
+      end
+    end
+
+    def ymd(d)
+      x = Calendar.civil_from_days(d)
+      [x / 10_000, x / 100 % 100, x % 100]
+    end
+
+    # "Oct 18" or "18 Oct", with the year: "Oct 18, 2026", "18 Oct 2026"
+    def md(d, year)
+      y, m, dd = ymd(d)
+      @day_first ? "#{dd} #{MONTHS[m - 1]}#{" #{y}" if year}" : "#{MONTHS[m - 1]} #{dd}#{", #{y}" if year}"
+    end
+
+    # "Sun, Oct 18" or "Sun 18 Oct"
+    def date(d, year)
+      wd = WEEKDAYS[Calendar.weekday(d)]
+      @day_first ? "#{wd} #{md(d, year)}" : "#{wd}, #{md(d, year)}"
+    end
+
+    def clock(secs, meridiem = true) = Describe.clock(secs, meridiem)
+
+    def local(epoch) = epoch + @zone.offset_at(epoch)
+
+    def day_of(epoch) = local(epoch).div(DAY)
+
+    def secs_of(epoch) = local(epoch) % DAY
+
+    def day_start(d) = @zone.local_to_utc(d * DAY, @ctx)
+
+    def aligned?(epoch) = day_start(day_of(epoch)) == epoch
+
+    def offset(epoch)
+      o = @zone.offset_at(epoch)
+      format("%s%02d:%02d", o < 0 ? "-" : "+", o.abs / 3600, o.abs / 60 % 60)
+    end
+
+    def iso(epoch) = Time.at(epoch, in: @zone.offset_at(epoch)).strftime("%FT%T%:z")
+  end
+
+  private_constant :Describe
+end