hron 1.0.0 → 2.0.0

data/lib/hron/parser.rb

@@ -1,289 +1,251 @@
 # frozen_string_literal: true
 
 require "date"
+require "tzinfo"
 require_relative "ast"
 require_relative "error"
 require_relative "lexer"
 
 module Hron
-  # Parser for hron expressions
   class Parser
+    # The `{what}` of each `expected {what}, got ...` error, one per phrase in the position table
+    # of spec/README.md, "Parse errors".
+    module Expected
+      EVERY_OR_ON = "'every' or 'on'"
+      REPEATER = "'day', 'weekday', 'weekend', a day name, 'week', 'month', 'year' or a number"
+      UNIT = "a unit ('min', 'hours', 'days', 'weeks', 'months' or 'years')"
+      AT = "'at'"
+      TIME = "a time (HH:MM)"
+      FROM = "'from'"
+      TO = "'to'"
+      DAY_TARGET = "'day', 'weekday', 'weekend' or a day name"
+      ON = "'on'"
+      DAY_NAME = "a day name"
+      THE = "'the'"
+      MONTH_TARGET = "a day such as 15th, 'last', an ordinal such as 'first', 'next', 'previous' or 'nearest'"
+      MONTH_LAST = "'day', 'weekday' or a day name"
+      NEAREST = "'nearest'"
+      WEEKDAY = "'weekday'"
+      DAY_OF_MONTH = "a day such as 15th"
+      YEAR_TARGET = "a month name or 'the'"
+      YEAR_THE = "a day such as 15th, 'last' or an ordinal such as 'first'"
+      YEAR_LAST = "'weekday' or a day name"
+      OF = "'of'"
+      MONTH_NAME = "a month name"
+      DAY_NUMBER = "a day number"
+      DATE = "a date (YYYY-MM-DD, or a month and day)"
+      ISO_DATE = "a date (YYYY-MM-DD)"
+      TIMEZONE = "a timezone"
+    end
+
+    CLAUSE_ORDER = [
+      [TokenKind::EXCEPT, "except"],
+      [TokenKind::UNTIL, "until"],
+      [TokenKind::STARTING, "starting"],
+      [TokenKind::DURING, "during"],
+      [TokenKind::IN, "in"]
+    ].freeze
+
+    private_constant :Expected, :CLAUSE_ORDER
+
+    def self.parse(input)
+      tokens = Lexer.new(input).tokenize
+      raise HronError.parse("empty expression", Span.new(0, 0), input) if tokens.empty?
+
+      new(tokens, input).parse
+    end
+
+    def self.iana_timezone(name)
+      return unless name.ascii_only?
+
+      lower = name.downcase(:ascii)
+      # System zoneinfo directories that are not IANA names of their own.
+      return if lower.start_with?("systemv/", "posix/", "right/")
+      return "UTC" if lower == "utc"
+
+      iana_names[lower] if name.include?("/")
+    end
+
+    def self.iana_names
+      @iana_names ||= TZInfo::Timezone.all_identifiers.to_h { |id| [id.downcase(:ascii), id] }
+    end
+    private_class_method :iana_names
+
     def initialize(tokens, input)
       @tokens = tokens
       @pos = 0
       @input = input
+      @chars = Utf8.convert(input).chars
+      @until_span = nil
     end
 
+    def parse
+      schedule = parse_clauses(parse_expression)
+      raise leftover(schedule) if peek
+
+      # spec/README.md, "Parse errors": every other error wins over a named until without starting.
+      check_named_until(schedule)
+      schedule
+    end
+
+    private
+
     def peek
-      (@pos < @tokens.length) ? @tokens[@pos] : nil
+      @tokens[@pos]
     end
 
     def peek_kind
-      tok = peek
-      tok&.kind
+      peek&.kind
     end
 
     def advance
-      tok = peek
-      @pos += 1 if tok
-      tok
+      token = @tokens[@pos]
+      @pos += 1
+      token
     end
 
-    def current_span
-      tok = peek
-      return tok.span if tok
+    def previous
+      @tokens[@pos - 1]
+    end
 
-      if @tokens.any?
-        last = @tokens.last
-        Span.new(last.span.end_pos, last.span.end_pos)
-      else
-        Span.new(0, 0)
-      end
+    def eat(kind)
+      found = peek_kind == kind
+      @pos += 1 if found
+      found
     end
 
