hron 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d473172aff0a9bd7a16cfdc2e43e978b060ab34068c2171eeb0df086a164061
-  data.tar.gz: 91f5ba0d255821fc2bbb9bc479d4784bf6a29d0b493b4dd1bb2f6a4da284b528
+  metadata.gz: 7b86b962f2f1a4ea1f9d78eccd38e02c5a7c98173e1ea246d132f989aaecc832
+  data.tar.gz: bf56a14f1874cfdcf5904445dbcacf771c5c5d67cd4e9595eb409a831aab89ec
 SHA512:
-  metadata.gz: 5a85275560b5a597f84c92c5c995e7e6ad59bff97f1748c941c9ae61684f131df7416705a1e45264c6c6bac3e0376e15372f69b4f9a3541e2312be1ccd397d51
-  data.tar.gz: 07dce6bdff312778441771040b89154567f7a70186729f47dadb2bd84e271d07d3f3a8d6cbd3020b3fa92e93ac2e188009adae437bdf9e23b13e5128549ced3f
+  metadata.gz: 169fb279979c7ce3a32fd71dac48186d45acb3f73417651a8db376d98034e6d37a072397cfd086d93685b92d7b343eb3fe7c317865b4323c7515dc5124a2a73a
+  data.tar.gz: df1da08a823a003f6bcdeb9df1ab72c96c4a6e15b8e6e675d126a1bb93f39f548fc451ba8e57167e0c3b63eb0436f71c7ae9392897f7786645cce01a7e59605e

data/README.md

@@ -1,6 +1,6 @@
 # hron
 
-**Human-readable cron** — scheduling expressions that are a superset of what cron can express.
+**Human-readable cron** — scheduling expressions that read like English and convert to and from cron.
 
 ```ruby
 require 'hron'
@@ -28,17 +28,18 @@ 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 the next occurrence, in the schedule's timezone
+now = Time.new(2026, 2, 6, 21, 0, 0, "+09:00")  # 07:00 in New York
+puts schedule.next_from(now)  # 2026-02-06 09:00:00 -0500
 
-# Get next 5 occurrences
-upcoming = schedule.next_n_from(now, 5)
-upcoming.each { |t| puts t }
+# Get the next 3 occurrences
+schedule.next_n_from(now, 3).each { |t| puts t }
+# 2026-02-06 09:00:00 -0500
+# 2026-02-09 09:00:00 -0500
+# 2026-02-10 09:00:00 -0500
 
 # Check if a time matches
-schedule.matches(Time.new(2026, 2, 9, 9, 0, 0))  # true
+schedule.matches(Time.new(2026, 2, 9, 9, 0, 0, "-05:00"))  # true: 09:00 in New York
 
 # Convert to/from cron
 simple = Hron::Schedule.parse("every day at 9:00")
@@ -50,48 +51,152 @@ 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
+
+# Build from parts, checked as parse checks text
+data = Hron::ScheduleData.new(
+  expression: Hron::DayRepeat.new(1, Hron::DayFilterWeekday.new, [Hron::TimeOfDay.new(9, 0)]),
+  timezone: "america/new_york"
+)
+puts Hron::Schedule.new(data)  # every weekday at 09:00 in America/New_York
+begin
+  Hron::Schedule.new(data.with(timezone: "EST"))
+rescue Hron::HronError => e
+  puts e.message  # timezone must be UTC or an Area/Location name such as America/New_York, got EST
+end
 ```
 
 ## Expression Syntax
 
