acute 1.0.0

data/lib/acute/duration.rb

@@ -0,0 +1,120 @@
+require "json"
+
+module Acute
+  # A length of time as the parts said, so "1 month" stays a month rather than a guess at its seconds
+  class Duration
+    # @api private
+    UNIT_PART = Ractor.make_shareable(
+      { year: [:years, 1], decade: [:years, 10], century: [:years, 100], quarter: [:months, 3], season: [:months, 3], month: [:months, 1],
+        week: [:weeks, 1], fortnight: [:weeks, 2], day: [:days, 1], business_day: [:business_days, 1],
+        hour: [:hours, 1], minute: [:minutes, 1], second: [:seconds, 1] }
+    )
+    FIXED = { weeks: 604_800, days: 86_400, hours: 3600, minutes: 60, seconds: 1 }.freeze
+    SHORT = Ractor.make_shareable({ years: "y", months: "mo", weeks: "w", business_days: " business days", days: "d",
+                                    hours: "h", minutes: "m", seconds: "s" })
+    LONG = Ractor.make_shareable({ years: "year", months: "month", weeks: "week", business_days: "business day",
+                                   days: "day", hours: "hour", minutes: "minute", seconds: "second" })
+    ORDER = SHORT.keys.freeze
+    private_constant :FIXED, :SHORT, :LONG, :ORDER
+    UNIT = { years: :year, months: :month, weeks: :week, business_days: :business_day, days: :day, hours: :hour,
+             minutes: :minute }.freeze
+
+    attr_reader :parts
+
+    # A fraction goes to the next smaller unit: "1.5 hours" is 1h 30m, "3.5 years" 3y 6mo; past seconds it stays
+    def self.from_units(units)
+      parts = Hash.new(0)
+      units.each do |u|
+        count = u.count
+        unit = u.unit
+        loop do
+          part, k = UNIT_PART.fetch(unit)
+          n = (smaller = Resolve::Period::SMALLER[unit]) ? count.floor : count
+          parts[part] += n * k
+          break if (count -= n).zero?
+          unit, m = smaller
+          count *= m
+        end
+      end
+      new(**parts)
+    end
+
+    def initialize(**parts)
+      unknown = parts.keys - ORDER
+      raise ArgumentError, "unknown duration parts: #{unknown.join(", ")}" if unknown.any?
+      @parts = ORDER.filter_map { |k| [k, whole(parts[k])] if parts[k] && parts[k] != 0 }.to_h.freeze
+      freeze
+    end
+
+    def kind = :duration
+
+    # With from:, the seconds from that Time to #after it
+    def seconds(from: nil, **ctx)
+      return whole(after(from, **ctx).to_r - from.to_r) if from
+      calendar = @parts.keys - FIXED.keys
+      if calendar.any?
+        raise ArgumentError, "a #{LONG[calendar[0]]} has no fixed length; use #after or #seconds(from:)"
+      end
+      @parts.sum { |k, n| n * FIXED[k] }
+    end
+
+    # D47: the Time this long after time, as "<this> from <time>" reads (D23): years and months first, on the
+    # calendar, then weeks and days of wall clock, then hours to seconds of elapsed time
+    def after(time, 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)
+      ctx = Context.new(time, zone, context, locale, week_start, hemisphere, fiscal_year_start, strict, dst, holidays,
+                        business_days, year_bias)
+      seconds = @parts.fetch(:seconds, 0)
+      node = @parts.reduce(nil) do |anchor, (part, n)|
+        part == :seconds ? anchor : Grammar::Shift.new(n, UNIT[part], anchor)
+      end
+      node = Grammar::Shift.new(seconds.floor, :second, node) if node.nil? || seconds.floor != 0
+      readings = Resolve.call(node, ctx, failure: true)
+      raise Explain.error(readings, to_s) if Failure === readings
+      epoch = readings[0].begin
+      Time.at(epoch, in: ctx.zone.offset_at(epoch)) + (seconds - seconds.floor) + (Time === time ? time.subsec : 0)
+    end
+
+    # Weeks alone stay weeks ("P2W"); ISO 8601 has no business days, so those give nil
+    def iso8601
+      return if @parts.key?(:business_days)
+      return "P#{@parts[:weeks]}W" if @parts.keys == [:weeks]
+      p = @parts
+      days = p.fetch(:days, 0) + p.fetch(:weeks, 0) * 7
+      date = [[p[:years], "Y"], [p[:months], "M"], [days.nonzero?, "D"]].filter_map { |n, l| "#{num(n)}#{l}" if n }.join
+      time = [[p[:hours], "H"], [p[:minutes], "M"], [p[:seconds], "S"]].filter_map { |n, l| "#{num(n)}#{l}" if n }.join
+      "P#{date}#{"T#{time}" unless time.empty?}"
+    end
+
+    def to_s(style = :short)
+      if style == :short
+        return @parts.map { |k, n| k == :business_days && n == 1 ? "1 business day" : "#{num(n)}#{SHORT[k]}" }.join(" ")
+      end
+      @parts.map { |k, n| "#{num(n)} #{LONG[k]}#{"s" unless n == 1}" }.join(" ")
+    end
+
+    # seconds is nil when a part has no fixed length; a fraction of a second is a Float
+    def to_h
+      fixed = (@parts.keys - FIXED.keys).empty?
+      { kind: "duration", parts: @parts.transform_values { json_num(_1) }, iso8601: iso8601,
+        seconds: fixed ? json_num(seconds) : nil }
+    end
+
+    def to_json(*args) = to_h.to_json(*args)
+
+    def as_json(*) = JSON.parse(to_json)
+
+    def ==(other) = Duration === other && other.parts == @parts
+
+    def inspect = "#<Acute::Duration #{self}>"
+
+    private
+
+    def json_num(n) = Rational === n ? n.to_f : n
+
+    def whole(n) = Rational === n && n.denominator == 1 ? n.to_i : n
+
+    # "123.45s": a fraction of a second as a decimal
+    def num(n) = Rational === n ? n.to_f.to_s : n.to_s
+  end
+end