-    def error(message, span)
-      HronError.parse(message, span, @input)
+    def expect(kind, what)
+      raise expected(what) unless eat(kind)
     end
 
-    def error_at_end(message)
-      if @tokens.any?
-        end_pos = @tokens.last.span.end_pos
-        span = Span.new(end_pos, end_pos)
-      else
-        span = Span.new(0, 0)
-      end
-      HronError.parse(message, span, @input)
+    def text(token)
+      @chars[token.span.start...token.span.end_pos].join
     end
 
-    def consume(expected, check_class)
-      span = current_span
-      tok = peek
-      if tok && tok.kind.is_a?(check_class)
-        @pos += 1
-        return tok
-      end
-      raise error("expected #{expected}, got #{tok.kind.class.name.split("::").last}", span) if tok
+    def error(message, start, stop, suggestion: nil)
+      HronError.parse(message, Span.new(start, stop), @input, suggestion: suggestion)
+    end
 
-      raise error_at_end("expected #{expected}")
+    def token_error(message, token)
+      error(message, token.span.start, token.span.end_pos)
     end
 
-    def consume_keyword(expected, kind_symbol)
-      span = current_span
-      tok = peek
-      if tok && tok.kind == kind_symbol
-        @pos += 1
-        return tok
-      end
-      raise error("expected #{expected}", span) if tok
+    def expected(what)
+      token = peek
+      return token_error("expected #{what}, got '#{text(token)}'", token) if token
 
-      raise error_at_end("expected #{expected}")
+      stop = @tokens.last&.span&.end_pos || 0
+      error("expected #{what}, got end of input", stop, stop)
     end
 
-    # --- Grammar productions ---
-
     def parse_expression
-      span = current_span
-      kind = peek_kind
-
-      case kind
-      when TokenKind::EVERY
-        advance
-        expr = parse_every
-      when TokenKind::ON
-        advance
-        expr = parse_on
+      if eat(TokenKind::EVERY)
+        parse_every
+      elsif eat(TokenKind::ON)
+        parse_on
       else
-        raise error("expected 'every' or 'on'", span)
+        raise expected(Expected::EVERY_OR_ON)
       end
-
-      parse_trailing_clauses(expr)
     end
 
-    def parse_trailing_clauses(expr)
-      schedule = ScheduleData.new(expr: expr)
+    def parse_clauses(expr)
+      fields = {expression: expr}
+      fields[:except] = parse_exception_list if eat(TokenKind::EXCEPT)
 
-      # except
-      if peek_kind == TokenKind::EXCEPT
-        advance
-        schedule = ScheduleData.new(
-          expr: schedule.expr,
-          timezone: schedule.timezone,
-          except: parse_exception_list,
-          until: schedule.until,
-          anchor: schedule.anchor,
-          during: schedule.during
-        )
-      end
-
-      # until
       if peek_kind == TokenKind::UNTIL
-        advance
-        schedule = ScheduleData.new(
-          expr: schedule.expr,
-          timezone: schedule.timezone,
-          except: schedule.except,
-          until: parse_until_spec,
-          anchor: schedule.anchor,
-          during: schedule.during
-        )
+        until_token = advance
+        date = parse_date
+        fields[:until] = date.is_a?(IsoDate) ? IsoUntil.new(date.date) : NamedUntil.new(date.month, date.day)
+        @until_span = [until_token.span.start, previous.span.end_pos]
       end
 
-      # starting
-      if peek_kind == TokenKind::STARTING
-        advance
-        k = peek_kind
-        raise error("expected ISO date (YYYY-MM-DD) after 'starting'", current_span) unless k.is_a?(TIsoDate)
-
-        validate_iso_date(k.date)
-        anchor = k.date
-        advance
-        schedule = ScheduleData.new(
-          expr: schedule.expr,
-          timezone: schedule.timezone,
-          except: schedule.except,
-          until: schedule.until,
-          anchor: anchor,
-          during: schedule.during
-        )
+      if eat(TokenKind::STARTING)
+        raise expected(Expected::ISO_DATE) unless peek_kind.is_a?(TIsoDate)
 
+        fields[:starting] = iso_date(advance)
       end
 
-      # during
-      if peek_kind == TokenKind::DURING
-        advance
-        schedule = ScheduleData.new(
-          expr: schedule.expr,
-          timezone: schedule.timezone,
-          except: schedule.except,
-          until: schedule.until,
-          anchor: schedule.anchor,
-          during: parse_month_list
-        )
-      end
+      fields[:during] = parse_month_list if eat(TokenKind::DURING)
 