-See the full [expression reference](https://github.com/prasrvenkat/hron#expression-syntax).
+See the full [expression reference](https://github.com/simpllyf/hron#expression-syntax).
 
 ## API
 
 ### `Hron::Schedule.parse(input) -> Schedule`
-Parse an hron expression string.
+Parse an hron expression string. Raises `Hron::HronError` with `kind` `:lex` or `:parse` when it is invalid (see [Errors](#errors)), and `TypeError` unless `input` is a `String`.
 
 ### `Hron::Schedule.from_cron(cron_expr) -> Schedule`
-Convert a 5-field cron expression to a Schedule.
+Convert a 5-field cron expression to a Schedule that fires at the same times. This ignores the timezone and DST transitions, where cron schedulers differ. Raises `Hron::HronError` with `kind` `:cron` for invalid cron, for crons that restrict both the day of month and the day of week (`0 9 15 * 1`), and for more than 24 times a day, unless they are evenly spaced on days an interval can carry (`*/7 * * * *` fires 216 times at uneven gaps). Raises `TypeError` unless `cron_expr` is a `String`.
 
 ### `Hron::Schedule.validate(input) -> Boolean`
-Check if an input string is a valid hron expression.
+`true` when `parse` accepts `input`, `false` when it raises `Hron::HronError`. Raises `TypeError` unless `input` is a `String`.
+
+### `Hron::Schedule.new(data) -> Schedule`
+Build a schedule from a `Hron::ScheduleData` (see [Building a schedule](#building-a-schedule)), checked by the rules `parse` applies, so it evaluates, displays and converts as a parsed one does. Raises `Hron::HronError` with `kind` `:eval` and no `span`, `input` or `suggestion` for the first part that breaks a rule, with the message and in the order of the [spec](https://github.com/simpllyf/hron/blob/main/spec/README.md#schedules-built-in-code), and `TypeError` for a part of the wrong type. The schedule keeps a frozen copy of `data`, so changing `data`'s lists or strings afterwards does not change it.
 
 ### `schedule.next_from(now) -> Time | nil`
 Compute the next occurrence after `now`.
 
+### `schedule.previous_from(now) -> Time | nil`
+Compute the most recent occurrence before `now`.
+
 ### `schedule.next_n_from(now, n) -> Array<Time>`
-Compute the next `n` occurrences after `now`.
+Compute up to `n` occurrences after `now`: none when `n <= 0`, and every one through the end of the supported range when there are fewer than `n`. Raises `TypeError` when `n` is not an `Integer`.
 
 ### `schedule.matches(time) -> Boolean`
 Check if a time matches this schedule.
 
+### `schedule.occurrences(from) -> Enumerator::Lazy<Time>`
+Every occurrence after `from`, computed as it is taken.
+
+### `schedule.between(from, to) -> Enumerator::Lazy<Time>`
+Every occurrence after `from` and up to and including `to`.
+
+### Times
+
+Every method takes a `Time` in any zone or offset; only its instant counts, and the methods never change it. Anything else, such as a `String`, `Date`, `DateTime` or `nil`, raises `TypeError`. Every `Time` returned is in the schedule's timezone, with that `TZInfo::Timezone` as its `zone`, or UTC when the schedule has none.
+
 ### `schedule.to_cron -> String`
-Convert to a 5-field cron expression. Raises `Hron::HronError` if the schedule can't be expressed as cron.
+Convert to a 5-field cron expression that fires at the same times. Yearly schedules, ordinal weekdays and partial-day intervals convert (`every 15 min from 09:00 to 17:45 on weekday` is `*/15 9-17 * * 1-5`). Raises `Hron::HronError` with `kind` `:cron` when no cron fires at the same times, as for `except`, `until`, `starting`, ISO dates, repeats every `n > 1` days, weeks, months or years, a directional nearest weekday, a `during` that excludes a yearly or named date's month, and times that are not every combination of their minutes and hours (`at 09:00, 17:30`). The timezone is not part of the cron: run it in the schedule's timezone. The [spec](https://github.com/simpllyf/hron/blob/main/spec/README.md#cron-conversion) has the full rules and every error message.
 
 ### `schedule.to_s -> String`
 Render as the canonical string form (roundtrip-safe).
 
-### `schedule.timezone -> String | nil`
-The timezone, if specified.
+### Getters
+
+Each getter returns one part of the schedule, with the classes under [Building a schedule](#building-a-schedule). What they return is frozen, so it cannot change the schedule.
+
+| Getter | Returns |
+|---|---|
+| `schedule.expression` | The expression: an `IntervalRepeat`, `DayRepeat`, `WeekRepeat`, `MonthRepeat`, `SingleDateExpr` or `YearRepeat`. |
+| `schedule.timezone` | The IANA timezone name with its canonical capitalization (`in utc` gives `"UTC"`), or `nil`. |
+| `schedule.except` | An `Array` of `NamedException` and `IsoException` in the order written; empty without an `except` clause. |
+| `schedule.until` | An `IsoUntil` or `NamedUntil`, or `nil`. |
+| `schedule.starting` | The `starting` date as a `"YYYY-MM-DD"` `String`, or `nil`. |
+| `schedule.during` | An `Array` of month `Symbol`s in the order written; empty without a `during` clause. |
+
+```ruby
+schedule = Hron::Schedule.parse("every weekday at 9:00 except dec 25 starting 2026-01-05 during jan, feb")
+schedule.expression  # #<data Hron::DayRepeat interval=1, days=#<data Hron::DayFilterWeekday>, times=[#<data Hron::TimeOfDay hour=9, minute=0>]>
+schedule.except      # [#<data Hron::NamedException month=:dec, day=25>]
+schedule.until       # nil
+schedule.starting    # "2026-01-05"
+schedule.during      # [:jan, :feb]
+schedule.timezone    # nil
+```
+
+### `schedule.data -> ScheduleData`
+All the parts at once, frozen, with the timezone in its IANA capitalization. `Hron::Schedule.new(schedule.data.with(timezone: "UTC"))` builds a changed copy.
+
+### `schedule == other`, `schedule.eql?(other)` and `schedule.hash`
+Schedules are equal when their parts are, with lists compared in order and duplicates included, and equal schedules have equal hashes, so a schedule works as a `Hash` key. `Hron::Schedule.parse("every day at 9:00")` equals `Hron::Schedule.parse("every day at 09:00")` and the schedule built from the same parts. Comparing a schedule with `nil` or anything but a schedule gives `false`.
+
+### Usage errors
+
+A value of the wrong type where an argument goes raises `TypeError`, never `Hron::HronError`, and `validate` never returns `false` for it: an input to `parse`, `validate` or `from_cron` that is not a `String` (`nil` included), a time that is not a `Time`, an `n` that is not an `Integer`, a part of the wrong type in `Hron::Schedule.new`, and a message, span, input or suggestion of the wrong type in the [`Hron::HronError` factories](#errors).
+
+## Building a schedule
+
+`Hron::ScheduleData.new(expression:, timezone: nil, except: [], until: nil, starting: nil, during: [])` holds a schedule's parts; every class here is a `Data` and takes its fields in this order, positionally or by name. `Hron::Schedule.new` checks them.
+
+| Field | Value |
+|---|---|
+| `expression` | One expression below. |
+| `timezone` | `"UTC"` or an IANA `Area/Location` name in any case, or `nil` for UTC. |
+| `except` | An `Array` of `NamedException(month, day)` and `IsoException(date)`; empty means no `except` clause. |
+| `until` | `NamedUntil(month, day)`, which needs `starting`, `IsoUntil(date)`, or `nil`. |
+| `starting` | The `starting` date, or `nil`. |
+| `during` | An `Array` of months; empty means no `during` clause. |
+
+| Expression | Fields |
+|---|---|
+| `IntervalRepeat` | `interval`, `unit` (`:min` or `:hours`), `from_time`, `to_time`, `day_filter` (a day filter or `nil`) |
+| `DayRepeat` | `interval`, `days` (a day filter, `DayFilterEvery` when `interval` is above 1), `times` |
+| `WeekRepeat` | `interval`, `days` (an `Array` of weekdays), `times` |
+| `MonthRepeat` | `interval`, `target`: `DaysTarget(specs)` of `SingleDay(day)` and `DayRange(start, end_day)`, `LastDayTarget`, `LastWeekdayTarget`, `NearestWeekdayTarget(day, direction)` with `direction` `nil`, `:next` or `:previous`, or `OrdinalWeekdayTarget(ordinal, weekday)`; `times` |
+| `SingleDateExpr` | `date`: `NamedDate(month, day)` or `IsoDate(date)`; `times` |
+| `YearRepeat` | `interval`, `target`: `YearDateTarget(month, day)`, `YearOrdinalWeekdayTarget(ordinal, weekday, month)`, `YearDayOfMonthTarget(day, month)` or `YearLastWeekdayTarget(month)`; `times` |
+
+- `interval`, `day` and the `hour` and `minute` of `TimeOfDay(hour, minute)` are `Integer`s, `times` is an `Array` of `TimeOfDay`, and a date is a `"YYYY-MM-DD"` `String`.
+- A day filter is `DayFilterEvery.new`, `DayFilterWeekday.new`, `DayFilterWeekend.new` or `DayFilterDays(days)`, with `days` an `Array` of weekdays.
+- Names are `Symbol`s: weekdays `:monday` to `:sunday` (`Hron::Weekday::ALL`), months `:jan` to `:dec` (`Hron::MonthName::ALL`), and ordinals `:first` to `:fifth` and `:last` (`Hron::OrdinalPosition::ALL`). `Hron::OrdinalPosition.to_n` gives 1 to 5 for `:first` to `:fifth` and -1 for `:last`.
+- A name of another type, such as `"monday"`, is a `TypeError`; an unknown `Symbol`, such as `:january`, is an `:eval` error (`unknown month :january`), as is any value where an expression, day filter, day spec, target, date, exception or until goes that is none of its classes.
+
+## Errors
+
+Every hron error is a `Hron::HronError`, a `StandardError` with:
+
+| Member | Value |
+|---|---|
+| `kind` | `:lex` or `:parse` from `parse`, `:eval` from `Hron::Schedule.new` (see [above](#hronschedulenewdata---schedule)), `:cron` from `from_cron` and `to_cron`; the values of `Hron::ErrorKind`. |
+| `message` | The exact message of the [spec](https://github.com/simpllyf/hron/blob/main/spec/README.md#error-message-format). |
+| `span` | A `Hron::Span` with `start` and `end_pos` for `:lex` and `:parse`, otherwise `nil`. |
+| `input` | The input as given for `:lex` and `:parse`, otherwise `nil`. |
+| `suggestion` | A suggested fix for some `:parse` errors, otherwise `nil`. |
+| `display_rich` | `error: {message}`, and for `:lex` and `:parse` the input with carets under the span and any suggestion. |
+| `Hron::HronError.lex(message, span, input)`, `.parse(message, span, input, suggestion: nil)`, `.eval(message)`, `.cron(message)` | Build an error of each kind. Each 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`. |
+
+```text
+error: until dec 31 has no year: add a starting date, or use an ISO date
+  every weekday at 09:00 until dec 31
+                         ^^^^^^^^^^^^ try: "until dec 31 starting YYYY-MM-DD"
+```
 
-### `schedule.expression -> ScheduleExpr`
-The underlying schedule expression AST.
+`span.start` and `span.end_pos` mark `[start, end_pos)` in code points, which for a valid UTF-8 string are Ruby's own character indices: `error.input[error.span.start...error.span.end_pos]` is the text the error points at. Each byte of invalid UTF-8 counts as one code point and is reported as `unexpected character U+FFFD`. A binary (`ASCII-8BIT`) string is read as UTF-8 bytes, and a string in any other encoding is converted to UTF-8 first, so a lone UTF-16 surrogate is also U+FFFD.
 
 ## Requirements
 
-- Ruby >= 3.2
-- TZInfo gem for timezone support
+- Ruby >= 4.0
+- TZInfo gem for timezone support. TZInfo generates DST rules only about 100 years ahead of the current year; past that it keeps the zone's last offset, which is summer time for a southern-hemisphere zone such as Australia/Sydney.
 
 ## License
 

data/hron.gemspec

@@ -6,19 +6,19 @@ Gem::Specification.new do |spec|
   spec.name = "hron"
   spec.version = Hron::VERSION
   spec.authors = ["Prasanna Venkataraman"]
-  spec.email = ["prasrvenkat@gmail.com"]
+  spec.email = ["pras@simpllyf.io"]
 
-  spec.summary = "Human-readable cron — a scheduling expression language that is a superset of cron"
+  spec.summary = "Human-readable cron — scheduling expressions that read like English and convert to and from cron"
   spec.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."
-  spec.homepage = "https://github.com/prasrvenkat/hron"
+                     "that is 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."
+  spec.homepage = "https://hron.io"
   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/releases"
+  spec.metadata["source_code_uri"] = "https://github.com/simpllyf/hron"
+  spec.metadata["changelog_uri"] = "https://github.com/simpllyf/hron/releases"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
@@ -32,8 +32,4 @@ Gem::Specification.new do |spec|
   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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Hron
-  # Weekday enumeration (ISO 8601: Monday=1, Sunday=7)
   module Weekday
     MONDAY = :monday
     TUESDAY = :tuesday
@@ -37,10 +36,12 @@ module Hron
       "sunday" => SUNDAY, "sun" => SUNDAY
     }.freeze
 
+    # ISO 8601: Monday=1, Sunday=7.
     def self.number(day)
       NUMBERS[day]
     end
 
+    # Sunday=0 … Saturday=6.
     def self.cron_dow(day)
       CRON_DOW[day]
     end
@@ -58,7 +59,6 @@ module Hron
     end
   end
 
-  # Month name enumeration
   module MonthName
     JAN = :jan
     FEB = :feb
@@ -101,6 +101,15 @@ module Hron
       NUMBERS[month]
     end
 
+    # A named date has no year, so February has 29.
+    def self.max_day(month)
+      case month
+      when FEB then 29
+      when APR, JUN, SEP, NOV then 30
+      else 31
+      end
+    end
+
     def self.from_number(n)
       NUMBER_TO_MONTH[n]
     end
@@ -114,17 +123,17 @@ module Hron
     end
   end
 
-  # Interval unit (minutes or hours)
   module IntervalUnit
     MIN = :min
     HOURS = :hours
 
+    ALL = [MIN, HOURS].freeze
+
     def self.to_s(unit)
       unit.to_s
     end
   end
 
-  # Ordinal position (first, second, etc.)
   module OrdinalPosition
     FIRST = :first
     SECOND = :second
@@ -133,10 +142,13 @@ module Hron
     FIFTH = :fifth
     LAST = :last
 
+    ALL = [FIRST, SECOND, THIRD, FOURTH, FIFTH, LAST].freeze
+
     TO_N = {
-      FIRST => 1, SECOND => 2, THIRD => 3, FOURTH => 4, FIFTH => 5
+      FIRST => 1, SECOND => 2, THIRD => 3, FOURTH => 4, FIFTH => 5, LAST => -1
     }.freeze
 
+    # 1-5 for first to fifth, and -1 for last.
     def self.to_n(ord)
       TO_N[ord]
     end
@@ -146,64 +158,48 @@ module Hron
     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 ---
+  DayFilterDays = Data.define(:days)
 
   SingleDay = Data.define(:day)
   DayRange = Data.define(:start, :end_day) # end_day to avoid Ruby keyword
 
-  # --- Direction for nearest weekday ---
-
   module NearestDirection
     NEXT = :next
     PREVIOUS = :previous
-  end
 
-  # --- Month target variants ---
+    ALL = [NEXT, PREVIOUS].freeze
+  end
 
-  DaysTarget = Data.define(:specs) # specs: Array<DayOfMonthSpec>
+  DaysTarget = Data.define(:specs)
   LastDayTarget = Data.define
   LastWeekdayTarget = Data.define
-  NearestWeekdayTarget = Data.define(:day, :direction) # day: 1-31, direction: nil or NearestDirection
+  # A nil direction stays in the month, as cron W does; a direction can cross into the adjacent month.
+  NearestWeekdayTarget = Data.define(:day, :direction)
   OrdinalWeekdayTarget = Data.define(:ordinal, :weekday)
 
-  # --- 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 ---
+  IsoDate = Data.define(:date)
 
   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)
@@ -211,33 +207,11 @@ module Hron
   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: [])
+  # The parts of a schedule, for Schedule.new to check. starting is a YYYY-MM-DD String; an
+  # empty except or during list is no clause.
+  ScheduleData = Data.define(:expression, :timezone, :except, :until, :starting, :during) do
+    def initialize(expression:, timezone: nil, except: [], until: nil, starting: 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