hron 1.0.0 → 2.1.0

data/lib/hron/display.rb

@@ -3,10 +3,9 @@
 require_relative "ast"
 
 module Hron
-  # Display module for converting schedules to canonical string representation
   module Display
     def self.display(schedule)
-      out = display_expr(schedule.expr)
+      out = display_expr(schedule.expression)
 
       unless schedule.except.empty?
         parts = schedule.except.map do |exc|
@@ -33,7 +32,7 @@ module Hron
         end
       end
 
-      out += " starting #{schedule.anchor}" if schedule.anchor
+      out += " starting #{schedule.starting}" if schedule.starting
 
       out += " during #{schedule.during.join(", ")}" unless schedule.during.empty?
 
@@ -146,7 +145,7 @@ module Hron
     end
 
     def self.format_time_list(times)
-      times.map(&:to_s).join(", ")
+      times.join(", ")
     end
 
     def self.format_ordinal_day_specs(specs)
@@ -161,7 +160,10 @@ module Hron
       parts.join(", ")
     end
 
+    # Ruby's % floors, so -9 % 10 is 1; spec/README.md writes a day below 1 with th.
     def self.ordinal_suffix(n)
+      return "th" if n < 1
+
       mod100 = n % 100
       return "th" if mod100.between?(11, 13)
 

data/lib/hron/error.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 module Hron
-  # Span in source input for error reporting
+  # The part of the input an error points at: [start, end_pos) counted in code points, which are
+  # the indices of a valid UTF-8 String. Each byte of invalid UTF-8 counts as one code point.
   Span = Data.define(:start, :end_pos) do # end_pos to avoid Ruby keyword
     def length
       end_pos - start
     end
   end
 
-  # Error kinds
   module ErrorKind
     LEX = :lex
     PARSE = :parse
@@ -16,7 +16,25 @@ module Hron
     CRON = :cron
   end
 
-  # Main error class for hron
+  module Utf8
+    REPLACEMENT = "�"
+
+    # The spec counts each byte of invalid UTF-8 as one U+FFFD; `scrub` alone would replace a
+    # truncated multi-byte sequence with a single one. A binary String is read as UTF-8 bytes.
+    def self.convert(input)
+      return input if input.encoding == Encoding::UTF_8 && input.valid_encoding?
+
+      if input.encoding == Encoding::UTF_8 || input.encoding == Encoding::BINARY
+        return input.b.force_encoding(Encoding::UTF_8).scrub { |bytes| REPLACEMENT * bytes.bytesize }
+      end
+
+      input.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT)
+    rescue EncodingError
+      input.b.force_encoding(Encoding::UTF_8).scrub { |bytes| REPLACEMENT * bytes.bytesize }
+    end
+  end
+  private_constant :Utf8
+
   class HronError < StandardError
     attr_reader :kind, :span, :input, :suggestion
 
@@ -28,37 +46,56 @@ module Hron
       @suggestion = suggestion
     end
 
+    # Each factory raises TypeError for a message or input that is not a String, a span that is
+    # not a Hron::Span, and a suggestion that is neither a String nor nil.
     def self.lex(message, span, input)
+      require_strings(message: message, input: input)
+      require_span(span)
       new(ErrorKind::LEX, message, span: span, input: input)
     end
 
     def self.parse(message, span, input, suggestion: nil)
+      require_strings(message: message, input: input)
+      require_span(span)
+      unless suggestion.nil? || suggestion.is_a?(String)
+        raise TypeError, "suggestion must be a String or nil, not #{suggestion.class}"
+      end
+
       new(ErrorKind::PARSE, message, span: span, input: input, suggestion: suggestion)
     end
 
     def self.eval(message)
+      require_strings(message: message)
       new(ErrorKind::EVAL, message)
     end
 
     def self.cron(message)
+      require_strings(message: message)
       new(ErrorKind::CRON, message)
     end
 
