hron 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee599aa7c2d192e696b13aa9ce580646930f177d12fea11207c8a0364ce72098
+  data.tar.gz: 6c0ad8e2e53cad36ceb9e3cf6f93ea2d8a981d1201c739680b3d90fecc74fcc6
+SHA512:
+  metadata.gz: 160761a9f062f461cc93613fb4008279fac3200183b128079440c734a328e32a8f682c374692307420ce8c0e672523e8d9db0df5ee854bd096aef4f8b084ce5e
+  data.tar.gz: f216e50bc6d69ae4a6a6a22396eea71777b051e34e4af3ff21fd245f45a1936385f0a70999276f977c1fb9f12cc16b9a1ce9a594449d4d51b3d01e5799a2a179

data/README.md

@@ -0,0 +1,98 @@
+# hron
+
+**Human-readable cron** — scheduling expressions that are a superset of what cron can express.
+
+```ruby
+require 'hron'
+
+schedule = Hron::Schedule.parse("every weekday at 9:00 in America/New_York")
+```
+
+## Install
+
+```sh
+gem install hron
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'hron'
+```
+
+## Usage
+
+```ruby
+require 'hron'
+
+# Parse an expression
+schedule = Hron::Schedule.parse("every weekday at 9:00 except dec 25, jan 1 in America/New_York")
+
+# Get next occurrence
+now = Time.now
+next_time = schedule.next_from(now)
+puts next_time
+
+# Get next 5 occurrences
+upcoming = schedule.next_n_from(now, 5)
+upcoming.each { |t| puts t }
+
+# Check if a time matches
+schedule.matches(Time.new(2026, 2, 9, 9, 0, 0))  # true
+
+# Convert to/from cron
+simple = Hron::Schedule.parse("every day at 9:00")
+puts simple.to_cron  # "0 9 * * *"
+
+from_cron = Hron::Schedule.from_cron("*/30 * * * *")
+puts from_cron  # "every 30 min from 00:00 to 23:59"
+
+# Validate without exceptions
+Hron::Schedule.validate("every day at 9:00")  # true
+Hron::Schedule.validate("invalid")  # false
+```
+
+## Expression Syntax
+
+See the full [expression reference](https://github.com/prasrvenkat/hron#expression-syntax).
+
+## API
+
+### `Hron::Schedule.parse(input) -> Schedule`
+Parse an hron expression string.
+
+### `Hron::Schedule.from_cron(cron_expr) -> Schedule`
+Convert a 5-field cron expression to a Schedule.
+
+### `Hron::Schedule.validate(input) -> Boolean`
+Check if an input string is a valid hron expression.
+
+### `schedule.next_from(now) -> Time | nil`
+Compute the next occurrence after `now`.
+
+### `schedule.next_n_from(now, n) -> Array<Time>`
+Compute the next `n` occurrences after `now`.
+
+### `schedule.matches(time) -> Boolean`
+Check if a time matches this schedule.
+
+### `schedule.to_cron -> String`
+Convert to a 5-field cron expression. Raises `Hron::HronError` if the schedule can't be expressed as cron.
+
+### `schedule.to_s -> String`
+Render as the canonical string form (roundtrip-safe).
+
+### `schedule.timezone -> String | nil`
+The timezone, if specified.
+
+### `schedule.expression -> ScheduleExpr`
+The underlying schedule expression AST.
+
+## Requirements
+
+- Ruby >= 3.2
+- TZInfo gem for timezone support
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: %i[test standard]

data/hron.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/hron/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "hron"
+  spec.version = Hron::VERSION
+  spec.authors = ["Prasanna Venkataraman"]
+  spec.email = ["prasrvenkat@gmail.com"]
+
+  spec.summary = "Human-readable cron — a scheduling expression language that is a superset of cron"
+  spec.description = "HRON (Human Readable Object Notation for schedules) 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."
+  spec.homepage = "https://github.com/prasrvenkat/hron"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 4.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/prasrvenkat/hron"
+  spec.metadata["changelog_uri"] = "https://github.com/prasrvenkat/hron/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "tzinfo", "~> 2.0"
+
+  spec.add_development_dependency "minitest", "~> 5.20"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "standard", "~> 1.43"
+end

data/lib/hron/ast.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Hron
+  # Weekday enumeration (ISO 8601: Monday=1, Sunday=7)
+  module Weekday
+    MONDAY = :monday
+    TUESDAY = :tuesday
+    WEDNESDAY = :wednesday
+    THURSDAY = :thursday
+    FRIDAY = :friday
+    SATURDAY = :saturday
+    SUNDAY = :sunday
+
+    ALL = [MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY].freeze
+    WEEKDAYS = [MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY].freeze
+    WEEKEND = [SATURDAY, SUNDAY].freeze
+
+    NUMBERS = {
+      MONDAY => 1, TUESDAY => 2, WEDNESDAY => 3, THURSDAY => 4,
+      FRIDAY => 5, SATURDAY => 6, SUNDAY => 7
+    }.freeze
+
+    CRON_DOW = {
+      SUNDAY => 0, MONDAY => 1, TUESDAY => 2, WEDNESDAY => 3,
+      THURSDAY => 4, FRIDAY => 5, SATURDAY => 6
+    }.freeze
+
+    NUMBER_TO_WEEKDAY = NUMBERS.invert.freeze
+
+    PARSE_MAP = {
+      "monday" => MONDAY, "mon" => MONDAY,
+      "tuesday" => TUESDAY, "tue" => TUESDAY,
+      "wednesday" => WEDNESDAY, "wed" => WEDNESDAY,
+      "thursday" => THURSDAY, "thu" => THURSDAY,
+      "friday" => FRIDAY, "fri" => FRIDAY,
+      "saturday" => SATURDAY, "sat" => SATURDAY,
+      "sunday" => SUNDAY, "sun" => SUNDAY
+    }.freeze
+
+    def self.number(day)
+      NUMBERS[day]
+    end
+
+    def self.cron_dow(day)
+      CRON_DOW[day]
+    end
+
+    def self.from_number(n)
+      NUMBER_TO_WEEKDAY[n]
+    end
+
+    def self.try_parse(s)
+      PARSE_MAP[s.downcase]
+    end
+
+    def self.to_s(day)
+      day.to_s
+    end
+  end
+
+  # Month name enumeration
+  module MonthName
+    JAN = :jan
+    FEB = :feb
+    MAR = :mar
+    APR = :apr
+    MAY = :may
+    JUN = :jun
+    JUL = :jul
+    AUG = :aug
+    SEP = :sep
+    OCT = :oct
+    NOV = :nov
+    DEC = :dec
+
+    ALL = [JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC].freeze
+
+    NUMBERS = {
+      JAN => 1, FEB => 2, MAR => 3, APR => 4, MAY => 5, JUN => 6,
+      JUL => 7, AUG => 8, SEP => 9, OCT => 10, NOV => 11, DEC => 12
+    }.freeze
+
+    NUMBER_TO_MONTH = NUMBERS.invert.freeze
+
+    PARSE_MAP = {
+      "january" => JAN, "jan" => JAN,
+      "february" => FEB, "feb" => FEB,
+      "march" => MAR, "mar" => MAR,
+      "april" => APR, "apr" => APR,
+      "may" => MAY,
+      "june" => JUN, "jun" => JUN,
+      "july" => JUL, "jul" => JUL,
+      "august" => AUG, "aug" => AUG,
+      "september" => SEP, "sep" => SEP,
+      "october" => OCT, "oct" => OCT,
+      "november" => NOV, "nov" => NOV,
+      "december" => DEC, "dec" => DEC
+    }.freeze
+
+    def self.number(month)
+      NUMBERS[month]
+    end
+
+    def self.from_number(n)
+      NUMBER_TO_MONTH[n]
+    end
+
+    def self.try_parse(s)
+      PARSE_MAP[s.downcase]
+    end
+
+    def self.to_s(month)
+      month.to_s
+    end
+  end
+
+  # Interval unit (minutes or hours)
+  module IntervalUnit
+    MIN = :min
+    HOURS = :hours
+
+    def self.to_s(unit)
+      unit.to_s
+    end
+  end
+
+  # Ordinal position (first, second, etc.)
+  module OrdinalPosition
+    FIRST = :first
+    SECOND = :second
+    THIRD = :third
+    FOURTH = :fourth
+    FIFTH = :fifth
+    LAST = :last
+
+    TO_N = {
+      FIRST => 1, SECOND => 2, THIRD => 3, FOURTH => 4, FIFTH => 5
+    }.freeze
+
+    def self.to_n(ord)
+      TO_N[ord]
+    end
+
+    def self.to_s(ord)
+      ord.to_s
+    end
+  end
+
+  # Time of day (hour and minute)
+  TimeOfDay = Data.define(:hour, :minute) do
+    def to_s
+      format("%02d:%02d", hour, minute)
+    end
+  end
+
+  # --- Day filter variants ---
+
+  DayFilterEvery = Data.define
+  DayFilterWeekday = Data.define
+  DayFilterWeekend = Data.define
+  DayFilterDays = Data.define(:days) # days: Array<Weekday>
+
+  # --- Day of month spec ---
+
+  SingleDay = Data.define(:day)
+  DayRange = Data.define(:start, :end_day) # end_day to avoid Ruby keyword
+
+  # --- Month target variants ---
+
+  DaysTarget = Data.define(:specs) # specs: Array<DayOfMonthSpec>
+  LastDayTarget = Data.define
+  LastWeekdayTarget = Data.define
+
+  # --- Year target variants ---
+
+  YearDateTarget = Data.define(:month, :day)
+  YearOrdinalWeekdayTarget = Data.define(:ordinal, :weekday, :month)
+  YearDayOfMonthTarget = Data.define(:day, :month)
+  YearLastWeekdayTarget = Data.define(:month)
+
+  # --- Date spec variants ---
+
+  NamedDate = Data.define(:month, :day)
+  IsoDate = Data.define(:date) # date: String (YYYY-MM-DD)
+
+  # --- Exception spec variants ---
+
+  NamedException = Data.define(:month, :day)
+  IsoException = Data.define(:date)
+
+  # --- Until spec variants ---
+
+  IsoUntil = Data.define(:date)
+  NamedUntil = Data.define(:month, :day)
+
+  # --- Schedule expression variants ---
+
+  IntervalRepeat = Data.define(:interval, :unit, :from_time, :to_time, :day_filter)
+  DayRepeat = Data.define(:interval, :days, :times)
+  WeekRepeat = Data.define(:interval, :days, :times)
+  MonthRepeat = Data.define(:interval, :target, :times)
+  OrdinalRepeat = Data.define(:interval, :ordinal, :day, :times)
+  SingleDateExpr = Data.define(:date, :times)
+  YearRepeat = Data.define(:interval, :target, :times)
+
+  # --- Schedule data (top-level) ---
+
+  ScheduleData = Data.define(:expr, :timezone, :except, :until, :anchor, :during) do
+    def initialize(expr:, timezone: nil, except: [], until: nil, anchor: nil, during: [])
+      super
+    end
+  end
+
+  # --- Helper functions ---
+
+  def self.expand_day_spec(spec)
+    case spec
+    when SingleDay
+      [spec.day]
+    when DayRange
+      (spec.start..spec.end_day).to_a
+    else
+      []
+    end
+  end
+
+  def self.expand_month_target(target)
+    case target
+    when DaysTarget
+      target.specs.flat_map { |spec| expand_day_spec(spec) }
+    else
+      []
+    end
+  end
+end

data/lib/hron/cron.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+require_relative "error"
+
+module Hron
+  # Cron conversion module
+  module Cron
+    CRON_DOW_MAP = {
+      0 => Weekday::SUNDAY,
+      1 => Weekday::MONDAY,
+      2 => Weekday::TUESDAY,
+      3 => Weekday::WEDNESDAY,
+      4 => Weekday::THURSDAY,
+      5 => Weekday::FRIDAY,
+      6 => Weekday::SATURDAY,
+      7 => Weekday::SUNDAY
+    }.freeze
+
+    def self.to_cron(schedule)
+      raise HronError.cron("not expressible as cron (except clauses not supported)") unless schedule.except.empty?
+
+      raise HronError.cron("not expressible as cron (until clauses not supported)") if schedule.until
+
+      raise HronError.cron("not expressible as cron (during clauses not supported)") unless schedule.during.empty?
+
+      expr = schedule.expr
+
+      case expr
+      when DayRepeat
+        raise HronError.cron("not expressible as cron (multi-day intervals not supported)") if expr.interval > 1
+        raise HronError.cron("not expressible as cron (multiple times not supported)") if expr.times.length != 1
+
+        time = expr.times[0]
+        dow = day_filter_to_cron_dow(expr.days)
+        "#{time.minute} #{time.hour} * * #{dow}"
+
+      when IntervalRepeat
+        full_day = expr.from_time.hour.zero? && expr.from_time.minute.zero? &&
+          expr.to_time.hour == 23 && expr.to_time.minute == 59
+        raise HronError.cron("not expressible as cron (partial-day interval windows not supported)") unless full_day
+
+        raise HronError.cron("not expressible as cron (interval with day filter not supported)") if expr.day_filter
+
+        if expr.unit == IntervalUnit::MIN
+          if (60 % expr.interval) != 0
+            raise HronError.cron("not expressible as cron (*/#{expr.interval} breaks at hour boundaries)")
+          end
+
+          "*/#{expr.interval} * * * *"
+        else
+          "0 */#{expr.interval} * * *"
+        end
+
+      when WeekRepeat
+        raise HronError.cron("not expressible as cron (multi-week intervals not supported)")
+
+      when MonthRepeat
+        raise HronError.cron("not expressible as cron (multi-month intervals not supported)") if expr.interval > 1
+        raise HronError.cron("not expressible as cron (multiple times not supported)") if expr.times.length != 1
+
+        time = expr.times[0]
+        case expr.target
+        when DaysTarget
+          expanded = []
+          expr.target.specs.each do |s|
+            case s
+            when SingleDay
+              expanded << s.day
+            when DayRange
+              (s.start..s.end_day).each { |d| expanded << d }
+            end
+          end
+          dom = expanded.join(",")
+          "#{time.minute} #{time.hour} #{dom} * *"
+        when LastDayTarget
+          raise HronError.cron("not expressible as cron (last day of month not supported)")
+        else
+          raise HronError.cron("not expressible as cron (last weekday of month not supported)")
+        end
+
+      when OrdinalRepeat
+        raise HronError.cron("not expressible as cron (ordinal weekday of month not supported)")
+
+      when SingleDateExpr
+        raise HronError.cron("not expressible as cron (single dates are not repeating)")
+
+      when YearRepeat
+        raise HronError.cron("not expressible as cron (yearly schedules not supported in 5-field cron)")
+
+      else
+        raise HronError.cron("unknown expression type: #{expr.class}")
+      end
+    end
+
+    def self.day_filter_to_cron_dow(filter)
+      case filter
+      when DayFilterEvery
+        "*"
+      when DayFilterWeekday
+        "1-5"
+      when DayFilterWeekend
+        "0,6"
+      when DayFilterDays
+        nums = filter.days.map { |d| Weekday.cron_dow(d) }.sort
+        nums.join(",")
+      end
+    end
+
+    def self.from_cron(cron_str)
+      fields = cron_str.strip.split
+      raise HronError.cron("expected 5 cron fields, got #{fields.length}") if fields.length != 5
+
+      minute_field, hour_field, dom_field, _month_field, dow_field = fields
+
+      # Minute interval: */N
+      if minute_field.start_with?("*/")
+        interval_str = minute_field[2..]
+        begin
+          interval = Integer(interval_str)
+        rescue ArgumentError
+          raise HronError.cron("invalid minute interval")
+        end
+
+        from_hour = 0
+        to_hour = 23
+
+        if hour_field == "*"
+          # full day
+        elsif hour_field.include?("-")
+          parts = hour_field.split("-")
+          begin
+            from_hour = Integer(parts[0])
+            to_hour = Integer(parts[1])
+          rescue ArgumentError, IndexError
+            raise HronError.cron("invalid hour range")
+          end
+        else
+          begin
+            h = Integer(hour_field)
+          rescue ArgumentError
+            raise HronError.cron("invalid hour")
+          end
+          from_hour = h
+          to_hour = h
+        end
+
+        day_filter = (dow_field == "*") ? nil : parse_cron_dow(dow_field)
+
+        if dom_field == "*"
+          return ScheduleData.new(
+            expr: IntervalRepeat.new(
+              interval,
+              IntervalUnit::MIN,
+              TimeOfDay.new(from_hour, 0),
+              TimeOfDay.new(to_hour, (to_hour == 23) ? 59 : 0),
+              day_filter
+            )
+          )
+        end
+      end
+
+      # Hour interval: 0 */N
+      if hour_field.start_with?("*/") && minute_field == "0"
+        interval_str = hour_field[2..]
+        begin
+          interval = Integer(interval_str)
+        rescue ArgumentError
+          raise HronError.cron("invalid hour interval")
+        end
+        if dom_field == "*" && dow_field == "*"
+          return ScheduleData.new(
+            expr: IntervalRepeat.new(
+              interval,
+              IntervalUnit::HOURS,
+              TimeOfDay.new(0, 0),
+              TimeOfDay.new(23, 59),
+              nil
+            )
+          )
+        end
+      end
+
+      # Standard time-based cron
+      begin
+        minute = Integer(minute_field)
+      rescue ArgumentError
+        raise HronError.cron("invalid minute field: #{minute_field}")
+      end
+      begin
+        hour = Integer(hour_field)
+      rescue ArgumentError
+        raise HronError.cron("invalid hour field: #{hour_field}")
+      end
+      t = TimeOfDay.new(hour, minute)
+
+      # DOM-based (monthly)
+      if dom_field != "*" && dow_field == "*"
+        raise HronError.cron("DOM ranges not supported: #{dom_field}") if dom_field.include?("-")
+
+        day_nums = []
+        dom_field.split(",").each do |s|
+          begin
+            n = Integer(s)
+          rescue ArgumentError
+            raise HronError.cron("invalid DOM field: #{dom_field}")
+          end
+          day_nums << n
+        end
+        specs = day_nums.map { |d| SingleDay.new(d) }
+        return ScheduleData.new(
+          expr: MonthRepeat.new(1, DaysTarget.new(specs), [t])
+        )
+      end
+
+      # DOW-based (day repeat)
+      days = parse_cron_dow(dow_field)
+      expr = DayRepeat.new(1, days, [t])
+      ScheduleData.new(expr: expr)
+    end
+
+    def self.parse_cron_dow(field)
+      return DayFilterEvery.new if field == "*"
+      return DayFilterWeekday.new if field == "1-5"
+      return DayFilterWeekend.new if ["0,6", "6,0"].include?(field)
+
+      raise HronError.cron("DOW ranges not supported: #{field}") if field.include?("-")
+
+      nums = []
+      field.split(",").each do |s|
+        begin
+          n = Integer(s)
+        rescue ArgumentError
+          raise HronError.cron("invalid DOW field: #{field}")
+        end
+        nums << n
+      end
+
+      days = nums.map { |n| cron_dow_to_weekday(n) }
+      DayFilterDays.new(days)
+    end
+
+    def self.cron_dow_to_weekday(n)
+      result = CRON_DOW_MAP[n]
+      raise HronError.cron("invalid DOW number: #{n}") unless result
+
+      result
+    end
+  end
+end