-      # in <timezone>
-      if peek_kind == TokenKind::IN
-        advance
-        k = peek_kind
-        raise error("expected timezone after 'in'", current_span) unless k.is_a?(TTimezone)
+      if eat(TokenKind::IN)
+        raise expected(Expected::TIMEZONE) unless peek_kind.is_a?(TTimezone)
 
-        tz = k.tz
-        advance
-        schedule = ScheduleData.new(
-          expr: schedule.expr,
-          timezone: tz,
-          except: schedule.except,
-          until: schedule.until,
-          anchor: schedule.anchor,
-          during: schedule.during
-        )
+        fields[:timezone] = timezone(advance)
+      end
+
+      ScheduleData.new(**fields)
+    end
 
+    def leftover(schedule)
+      token = peek
+      # Every clause holds at least one item, so a clause was read exactly when its field is set.
+      read = [schedule.except.any?, !schedule.until.nil?, !schedule.starting.nil?, schedule.during.any?, !schedule.timezone.nil?]
+      clause = CLAUSE_ORDER.index { |kind, _| kind == token.kind }
+      last_read = read.rindex(true)
+      message = if clause && read[clause]
+        "duplicate '#{CLAUSE_ORDER[clause][1]}' clause"
+      elsif clause && last_read
+        "'#{CLAUSE_ORDER[clause][1]}' must come before '#{CLAUSE_ORDER[last_read][1]}'"
+      else
+        "unexpected '#{text(token)}' after the schedule"
       end
+      token_error(message, token)
+    end
 
-      schedule
+    def check_named_until(schedule)
+      named = schedule.until
+      return unless named.is_a?(NamedUntil) && schedule.starting.nil?
+
+      raise error(
+        "until #{named.month} #{named.day} has no year: add a starting date, or use an ISO date",
+        *@until_span,
+        suggestion: "until #{named.month} #{named.day} starting YYYY-MM-DD"
+      )
     end
 
     def parse_exception_list
       exceptions = [parse_exception]
-      while peek_kind == TokenKind::COMMA
-        advance
-        exceptions << parse_exception
-      end
+      exceptions << parse_exception while eat(TokenKind::COMMA)
       exceptions
     end
 
-    def validate_iso_date(date_str)
-      Date.iso8601(date_str)
-    rescue Date::Error
-      raise error("invalid date: #{date_str}", current_span)
-    end
-
-    def validate_named_date(month, day)
-      max = case month
-      when MonthName::JAN then 31
-      when MonthName::FEB then 29
-      when MonthName::MAR then 31
-      when MonthName::APR then 30
-      when MonthName::MAY then 31
-      when MonthName::JUN then 30
-      when MonthName::JUL then 31
-      when MonthName::AUG then 31
-      when MonthName::SEP then 30
-      when MonthName::OCT then 31
-      when MonthName::NOV then 30
-      when MonthName::DEC then 31
-      end
-      return if day.between?(1, max)
-
-      raise error("invalid day #{day} for #{month} (max #{max})", current_span)
+    def parse_exception
+      date = parse_date
+      date.is_a?(IsoDate) ? IsoException.new(date.date) : NamedException.new(date.month, date.day)
     end
 
-    def parse_exception
-      k = peek_kind
-      if k.is_a?(TIsoDate)
-        validate_iso_date(k.date)
-        advance
-        return IsoException.new(k.date)
-      end
-      if k.is_a?(TMonthName)
-        month = k.name
+    def parse_date
+      kind = peek_kind
+      if kind.is_a?(TIsoDate)
+        iso_date(advance)
+        IsoDate.new(kind.date)
+      elsif kind.is_a?(TMonthName)
         advance
-        day = parse_day_number("expected day number after month name in exception")
-        validate_named_date(month, day)
-        return NamedException.new(month, day)
+        NamedDate.new(kind.name, parse_day_of(kind.name))
+      else
+        raise expected(Expected::DATE)
       end
-      raise error("expected ISO date or month-day in exception", current_span)
     end
 