-    def display_rich
-      if [ErrorKind::LEX, ErrorKind::PARSE].include?(kind) && span && input
-        buf = []
-        buf << "error: #{message}"
-        buf << "  #{input}"
-        padding = " " * (span.start + 2)
-        len = [span.length, 1].max
-        underline = "^" * len
-        line = "#{padding}#{underline}"
-        line += " try: \"#{suggestion}\"" if suggestion
-        buf << line
-        buf.join("\n")
-      else
-        "error: #{message}"
+    def self.require_strings(**values)
+      values.each do |name, value|
+        raise TypeError, "#{name} must be a String, not #{value.class}" unless value.is_a?(String)
       end
     end
+    private_class_method :require_strings
+
+    def self.require_span(span)
+      raise TypeError, "span must be a Hron::Span, not #{span.class}" unless span.is_a?(Span)
+    end
+    private_class_method :require_span
+
+    # The message, then for lex and parse errors the input and a line of carets under the span,
+    # and any suggestion as ` try: "..."`. Lines are joined by "\n", with no trailing newline.
+    def display_rich
+      return "error: #{message}" unless [ErrorKind::LEX, ErrorKind::PARSE].include?(kind) && span && input
+
+      # A tab, CR or LF would move the input off the line the carets are aligned to.
+      shown = Utf8.convert(input).tr("\t\r\n", "   ")
+      carets = "  #{" " * span.start}#{"^" * [span.length, 1].max}"
+      carets += " try: \"#{suggestion}\"" if suggestion
+      ["error: #{message}", "  #{shown}", carets].join("\n")
+    end
   end
 end

data/lib/hron/eval/calendar.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../ast"
+
+module Hron
+  class Evaluator
+    # Proleptic Gregorian throughout: Ruby's Date otherwise switches to the Julian calendar
+    # before 1582, and a search can reach back that far.
+    module Calendar
+      # The calendar a search walks: no date outside it holds an occurrence in the
+      # supported range (spec/README.md, "Supported range").
+      FIRST_DATE = Date.new(1, 1, 1, Date::GREGORIAN)
+      LAST_DATE = Date.new(9999, 12, 31, Date::GREGORIAN)
+
+      FRIDAY = 5
+      SATURDAY = 6
+      SUNDAY = 7
+
+      module_function
+
+      def date(year, month, day)
+        Date.new(year, month, day, Date::GREGORIAN) if Date.valid_date?(year, month, day, Date::GREGORIAN)
+      end
+
+      def parse_date(iso)
+        Date.iso8601(iso, Date::GREGORIAN)
+      end
+
+      def days_between(from, to)
+        to.jd - from.jd
+      end
+
+      def month_index(date)
+        (date.year * 12) + date.month - 1
+      end
+
+      def first_of_month(index)
+        year, month = index.divmod(12)
+        Date.new(year, month + 1, 1, Date::GREGORIAN)
+      end
+
+      def first_of_year(year)
+        Date.new(year, 1, 1, Date::GREGORIAN)
+      end
+
+      def monday_of_week(date)
+        date - (date.cwday - 1)
+      end
+
+      def matches_day_filter?(date, filter)
+        case filter
+        when nil, DayFilterEvery then true
+        when DayFilterWeekday then date.cwday <= FRIDAY
+        when DayFilterWeekend then date.cwday > FRIDAY
+        when DayFilterDays then filter.days.any? { |day| Weekday.number(day) == date.cwday }
+        end
+      end
+
+      def month_target_dates(year, month, target)
+        case target
+        when DaysTarget
+          Evaluator.days_of(target).uniq.sort.filter_map { |day| date(year, month, day) }
+        when LastDayTarget then [last_day_of_month(year, month)]
+        when LastWeekdayTarget then [last_weekday_of_month(year, month)]
+        when NearestWeekdayTarget then [nearest_weekday(year, month, target.day, target.direction)].compact
+        when OrdinalWeekdayTarget then [ordinal_weekday(year, month, target.ordinal, target.weekday)].compact
+        end
+      end
+
+      def year_target_date(year, target)
+        month = MonthName.number(target.month)
+        case target
+        when YearDateTarget, YearDayOfMonthTarget then date(year, month, target.day)
+        when YearOrdinalWeekdayTarget then ordinal_weekday(year, month, target.ordinal, target.weekday)
+        when YearLastWeekdayTarget then last_weekday_of_month(year, month)
+        end
+      end
+
+      def last_day_of_month(year, month)
+        Date.new(year, month, -1, Date::GREGORIAN)
+      end
+
+      def last_weekday_of_month(year, month)
+        last = last_day_of_month(year, month)
+        last - [last.cwday - FRIDAY, 0].max
+      end
+
+      def ordinal_weekday(year, month, ordinal, weekday)
+        target = Weekday.number(weekday)
+        if ordinal == OrdinalPosition::LAST
+          last = last_day_of_month(year, month)
+          return last - ((last.cwday - target) % 7)
+        end
+
+        first = Date.new(year, month, 1, Date::GREGORIAN)
+        nth = first + (((target - first.cwday) % 7) + (7 * (OrdinalPosition.to_n(ordinal) - 1)))
+        nth if nth.month == month
+      end
+
+      # Without a direction it stays in the month, as cron's W does; with one it can cross into
+      # the adjacent month (spec/README.md, "Nearest weekday and `during`").
+      def nearest_weekday(year, month, day, toward)
+        target = date(year, month, day)
+        return target if target.nil? || target.cwday <= FRIDAY
+
+        target + case [target.cwday, toward]
+        in [SATURDAY, NearestDirection::NEXT] then 2
+        in [SATURDAY, NearestDirection::PREVIOUS] then -1
+        in [SATURDAY, nil] if day == 1 then 2
+        in [SATURDAY, nil] then -1
+        in [SUNDAY, NearestDirection::NEXT] then 1
+        in [SUNDAY, NearestDirection::PREVIOUS] then -2
+        in [SUNDAY, nil] if target == last_day_of_month(year, month) then -2
+        in [SUNDAY, nil] then 1
+        end
+      end
+    end
+  end
+end

