hron 0.6.1 → 2.0.0

data/lib/hron/parts.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "ast"
+require_relative "error"
+require_relative "display"
+require_relative "parser"
+
+module Hron
+  # The checks of spec/README.md, "Schedules built in code", in its order. A part of the wrong
+  # Ruby type is a TypeError, a usage error rather than a HronError. Names are Symbols, so a
+  # name of another type is a TypeError too; the AST's unions (expression, day filter, ...)
+  # have no Ruby type of their own, so any value outside one is an unknown value of its kind.
+  # checked builds every part anew as its Hron class, so a part of a subclass gives a schedule
+  # equal to the parsed one.
+  module Parts
+    INTERVAL_MAX = 2_147_483_647
+
+    module_function
+
+    def checked(data)
+      raise TypeError, "data must be a Hron::ScheduleData, not #{data.class}" unless data.is_a?(ScheduleData)
+
+      expr = check_expression(data.expression)
+      except = list(data.except, "except").map { |exception| check_exception(exception) }
+      until_spec = data.until.nil? ? nil : check_until(data.until)
+      starting = data.starting.nil? ? nil : check_iso_date(string(data.starting, "starting"))
+      during = list(data.during, "during").map { |month| check_name(month, MonthName::ALL, "month") }
+      timezone = data.timezone.nil? ? nil : check_timezone(string(data.timezone, "timezone"))
+      if until_spec.is_a?(NamedUntil) && starting.nil?
+        raise error("until #{until_spec.month} #{until_spec.day} has no year: add a starting date, or use an ISO date")
+      end
+      ScheduleData.new(expression: expr, timezone:, except:, until: until_spec, starting:, during:)
+    end
+
+    def check_expression(expr)
+      case expr
+      when IntervalRepeat
+        interval = check_interval(expr.interval)
+        unit = check_name(expr.unit, IntervalUnit::ALL, "interval unit")
+        from = check_time(expr.from_time)
+        to = check_time(expr.to_time)
+        if minute_of_day(from) > minute_of_day(to)
+          raise error("time window must not run backwards: #{from} to #{to} (a window cannot cross midnight)")
+        end
+        day_filter = expr.day_filter.nil? ? nil : check_day_filter(expr.day_filter)
+        IntervalRepeat.new(interval, unit, from, to, day_filter)
+      when DayRepeat
+        interval = check_interval(expr.interval)
+        # `every 2 days` has no place for a day filter, so other days would not survive display.
+        raise error("days must be every day when the interval is above 1") if interval > 1 && !expr.days.is_a?(DayFilterEvery)
+
+        DayRepeat.new(interval, check_day_filter(expr.days), check_times(expr.times))
+      when WeekRepeat
+        interval = check_interval(expr.interval)
+        WeekRepeat.new(interval, check_weekdays(expr.days), check_times(expr.times))
+      when MonthRepeat
+        interval = check_interval(expr.interval)
+        MonthRepeat.new(interval, check_month_target(expr.target), check_times(expr.times))
+      when SingleDateExpr
+        SingleDateExpr.new(check_date(expr.date), check_times(expr.times))
+      when YearRepeat
+        interval = check_interval(expr.interval)
+        YearRepeat.new(interval, check_year_target(expr.target), check_times(expr.times))
+      else
+        raise unknown("expression", expr)
+      end
+    end
+
+    def check_interval(interval)
+      integer(interval, "interval")
+      raise error("interval must be 1-#{INTERVAL_MAX}, got #{interval}") unless interval.between?(1, INTERVAL_MAX)
+
+      interval
+    end
+
+    def check_times(times)
+      raise error("times must not be empty") if list(times, "times").empty?
+
+      times.map { |time| check_time(time) }
+    end
+
+    def check_time(time)
+      raise TypeError, "a time must be a Hron::TimeOfDay, not #{time.class}" unless time.is_a?(TimeOfDay)
+
+      integer(time.hour, "hour")
+      integer(time.minute, "minute")
+      raise error("time must be 00:00-23:59, got #{time}") unless time.hour.between?(0, 23) && time.minute.between?(0, 59)
+
+      TimeOfDay.new(time.hour, time.minute)
+    end
+
+    def minute_of_day(time)
+      (time.hour * 60) + time.minute
+    end
+
+    def check_day_filter(filter)
+      case filter
+      when DayFilterEvery then DayFilterEvery.new
+      when DayFilterWeekday then DayFilterWeekday.new
+      when DayFilterWeekend then DayFilterWeekend.new
+      when DayFilterDays then DayFilterDays.new(check_weekdays(filter.days))
+      else raise unknown("day filter", filter)
+      end
+    end
+
+    def check_weekdays(days)
+      raise error("days must not be empty") if list(days, "days").empty?
+
+      days.map { |day| check_name(day, Weekday::ALL, "weekday") }
+    end
+
+    def check_month_target(target)
+      case target
+      when DaysTarget
+        raise error("days must not be empty") if list(target.specs, "days").empty?
+
+        DaysTarget.new(target.specs.map { |spec| check_day_spec(spec) })
+      when LastDayTarget then LastDayTarget.new
+      when LastWeekdayTarget then LastWeekdayTarget.new
+      when NearestWeekdayTarget
+        direction = target.direction.nil? ? nil : check_name(target.direction, NearestDirection::ALL, "direction")
+        check_day(target.day, suffixed: true)
+        NearestWeekdayTarget.new(target.day, direction)
+      when OrdinalWeekdayTarget
+        ordinal = check_name(target.ordinal, OrdinalPosition::ALL, "ordinal")
+        OrdinalWeekdayTarget.new(ordinal, check_name(target.weekday, Weekday::ALL, "weekday"))
+      else
+        raise unknown("month target", target)
+      end
+    end
+
+    def check_day_spec(spec)
+      case spec
+      when SingleDay
+        check_day(spec.day, suffixed: true)
+        SingleDay.new(spec.day)
+      when DayRange
+        start = check_day(spec.start, suffixed: true)
+        last = check_day(spec.end_day, suffixed: true)
+        raise error("day range must not run backwards: #{start} to #{last}") if spec.start > spec.end_day
+
+        DayRange.new(spec.start, spec.end_day)
+      else
+        raise unknown("day spec", spec)
+      end
+    end
+
+    def check_year_target(target)
+      case target
+      when YearDateTarget then YearDateTarget.new(*check_named_date(target.month, target.day))
+      when YearOrdinalWeekdayTarget
+        ordinal = check_name(target.ordinal, OrdinalPosition::ALL, "ordinal")
+        weekday = check_name(target.weekday, Weekday::ALL, "weekday")
+        YearOrdinalWeekdayTarget.new(ordinal, weekday, check_name(target.month, MonthName::ALL, "month"))
+      when YearDayOfMonthTarget
+        month = check_name(target.month, MonthName::ALL, "month")
+        shown = check_day(target.day, suffixed: true)
+        check_day_in_month(target.day, month, shown)
+        YearDayOfMonthTarget.new(target.day, month)
+      when YearLastWeekdayTarget then YearLastWeekdayTarget.new(check_name(target.month, MonthName::ALL, "month"))
+      else raise unknown("year target", target)
+      end
+    end
+
+    def check_date(date)
+      case date
+      when NamedDate then NamedDate.new(*check_named_date(date.month, date.day))
+      when IsoDate then IsoDate.new(check_iso_date(string(date.date, "date")))
+      else raise unknown("date", date)
+      end
+    end
+
+    def check_exception(exception)
+      case exception
+      when NamedException then NamedException.new(*check_named_date(exception.month, exception.day))
+      when IsoException then IsoException.new(check_iso_date(string(exception.date, "date")))
+      else raise unknown("exception", exception)
+      end
+    end
+
+    def check_until(until_spec)
+      case until_spec
+      when NamedUntil then NamedUntil.new(*check_named_date(until_spec.month, until_spec.day))
+      when IsoUntil then IsoUntil.new(check_iso_date(string(until_spec.date, "date")))
+      else raise unknown("until", until_spec)
+      end
+    end
+
+    def check_named_date(month, day)
+      check_name(month, MonthName::ALL, "month")
+      shown = check_day(day, suffixed: false)
+      check_day_in_month(day, month, shown)
+      [month, day]
+    end
+
+    def check_day(day, suffixed:)
+      integer(day, "day")
+      shown = suffixed ? "#{day}#{Display.ordinal_suffix(day)}" : day.to_s
+      raise error("day must be 1-31, got #{shown}") unless day.between?(1, 31)
+
+      shown
+    end
+
+    def check_day_in_month(day, month, shown)
+      max = MonthName.max_day(month)
+      raise error("day must be 1-#{max} for #{month}, got #{shown}") if day > max
+    end
+
+    # Date.iso8601 alone would also read `20260206`, `+002026-02-06` and fullwidth digits. The
+    # encoding must be ASCII-compatible, or ten bytes that read as a date are other characters.
+    def check_iso_date(date)
+      if date.encoding.ascii_compatible? && date.b.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+        year, month, day = date.b.split("-").map(&:to_i)
+        return date if year >= 1 && Date.valid_date?(year, month, day, Date::GREGORIAN)
+      end
+
+      raise error("date must be a calendar date from 0001-01-01 to 9999-12-31, got #{Utf8.convert(date)}")
+    end
+
+    def check_timezone(name)
+      Parser.iana_timezone(name) or
+        raise error("timezone must be UTC or an Area/Location name such as America/New_York, got #{Utf8.convert(name)}")
+    end
+
+    def check_name(value, names, kind)
+      raise TypeError, "#{kind} must be a Symbol, not #{value.class}" unless value.is_a?(Symbol)
+      raise unknown(kind, value) unless names.include?(value)
+
+      value
+    end
+
+    def integer(value, what)
+      raise TypeError, "#{what} must be an Integer, not #{value.class}" unless value.is_a?(Integer)
+    end
+
+    def string(value, what)
+      raise TypeError, "#{what} must be a String, not #{value.class}" unless value.is_a?(String)
+
+      String.new(value)
+    end
+
+    def list(value, what)
+      raise TypeError, "#{what} must be an Array, not #{value.class}" unless value.is_a?(Array)
+
+      value
+    end
+
+    def unknown(kind, value)
+      error("unknown #{kind} #{value.inspect}")
+    end
+
+    def error(message)
+      HronError.eval(message)
+    end
+  end
+end