-    def parse_until_spec
-      k = peek_kind
-      if k.is_a?(TIsoDate)
-        validate_iso_date(k.date)
-        advance
-        return IsoUntil.new(k.date)
-      end
-      if k.is_a?(TMonthName)
-        month = k.name
-        advance
-        day = parse_day_number("expected day number after month name in until")
-        validate_named_date(month, day)
-        return NamedUntil.new(month, day)
-      end
-      raise error("expected ISO date or month-day after 'until'", current_span)
+    def iso_date(token)
+      written = text(token)
+      year, month, day = written.split("-").map(&:to_i)
+      return written if year >= 1 && Date.valid_date?(year, month, day, Date::GREGORIAN)
+
+      raise token_error("date must be a calendar date from 0001-01-01 to 9999-12-31, got #{written}", token)
     end
 
-    def parse_day_number(error_msg)
-      k = peek_kind
-      if k.is_a?(TNumber)
-        val = k.value
-        if val < 1 || val > 31
-          raise error("invalid day number #{val} (must be 1-31)", current_span)
-        end
-        advance
-        return val
-      end
-      if k.is_a?(TOrdinalNumber)
-        val = k.value
-        if val < 1 || val > 31
-          raise error("invalid day number #{val} (must be 1-31)", current_span)
-        end
-        advance
-        return val
-      end
-      raise error(error_msg, current_span)
+    def timezone(token)
+      name = text(token)
+      Parser.iana_timezone(name) or
+        raise token_error("timezone must be UTC or an Area/Location name such as America/New_York, got #{name}", token)
     end
 
-    # After "every": dispatch
     def parse_every
-      raise error_at_end("expected repeater") unless peek
-
-      k = peek_kind
-
-      case k
-      when TokenKind::YEAR
-        advance
-        parse_year_repeat(1)
+      kind = peek_kind
+      case kind
       when TokenKind::DAY
+        advance
         parse_day_repeat(1, DayFilterEvery.new)
       when TokenKind::WEEKDAY_KW
         advance
@@ -292,393 +254,298 @@ module Hron
         advance
         parse_day_repeat(1, DayFilterWeekend.new)
       when TDayName
-        days = parse_day_list
-        parse_day_repeat(1, DayFilterDays.new(days))
+        parse_day_repeat(1, DayFilterDays.new(parse_day_list))
+      when TokenKind::WEEKS
+        advance
+        parse_week_repeat(1)
       when TokenKind::MONTH
         advance
         parse_month_repeat(1)
-      when TokenKind::WEEKS
+      when TokenKind::YEAR
         advance
-        parse_week_repeat(1)
+        parse_year_repeat(1)
       when TNumber
-        parse_number_repeat
+        parse_number_repeat(kind.value)
       else
-        raise error(
-          "expected day, weekday, weekend, year, day name, month, or number after 'every'",
-          current_span
-        )
+        raise expected(Expected::REPEATER)
       end
     end
 
     def parse_day_repeat(interval, days)
-      consume_keyword("'day'", TokenKind::DAY) if days.is_a?(DayFilterEvery)
-      consume_keyword("'at'", TokenKind::AT)
-      times = parse_time_list
-      DayRepeat.new(interval, days, times)
+      expect(TokenKind::AT, Expected::AT)
+      DayRepeat.new(interval, days, parse_time_list)
     end
 
-    def parse_number_repeat
-      span = current_span
-      k = peek_kind
-      num = k.value
-      raise error("interval must be at least 1", span) if num.zero?
-
-      advance
+    def parse_number_repeat(interval)
+      number = advance
+      raise token_error("interval must be 1-2147483647, got #{text(number)}", number) if interval.zero?
 
-      nk = peek_kind
-      case nk
+      kind = peek_kind
+      case kind
       when TokenKind::WEEKS
         advance
-        parse_week_repeat(num)
+        parse_week_repeat(interval)
       when TIntervalUnit
-        parse_interval_repeat(num)
+        advance
+        parse_interval_repeat(interval, kind.unit)
       when TokenKind::DAY
-        parse_day_repeat(num, DayFilterEvery.new)
+        advance
+        parse_day_repeat(interval, DayFilterEvery.new)
       when TokenKind::MONTH
         advance
-        parse_month_repeat(num)
+        parse_month_repeat(interval)
       when TokenKind::YEAR
         advance
-        parse_year_repeat(num)
+        parse_year_repeat(interval)
       else
-        raise error(
-          "expected 'weeks', 'min', 'minutes', 'hour', 'hours', 'day(s)', 'month(s)', or 'year(s)' after number",
-          current_span
-        )
+        raise expected(Expected::UNIT)
       end
     end
 