data/lib/hron/eval/wall_clock.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Hron
+  class Evaluator
+    # A wall time a fall-back repeats takes its first pass
+    # (spec/README.md, "DST fall-back (ambiguous times)").
+    module WallClock
+      DAY_SECONDS = 86_400
+      MINUTES_PER_HOUR = 60
+
+      module_function
+
+      # A wall time in a spring-forward gap shifts forward by the gap's length (spec/README.md,
+      # "DST spring-forward (gaps)"). A Time carries no zone, so this also returns the date it
+      # lands on.
+      def fixed_time_on(date, time, zone)
+        wall = wall_time(date, time.hour, time.minute)
+        instant = first_pass(wall, zone) { nil }
+        return instant, date if instant
+
+        # Read with the offset in force before the gap, a wall time in it lands past it, where
+        # the offset after the gap reads it.
+        transition = gap_transition(wall, zone)
+        instant = wall - transition.previous_offset.utc_total_offset
+        local = instant + transition.offset.utc_total_offset
+        [instant, Date.new(local.year, local.month, local.day, Date::GREGORIAN)]
+      end
+
+      # A slot in a spring-forward gap has no instant (spec/README.md, "Interval slots in a
+      # spring-forward gap"); its key is the instant the gap ends, so keys never decrease in
+      # wall-clock order and one binary search finds the slots on either side of an instant.
+      # A Struct, as a binary search makes several for every date.
+      Slot = Struct.new(:key, :instant)
+
+      def slot_on(date, minute, zone)
+        wall = wall_time(date, *minute.divmod(MINUTES_PER_HOUR))
+        instant = first_pass(wall, zone) { nil }
+        Slot.new(instant || gap_transition(wall, zone).at.to_time, instant)
+      end
+
+      def minute_of_day(time)
+        (time.hour * MINUTES_PER_HOUR) + time.minute
+      end
+
+      def first_pass(wall, zone)
+        offset = zone.periods_for_local(wall).first&.offset&.utc_total_offset
+        offset ? wall - offset : yield(wall)
+      end
+
+      # The wall time as a UTC Time, so the system time zone never interferes.
+      def wall_time(date, hour, minute)
+        Time.utc(date.year, date.month, date.day, hour, minute)
+      end
+
+      def gap_transition(wall, zone)
+        zone.transitions_up_to(wall + DAY_SECONDS, wall - DAY_SECONDS).rfind do |transition|
+          transition.at.to_time + transition.previous_offset.utc_total_offset <= wall
+        end
+      end
+    end
+  end
+end