data/lib/hron/schedule.rb

@@ -4,65 +4,96 @@ require_relative "parser"
 require_relative "evaluator"
 require_relative "display"
 require_relative "cron"
+require_relative "parts"
 
 module Hron
-  # Main Schedule class - the primary public API for hron
+  # Each method that takes a time takes a Time in any zone and reads only its instant, and
+  # raises TypeError for anything else. Each Time returned is in the schedule's timezone, with
+  # that TZInfo::Timezone as its zone, or in UTC when the schedule has none.
   class Schedule
+    # The frozen ScheduleData this schedule was built from, with the timezone in its IANA
+    # capitalization.
     attr_reader :data
 
+    # Builds a schedule from a ScheduleData, checked by the rules parse applies. Raises HronError
+    # of kind :eval for the first part that breaks one, in the order of spec/README.md,
+    # "Schedules built in code", and TypeError for a part of the wrong type. Keeps a frozen
+    # copy, so later changes to data's lists and strings do not change the schedule.
     def initialize(data)
-      @data = data
+      @data = Ractor.make_shareable(Parts.checked(data))
     end
 
-    # Parse a hron expression and return a Schedule
+    # For parse and from_cron, whose parts already keep every rule and are their own.
+    def self.from_valid(data)
+      allocate.tap { |schedule| schedule.instance_variable_set(:@data, Ractor.make_shareable(data)) }
+    end
+    private_class_method :from_valid
+
+    # Raises HronError if the expression is invalid, and TypeError unless input is a String.
     def self.parse(input)