-    def parse_interval_repeat(interval)
-      k = peek_kind
-      unit = k.unit
-      advance
-
-      consume_keyword("'from'", TokenKind::FROM)
-      from_time = parse_time
-      consume_keyword("'to'", TokenKind::TO)
-      to_time = parse_time
-
-      day_filter = nil
-      if peek_kind == TokenKind::ON
-        advance
-        day_filter = parse_day_target
+    def parse_interval_repeat(interval, unit)
+      expect(TokenKind::FROM, Expected::FROM)
+      from = parse_time
+      from_token = previous
+      expect(TokenKind::TO, Expected::TO)
+      to = parse_time
+      to_token = previous
+      if (from.hour * 60) + from.minute > (to.hour * 60) + to.minute
+        raise error(
+          "time window must not run backwards: #{text(from_token)} to #{text(to_token)} (a window cannot cross midnight)",
+          from_token.span.start, to_token.span.end_pos
+        )
       end
 
-      IntervalRepeat.new(interval, unit, from_time, to_time, day_filter)
+      day_filter = eat(TokenKind::ON) ? parse_day_target : nil
+      IntervalRepeat.new(interval, unit, from, to, day_filter)
     end
 
     def parse_week_repeat(interval)
-      consume_keyword("'on'", TokenKind::ON)
+      expect(TokenKind::ON, Expected::ON)
       days = parse_day_list
-      consume_keyword("'at'", TokenKind::AT)
-      times = parse_time_list
-      WeekRepeat.new(interval, days, times)
+      expect(TokenKind::AT, Expected::AT)
+      WeekRepeat.new(interval, days, parse_time_list)
     end
 
     def parse_month_repeat(interval)
-      consume_keyword("'on'", TokenKind::ON)
-      consume_keyword("'the'", TokenKind::THE)
+      expect(TokenKind::ON, Expected::ON)
+      expect(TokenKind::THE, Expected::THE)
 
-      k = peek_kind
-
-      if k == TokenKind::LAST
+      kind = peek_kind
+      target = if kind == TokenKind::LAST
         advance
-        nk = peek_kind
-        if nk == TokenKind::DAY
-          advance
-          target = LastDayTarget.new
-        elsif nk == TokenKind::WEEKDAY_KW
-          advance
-          target = LastWeekdayTarget.new
-        elsif nk.is_a?(TDayName)
-          weekday = nk.name
-          advance
-          target = OrdinalWeekdayTarget.new(OrdinalPosition::LAST, weekday)
-        else
-          raise error("expected 'day', 'weekday', or day name after 'last'", current_span)
-        end
-      elsif k.is_a?(TOrdinal)
-        ordinal = parse_ordinal_position
-        nk = peek_kind
-        raise error("expected day name after ordinal", current_span) unless nk.is_a?(TDayName)
-
-        weekday = nk.name
+        parse_month_last_target
+      elsif kind.is_a?(TOrdinal)
         advance
-        target = OrdinalWeekdayTarget.new(ordinal, weekday)
-      elsif k.is_a?(TOrdinalNumber)
-        specs = parse_ordinal_day_list
-        target = DaysTarget.new(specs)
-      elsif k == TokenKind::NEXT || k == TokenKind::PREVIOUS || k == TokenKind::NEAREST
-        target = parse_nearest_weekday_target
+        OrdinalWeekdayTarget.new(kind.position, parse_day_name)
+      elsif kind.is_a?(TOrdinalNumber)
+        DaysTarget.new(parse_ordinal_day_list)
+      elsif [TokenKind::NEXT, TokenKind::PREVIOUS, TokenKind::NEAREST].include?(kind)
+        parse_nearest_weekday_target
       else
-        raise error("expected ordinal day (1st, 15th), 'last', ordinal (first..fifth), or '[next|previous] nearest' after 'the'", current_span)
+        raise expected(Expected::MONTH_TARGET)
       end
 
-      consume_keyword("'at'", TokenKind::AT)
-      times = parse_time_list
-      MonthRepeat.new(interval, target, times)
+      expect(TokenKind::AT, Expected::AT)
+      MonthRepeat.new(interval, target, parse_time_list)
     end
 