data/lib/acute/errors.rb

@@ -0,0 +1,47 @@
+module Acute
+  # What every error acute raises on purpose includes, so one rescue catches them all
+  module Error; end
+
+  # T30: inspect escapes control characters but leaves Unicode format characters as they are, and a bidi
+  # override in a quoted word can reorder how the rest of a terminal or log line reads. A message shows them
+  # escaped, as inspect shows a newline; so are the control characters of a message that quotes raw (OptionParser's).
+  INVISIBLE = /[\p{Cc}\p{Cf}\u2028\u2029]/
+  def self.visible(message)
+    return message unless message.match?(INVISIBLE)
+    message.gsub(INVISIBLE) { _1.ord < 128 ? _1.inspect[1..-2] : format("\\u%04X", _1.ord) }
+  end
+
+  # A value a message quotes, cut so a huge one costs nothing to report or log
+  def self.quote(string, limit = 64) = string.length > limit ? "#{string[0, limit].inspect[0..-2]}…\"" : string.inspect
+
+  class ParseError < StandardError
+    include Error
+
+    attr_reader :code, :position, :unknown, :hint
+
+    def initialize(message, code:, position:, unknown: [], hint: nil)
+      super(Acute.visible(message))
+      @code = code
+      @position = position
+      @unknown = unknown
+      @hint = hint
+    end
+  end
+
+  # A bad value for an option; an ArgumentError, so code rescuing that is unchanged
+  class OptionError < ArgumentError
+    include Error
+
+    attr_reader :option, :value
+
+    def initialize(message, option:, value:)
+      super(Acute.visible(message))
+      @option = option
+      @value = value
+    end
+  end
+
+  # What a stage returns instead of raising: start and stop are byte offsets into the text
+  # @api private
+  Failure = Struct.new(:code, :start, :stop)
+end

data/lib/acute/explain.rb