-      new(Hron.parse(input))
+      require_string(input, "input")
+      from_valid(Parser.parse(input))
     end
 
-    # Parse a cron expression and return a Schedule
+    # Converts a 5-field cron expression to a Schedule that fires at the same times. Raises
+    # HronError of kind :cron when it is not valid cron or has no exact hron equivalent, and
+    # TypeError unless cron_expr is a String.
     def self.from_cron(cron_expr)
-      new(Cron.from_cron(cron_expr))
+      require_string(cron_expr, "cron_expr")
+      from_valid(Cron.from_cron(cron_expr))
     end
 
-    # Validate a hron expression without raising an error
+    # True when parse accepts input, false when it raises HronError. Raises TypeError unless
+    # input is a String.
     def self.validate(input)
-      Hron.parse(input)
+      require_string(input, "input")
+      Parser.parse(input)
       true
     rescue HronError
       false
     end
 
-    # Get the next occurrence from the given time
+    # A usage error, never a HronError or false (spec/README.md, "Timestamps and counts").
+    def self.require_string(value, name)
+      raise TypeError, "#{name} must be a String, not #{value.class}" unless value.is_a?(String)
+    end
+    private_class_method :require_string
+
+    # Returns the next occurrence strictly after now, or nil if there is none.
     def next_from(now)
       Evaluator.next_from(@data, now)
     end
 
-    # Get the next N occurrences from the given time
+    # Returns an Array of up to n occurrences strictly after now, empty when n <= 0. Raises
+    # TypeError unless n is an Integer.
     def next_n_from(now, n)
       Evaluator.next_n_from(@data, now, n)
     end
 
-    # Get the most recent occurrence strictly before the given time
+    # Returns the most recent occurrence strictly before now, or nil if there is none.
     def previous_from(now)
       Evaluator.previous_from(@data, now)
     end
 
-    # Check if the schedule matches the given datetime
+    # True when the minute containing dt, on the schedule's wall clock, is an occurrence.
     def matches(dt)
       Evaluator.matches(@data, dt)
     end
 
-    # Returns a lazy Enumerator of occurrences starting after `from`
+    # Returns a lazy Enumerator of occurrences strictly after from. Unbounded for repeating
+    # schedules unless an until clause or the end of the supported range ends them.
     def occurrences(from)
       Evaluator.occurrences(@data, from)
     end
 