-    def parse_year_repeat(interval)
-      consume_keyword("'on'", TokenKind::ON)
-
-      k = peek_kind
-
-      if k == TokenKind::THE
-        advance
-        target = parse_year_target_after_the
-      elsif k.is_a?(TMonthName)
-        month = k.name
-        advance
-        day = parse_day_number("expected day number after month name")
-        validate_named_date(month, day)
-        target = YearDateTarget.new(month, day)
+    def parse_month_last_target
+      kind = peek_kind
+      target = if kind == TokenKind::DAY
+        LastDayTarget.new
+      elsif kind == TokenKind::WEEKDAY_KW
+        LastWeekdayTarget.new
+      elsif kind.is_a?(TDayName)
+        OrdinalWeekdayTarget.new(OrdinalPosition::LAST, kind.name)
       else
-        raise error("expected month name or 'the' after 'every year on'", current_span)
+        raise expected(Expected::MONTH_LAST)
       end
+      advance
+      target
+    end
 
-      consume_keyword("'at'", TokenKind::AT)
-      times = parse_time_list
-      YearRepeat.new(interval, target, times)
+    def parse_nearest_weekday_target
+      direction = if eat(TokenKind::NEXT)
+        NearestDirection::NEXT
+      elsif eat(TokenKind::PREVIOUS)
+        NearestDirection::PREVIOUS
+      end
+      expect(TokenKind::NEAREST, Expected::NEAREST)
+      expect(TokenKind::WEEKDAY_KW, Expected::WEEKDAY)
+      expect(TokenKind::TO, Expected::TO)
+      day, = parse_ordinal_day
+      NearestWeekdayTarget.new(day, direction)
     end
 
-    def parse_year_target_after_the
-      k = peek_kind
+    def parse_ordinal_day_list
+      specs = [parse_ordinal_day_spec]
+      specs << parse_ordinal_day_spec while eat(TokenKind::COMMA)
+      specs
+    end
 
-      if k == TokenKind::LAST
-        advance
-        nk = peek_kind
-        if nk == TokenKind::WEEKDAY_KW
-          advance
-          consume_keyword("'of'", TokenKind::OF)
-          month = parse_month_name_token
-          return YearLastWeekdayTarget.new(month)
-        end
-        if nk.is_a?(TDayName)
-          weekday = nk.name
-          advance
-          consume_keyword("'of'", TokenKind::OF)
-          month = parse_month_name_token
-          return YearOrdinalWeekdayTarget.new(OrdinalPosition::LAST, weekday, month)
-        end
-        raise error("expected 'weekday' or day name after 'last' in yearly expression", current_span)
-      end
+    def parse_ordinal_day_spec
+      start, start_token = parse_ordinal_day
+      return SingleDay.new(start) unless eat(TokenKind::TO)
 
-      if k.is_a?(TOrdinal)
-        ordinal = parse_ordinal_position
-        nk = peek_kind
-        if nk.is_a?(TDayName)
-          weekday = nk.name
-          advance
-          consume_keyword("'of'", TokenKind::OF)
-          month = parse_month_name_token
-          return YearOrdinalWeekdayTarget.new(ordinal, weekday, month)
-        end
-        raise error("expected day name after ordinal in yearly expression", current_span)
+      stop, stop_token = parse_ordinal_day
+      if start > stop
+        raise error(
+          "day range must not run backwards: #{text(start_token)} to #{text(stop_token)}",
+          start_token.span.start, stop_token.span.end_pos
+        )
       end
+      DayRange.new(start, stop)
+    end
 
-      if k.is_a?(TOrdinalNumber)
-        day = k.value
-        advance
-        consume_keyword("'of'", TokenKind::OF)
-        month = parse_month_name_token
-        validate_named_date(month, day)
-        return YearDayOfMonthTarget.new(day, month)
-      end
+    def parse_ordinal_day
+      kind = peek_kind
+      raise expected(Expected::DAY_OF_MONTH) unless kind.is_a?(TOrdinalNumber)
 
-      raise error("expected ordinal, day number, or 'last' after 'the' in yearly expression", current_span)
+      token = advance
+      [day_of_month(kind.value, token), token]
     end
 
-    def parse_month_name_token
-      k = peek_kind
-      if k.is_a?(TMonthName)
-        advance
-        return k.name
-      end
-      raise error("expected month name", current_span)
+    def parse_day_of(month)
+      kind = peek_kind
+      raise expected(Expected::DAY_NUMBER) unless kind.is_a?(TNumber) || kind.is_a?(TOrdinalNumber)
+
+      token = advance
+      day = day_of_month(kind.value, token)
+      check_day_in_month(day, token, month)
+      day
     end
 