@@ -0,0 +1,165 @@
+require_relative "errors"
+require_relative "lexer"
+require_relative "calendar"
+require_relative "tables/words"
+
+module Acute
+  # Turns a Failure into a ParseError with a message, character positions and a hint. Only the error
+  # path comes here, so it can afford to rescan the text.
+  # @api private
+  module Explain
+    def self.error(failure, text)
+      return ParseError.new("the text is not valid UTF-8", code: :invalid_encoding, position: 0...0) if failure.code == :invalid_encoding
+      first = chars(text, failure.start)...chars(text, failure.stop)
+      slice = text.byteslice(failure.start, failure.stop - failure.start)
+      case failure.code
+      when :unknown_word
+        words = Lexer.unknown_ranges(text).map { |r| text.byteslice(r.begin, r.size) }
+        hint = suggest(words.first)
+        noun = words.size == 1 ? "word" : "words"
+        ParseError.new("unknown #{noun} #{words.map(&:inspect).join(", ")}", code: :unknown_word, position: first,
+                       unknown: words, hint: hint && "did you mean #{hint.inspect}?")
+      when :invalid_date
+        ParseError.new(invalid(text, failure) || "#{slice.inspect} is not a valid time", code: :invalid_date, position: first)
+      when :incomplete
+        ParseError.new("the phrase is incomplete", code: :incomplete, position: first)
+      when :conflict
+        ParseError.new("#{slice.inspect} doesn't fit with the rest of the phrase", code: :conflict, position: first)
+      when :no_occurrence
+        ParseError.new("the rule ends before it starts", code: :no_occurrence, position: first)
+      when :vague_rule
+        ParseError.new("#{slice.inspect} says how often, not when", code: :vague_rule, position: first)
+      when :not_rule
+        ParseError.new("not a repeating time", code: :not_rule, position: first)
+      when :dst_skipped_time
+        ParseError.new("#{slice.inspect} names a wall time the clocks skip as they go forward", code: failure.code,
+                       position: first, hint: "dst: :earlier, :later or :compatible picks an instant for it")
+      when :dst_repeated_time
+        ParseError.new("#{slice.inspect} names a wall time that happens twice as the clocks go back",
+                       code: failure.code, position: first, hint: "dst: :earlier or :later picks one")
+      when :business_day_limit
+        ParseError.new("more than #{Resolve::Period::LIMIT} business days in one call is too many to count", code: :business_day_limit,
+                       position: first)
+      when :occurrence_limit
+        ParseError.new("more than #{Rule::MAX_OCCURRENCES} occurrences in one call is too many to list; each lists them lazily",
+                       code: :occurrence_limit, position: first)
+      when :step_limit
+        ParseError.new("no occurrence within #{Rule::STEPS} steps of the search", code: :step_limit, position: first)
+      else
+        ParseError.new("longer than #{MAX_LENGTH} bytes", code: :too_long, position: first)
+      end
+    end
+
+    def self.chars(text, byte) = text.byteslice(0, byte).length
+
+    # D48's account of what is out of range in an error's span, which names no input; nil when there is none
+    def self.reason(error, text)
+      return unless error.code == :invalid_date
+      span = error.position
+      invalid(text, Failure.new(:invalid_date, text[0, span.begin].bytesize, text[0, span.end].bytesize))
+    end
+
+    L = Lexer
+    MONTHS = %w[_ January February March April May June July August September October November December].freeze
+
+    # D48: what is out of range in an invalid date or time ("June has 30 days"), or nil when it can't say
+    def self.invalid(text, failure)
+      all = Lexer.lex(text, []).each_slice(L::STRIDE).to_a
+      t = all.select { |_, _, _, st, e| st >= failure.start && e <= failure.stop }
+      mer = all[all.index(t.last) + 1]&.first == L::MER if t.any?
+      month = day = year = nil
+      nums = []
+      t.each_with_index do |(k, v, f), i|
+        case k
+        when L::CLOCK
+          hour = v / 10_000
+          return "there is no hour #{hour} on a 12-hour clock" if mer && hour > 12 && hour < 24
+          return clock(hour, v / 100 % 100, v % 100)
+        when L::MONTH
+          month = v
+          day ||= [i > 0 && t[i - 1], t[i + 1]].find { |x| x && x[0] == L::NUM && x[2] & L::DIGITS <= 2 }&.at(1)
+        when L::ORD then day = v
+        when L::HOLIDAY then (month, day = 2, 29) if v == :leap_day
+        when L::NUM
+          case f & L::DIGITS
+          when 4 then year = v
+          when 1, 2 then nums << v
+          else return nil
+          end
+        end
+      end
+      return "there is no hour #{nums[0]} on a 12-hour clock" if mer && t.size == 1 && nums[0].to_i > 12
+      month, day = numeric(nums, year && t[0][1] == year) unless month
+      return unless month && day && month.between?(1, 12) && day >= 1
+      return "#{year} is not a leap year" if month == 2 && day == 29 && year && !Calendar.leap?(year)
+      max = year ? Calendar.days_in_month(year, month) : month == 2 ? 29 : Calendar::MONTH_DAYS[month]
+      return if day <= max
+      return "February has 28 days, 29 in a leap year" if month == 2 && !year
+      "#{MONTHS[month]}#{" #{year}" if month == 2} has #{max} days"
+    end
+
+    def self.clock(hour, min, sec)
+      return "there is no hour #{hour}" if hour > 24 || (hour == 24 && min + sec > 0)
+      return "there is no minute #{min}" if min > 59
+      "there is no second #{sec}" if sec > 59
+    end
+
+    # A numeric date's month and day: year first, or the one order where only one number can be the month
+    def self.numeric(nums, year_first)
+      return unless nums.size == 2
+      return nums if year_first
+      a, b = nums
+      if a <= 12 && b > 12 then [a, b]
+      elsif b <= 12 && a > 12 then [b, a]
+      end
+    end
+
+    def self.letters(bytes) = bytes.inject(0) { |m, c| m | 1 << (c & 63) }
+
+    HINTS = Ractor.make_shareable(Tables::HINT_WORDS.map { |w| [w, w.bytes, letters(w.bytes)] })
+
+    # The closest known word within two edits, if it is close enough to be a likely typo
+    def self.suggest(word)
+      return unless word&.ascii_only?
+      a = word.downcase.bytes
+      mask = letters(a)
+      best = nil
+      best_distance = 3
+      HINTS.each do |candidate, b, m|
+        next if (b.size - a.size).abs >= best_distance
+        # each letter one word has and the other lacks costs an edit, so this bounds the distance from below
+        next if (mask & ~m).to_s(2).count("1") >= best_distance || (m & ~mask).to_s(2).count("1") >= best_distance
+        d = distance(a, b, best_distance)
+        if d < best_distance && d < b.size / 2
+          best = candidate
+          best_distance = d
+        end
+      end
+      best
+    end
+
+    # Optimal string alignment distance: Levenshtein plus adjacent transpositions, three rows at a time.
+    # Gives up with limit once a whole row is at least limit, since the distance can only grow from there.
+    def self.distance(a, b, limit = Float::INFINITY)
+      before = nil
+      prev = (0..b.size).to_a
+      a.each_with_index do |ca, i|
+        row = [i + 1]
+        low = i + 1
+        b.each_with_index do |cb, j|
+          d = prev[j + 1] + 1
+          d = row[j] + 1 if row[j] + 1 < d
+          s = prev[j] + (ca == cb ? 0 : 1)
+          d = s if s < d
+          d = before[j - 1] + 1 if i > 0 && j > 0 && ca == b[j - 1] && a[i - 1] == cb && before[j - 1] + 1 < d
+          row << d
+          low = d if d < low
+        end
+        return limit if low >= limit
+        before = prev
+        prev = row
+      end
+      prev[b.size]
+    end
+  end
+end