-    # Returns a lazy Enumerator of occurrences where from < occurrence <= to
+    # Returns a lazy Enumerator of occurrences where from < occurrence <= to, empty when either
+    # bound is outside the supported range.
     def between(from, to)
       Evaluator.between(@data, from, to)
     end
 
-    # Convert to 5-field cron expression
+    # Converts to a 5-field cron expression that fires at the same times, leaving out the
+    # timezone. Raises HronError of kind :cron when no cron does.
     def to_cron
       Cron.to_cron(@data)
     end
@@ -72,19 +103,50 @@ module Hron
       Display.display(@data)
     end
 
-    # Get inspect representation
     def inspect
       "Schedule(\"#{self}\")"
     end
 
-    # Get the timezone
+    # Schedules are equal when their parts are.
+    def ==(other)
+      other.is_a?(Schedule) && data == other.data
+    end
+
+    def eql?(other)
+      other.is_a?(Schedule) && data.eql?(other.data)
+    end
+
+    def hash
+      data.hash
+    end
+
+    # Returns the IANA timezone name with its canonical capitalization, or nil if none was given.
     def timezone
       @data.timezone
     end
 
-    # Get the schedule expression
     def expression
-      @data.expr
+      @data.expression
+    end
+
+    # The except dates, in the order written; empty without an except clause.
+    def except
+      @data.except
+    end
+
+    # An IsoUntil or NamedUntil, or nil without an until clause.
+    def until
+      @data.until
+    end
+
+    # The starting date as a YYYY-MM-DD String, or nil without a starting clause.
+    def starting
+      @data.starting
+    end
+
+    # The during months as Symbols, in the order written; empty without a during clause.
+    def during
+      @data.during
     end
   end
 end

data/lib/hron/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hron
-  VERSION = "0.6.1"
+  VERSION = "2.0.0"
 end

data/lib/hron.rb

@@ -8,21 +8,31 @@ require_relative "hron/parser"
 require_relative "hron/evaluator"
 require_relative "hron/display"
 require_relative "hron/cron"
+require_relative "hron/parts"
 require_relative "hron/schedule"
 
 module Hron
+  # Parser, Evaluator, Display and Cron take or return a schedule's parts without the checks
+  # of Schedule.new, Parts is those checks, and Lexer gives Parser its tokens, so only code
+  # inside Hron uses them (spec/README.md, "Schedules built in code").
+  private_constant :Lexer, :Parser, :Evaluator, :Display, :Cron, :Parts
+
   class << self
-    # Parse a hron expression and return a Schedule
+    # Parses a hron expression into a Schedule. Raises HronError if it is invalid, and TypeError
+    # unless input is a String.
     def parse_schedule(input)
       Schedule.parse(input)
     end
 
-    # Validate a hron expression without raising an error
+    # True when parse accepts input, false when it raises HronError. Raises TypeError unless
+    # input is a String.
     def validate(input)
       Schedule.validate(input)
     end
 
-    # Parse from a cron expression
+    # Converts a 5-field cron expression to a Schedule that fires at the same times. Raises
+    # HronError of kind :cron when it is not valid cron or has no exact hron equivalent, and
+    # TypeError unless cron_expr is a String.
     def from_cron(cron_expr)
       Schedule.from_cron(cron_expr)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hron
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Prasanna Venkataraman
@@ -23,53 +23,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.20'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.20'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: standard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.43'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.43'
 description: hron (human-readable cron) is a scheduling expression language that is
-  designed to be easy to read, write, and understand. It is a superset of cron, meaning
-  any valid cron expression can be converted to and from hron.
+  designed to be easy to read, write, and understand. It converts to and from cron
+  exactly where both can express a schedule, and expresses schedules cron cannot.
 email:
-- prasrvenkat@gmail.com
+- pras@simpllyf.io
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -82,18 +40,21 @@ files:
 - lib/hron/cron.rb
 - lib/hron/display.rb
 - lib/hron/error.rb
+- lib/hron/eval/calendar.rb
+- lib/hron/eval/wall_clock.rb
 - lib/hron/evaluator.rb
 - lib/hron/lexer.rb
 - lib/hron/parser.rb
+- lib/hron/parts.rb
 - lib/hron/schedule.rb
 - lib/hron/version.rb
-homepage: https://github.com/prasrvenkat/hron
+homepage: https://hron.io
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/prasrvenkat/hron
-  source_code_uri: https://github.com/prasrvenkat/hron
-  changelog_uri: https://github.com/prasrvenkat/hron/releases
+  homepage_uri: https://hron.io
+  source_code_uri: https://github.com/simpllyf/hron
+  changelog_uri: https://github.com/simpllyf/hron/releases
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -109,8 +70,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Human-readable cron — a scheduling expression language that is a superset
-  of cron
+summary: Human-readable cron — scheduling expressions that read like English and convert
+  to and from cron
 test_files: []