-    def parse_ordinal_position
-      span = current_span
-      k = peek_kind
-      if k.is_a?(TOrdinal)
-        advance
-        return k.position
-      end
-      if k == TokenKind::LAST
-        advance
-        return OrdinalPosition::LAST
-      end
-      raise error("expected ordinal (first, second, third, fourth, fifth, last)", span)
+    def day_of_month(n, token)
+      return n if n.between?(1, 31)
+
+      raise token_error("day must be 1-31, got #{text(token)}", token)
     end
 
-    def parse_on
-      date = parse_date_target
-      consume_keyword("'at'", TokenKind::AT)
-      times = parse_time_list
-      SingleDateExpr.new(date, times)
+    def check_day_in_month(day, token, month)
+      max = MonthName.max_day(month)
+      raise token_error("day must be 1-#{max} for #{month}, got #{text(token)}", token) if day > max
     end
 
-    def parse_date_target
-      k = peek_kind
-      if k.is_a?(TIsoDate)
-        validate_iso_date(k.date)
+    def parse_year_repeat(interval)
+      expect(TokenKind::ON, Expected::ON)
+
+      kind = peek_kind
+      target = if kind == TokenKind::THE
         advance
-        return IsoDate.new(k.date)
-      end
-      if k.is_a?(TMonthName)
-        month = k.name
+        parse_year_target_after_the
+      elsif kind.is_a?(TMonthName)
         advance
-        day = parse_day_number("expected day number after month name")
-        validate_named_date(month, day)
-        return NamedDate.new(month, day)
+        YearDateTarget.new(kind.name, parse_day_of(kind.name))
+      else
+        raise expected(Expected::YEAR_TARGET)
       end
-      raise error("expected date (ISO date or month name)", current_span)
+
+      expect(TokenKind::AT, Expected::AT)
+      YearRepeat.new(interval, target, parse_time_list)
     end
 
-    def parse_day_target
-      k = peek_kind
-      case k
-      when TokenKind::DAY
-        advance
-        DayFilterEvery.new
-      when TokenKind::WEEKDAY_KW
-        advance
-        DayFilterWeekday.new
-      when TokenKind::WEEKEND_KW
-        advance
-        DayFilterWeekend.new
-      when TDayName
-        days = parse_day_list
-        DayFilterDays.new(days)
+    def parse_year_target_after_the
+      kind = peek_kind
+      if kind == TokenKind::LAST
+        advance
+        parse_year_last_target
+      elsif kind.is_a?(TOrdinal)
+        advance
+        weekday = parse_day_name
+        YearOrdinalWeekdayTarget.new(kind.position, weekday, parse_of_month)
+      elsif kind.is_a?(TOrdinalNumber)
+        day, day_token = parse_ordinal_day
+        month = parse_of_month
+        check_day_in_month(day, day_token, month)
+        YearDayOfMonthTarget.new(day, month)
       else
-        raise error("expected 'day', 'weekday', 'weekend', or day name", current_span)
+        raise expected(Expected::YEAR_THE)
       end
     end
 
-    def parse_day_list
-      k = peek_kind
-      raise error("expected day name", current_span) unless k.is_a?(TDayName)
-
-      days = [k.name]
-      advance
-
-      while peek_kind == TokenKind::COMMA
+    def parse_year_last_target
+      kind = peek_kind
+      if kind == TokenKind::WEEKDAY_KW
         advance
-        nk = peek_kind
-        raise error("expected day name after ','", current_span) unless nk.is_a?(TDayName)
-
-        days << nk.name
+        YearLastWeekdayTarget.new(parse_of_month)
+      elsif kind.is_a?(TDayName)
         advance
+        YearOrdinalWeekdayTarget.new(OrdinalPosition::LAST, kind.name, parse_of_month)
+      else
+        raise expected(Expected::YEAR_LAST)
       end
-      days
     end
 
-    def parse_ordinal_day_list
-      specs = [parse_ordinal_day_spec]
-      while peek_kind == TokenKind::COMMA
-        advance
-        specs << parse_ordinal_day_spec
-      end
-      specs
+    def parse_of_month
+      expect(TokenKind::OF, Expected::OF)
+      parse_month_name
     end
 
-    def parse_ordinal_day_spec
-      k = peek_kind
-      raise error("expected ordinal day number", current_span) unless k.is_a?(TOrdinalNumber)
+    def parse_month_name
+      kind = peek_kind
+      raise expected(Expected::MONTH_NAME) unless kind.is_a?(TMonthName)
 
-      start = k.value
-      span = current_span
-      raise error("invalid day number #{start} (must be 1-31)", span) if start < 1 || start > 31
       advance
+      kind.name
+    end
 
-      if peek_kind == TokenKind::TO
-        advance
-        nk = peek_kind
-        raise error("expected ordinal day number after 'to'", current_span) unless nk.is_a?(TOrdinalNumber)
-
-        end_day = nk.value
-        end_span = current_span
-        raise error("invalid day number #{end_day} (must be 1-31)", end_span) if end_day < 1 || end_day > 31
-        advance
-        raise error("invalid day range: #{start} to #{end_day} (start must be <= end)", current_span) if start > end_day
-        return DayRange.new(start, end_day)
-      end
-
-      SingleDay.new(start)
+    def parse_month_list
+      months = [parse_month_name]
+      months << parse_month_name while eat(TokenKind::COMMA)
+      months
     end
 
-    def parse_nearest_weekday_target
-      k = peek_kind
+    def parse_on
+      date = parse_date
+      expect(TokenKind::AT, Expected::AT)
+      SingleDateExpr.new(date, parse_time_list)
+    end
 
-      # Optional direction: "next" or "previous"
-      direction = nil
-      if k == TokenKind::NEXT
+    def parse_day_target
+      case peek_kind
+      when TokenKind::DAY
         advance
-        direction = NearestDirection::NEXT
-      elsif k == TokenKind::PREVIOUS
+        DayFilterEvery.new
+      when TokenKind::WEEKDAY_KW
         advance
-        direction = NearestDirection::PREVIOUS
-      end
-
-      consume_keyword("'nearest'", TokenKind::NEAREST)
-      consume_keyword("'weekday'", TokenKind::WEEKDAY_KW)
-      consume_keyword("'to'", TokenKind::TO)
-
-      # Parse the day number (ordinal like 15th)
-      k = peek_kind
-      if k.is_a?(TOrdinalNumber)
-        day = k.value
-        if day < 1 || day > 31
-          raise error("invalid day number #{day} (must be 1-31)", current_span)
-        end
+        DayFilterWeekday.new
+      when TokenKind::WEEKEND_KW
         advance
+        DayFilterWeekend.new
+      when TDayName
+        DayFilterDays.new(parse_day_list)
       else
-        raise error("expected ordinal day number after 'to'", current_span)
+        raise expected(Expected::DAY_TARGET)
       end
+    end
 
-      NearestWeekdayTarget.new(day, direction)
+    def parse_day_name
+      kind = peek_kind
+      raise expected(Expected::DAY_NAME) unless kind.is_a?(TDayName)
+
+      advance
+      kind.name
     end
 
-    def parse_month_list
-      months = [parse_month_name_token]
-      while peek_kind == TokenKind::COMMA
-        advance
-        months << parse_month_name_token
-      end
-      months
+    def parse_day_list
+      days = [parse_day_name]
+      days << parse_day_name while eat(TokenKind::COMMA)
+      days
     end
 
     def parse_time_list
       times = [parse_time]
-      while peek_kind == TokenKind::COMMA
-        advance
-        times << parse_time
-      end
+      times << parse_time while eat(TokenKind::COMMA)
       times
     end
 
     def parse_time
-      span = current_span
-      k = peek_kind
-      if k.is_a?(TTime)
-        advance
-        return TimeOfDay.new(k.hour, k.minute)
-      end
-      raise error("expected time (HH:MM)", span)
-    end
-  end
-
-  def self.parse(input)
-    tokens = tokenize(input)
-
-    raise HronError.parse("empty expression", Span.new(0, 0), input) if tokens.empty?
-
-    parser = Parser.new(tokens, input)
-    schedule = parser.parse_expression
-
-    raise HronError.parse("unexpected tokens after expression", parser.current_span, input) if parser.peek
+      kind = peek_kind
+      raise expected(Expected::TIME) unless kind.is_a?(TTime)
 
-    schedule
+      advance
+      TimeOfDay.new(kind.hour, kind.minute)
+    end
   end
 end