philiprehberger-cron_kit 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1977410207f5f4175dbc118475df47ab7de96efdf3e04a5bb51f5f7e58eb3999
-  data.tar.gz: 3ff3ab0609f47dcadf8b6af55d7ddc60439e0691eed2d52874a994c5a139d6e0
+  metadata.gz: f5662dedc928394f24b8af5ab47de3d35b4a9847f5c49bc5b10795317048b791
+  data.tar.gz: cf11c8cc20f88143e0b55f22f4f2aa8e35384b7ad558ce08eed1033265621bef
 SHA512:
-  metadata.gz: 804c1abd96ae6ec6d9ef5905a6d6e0fe040f28658e27348f89158a0aa82358c27f67cc0388ce4b475a3c74986e8ebd7f7f5bb854a9369cf8b416122ede96d34f
-  data.tar.gz: ca197108c82de369eeae3e64c6115649957de51634d3fa299a6db88c447b510467cd71d9009ced8d35120c2a80b00690643f0ed93c0dc9dda3e00b581be84305
+  metadata.gz: 1a0c427360b5546e8e732d4bf20097f8ec8c0265b3a026758282b0c069ea196bb9f7d229dd305e222c248aac60bc9df9e0872d6c069ed95b05fc7d8afec3ec47
+  data.tar.gz: 5629f8e7aed24666f3e4b657d6760a6ce1e06ca457f6f4fa1ab146554bb45d17ff64c09f9f49beae50ca0c733f5328ed59b4561390db0fc736a8d07a46c218c0

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-07-15
+
+### Added
+- Named month tokens (`JAN`–`DEC`) and weekday tokens (`SUN`–`SAT`) in the month and day-of-week fields, case-insensitive, in single values, lists, and ranges (e.g. `MON-FRI`, `JAN,JUN,DEC`)
+- `7` accepted as an alias for Sunday in the day-of-week field (Vixie/crontab interop)
+
+### Fixed
+- Day-of-month / day-of-week now follow standard (Vixie) cron OR-semantics: when both fields are restricted, a time matches when either matches (e.g. `0 0 13 * 5` fires on the 13th or any Friday); previously the fields were ANDed, causing under-firing. Applies to `#match?`, `#next_at`, `#next_runs`, and `#previous_run`
+
+## [0.8.1] - 2026-06-14
+
+### Changed
+- Added package card image to README
+- Added YARD doc comments to Scheduler public methods
+- Made job-name examples consistent in README
+
+### Fixed
+- Replaced bare RuntimeError raises in Expression parser with Error class
+- Scheduler#every now validates a block is provided at registration time
+
 ## [0.8.0] - 2026-05-13
 
 ### Added
@@ -154,7 +174,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Philiprehberger::CronKit.parse` convenience method
 - `Philiprehberger::CronKit.new` convenience method for creating a Scheduler
 
-[Unreleased]: https://github.com/philiprehberger/rb-cron-kit/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/philiprehberger/rb-cron-kit/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/philiprehberger/rb-cron-kit/compare/v0.8.1...v0.9.0
+[0.8.1]: https://github.com/philiprehberger/rb-cron-kit/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/philiprehberger/rb-cron-kit/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/philiprehberger/rb-cron-kit/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/philiprehberger/rb-cron-kit/compare/v0.5.1...v0.6.0

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-cron_kit.svg)](https://rubygems.org/gems/philiprehberger-cron_kit)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-cron-kit)](https://github.com/philiprehberger/rb-cron-kit/commits/main)
 
+![philiprehberger-cron_kit](https://raw.githubusercontent.com/philiprehberger/rb-cron-kit/main/package-card.webp)
+
 Cron expression parser and scheduler
 
 ## Requirements
@@ -183,14 +185,14 @@ scheduler.running_jobs # => 2
 ```ruby
 scheduler = Philiprehberger::CronKit.new
 
-scheduler.every("0 9 * * 1-5", name: "morning-report") do
+scheduler.every("0 9 * * 1-5", name: "morning_report") do
   generate_report
 end
 
-scheduler.job_names     # => ["morning-report"]
-scheduler.job?("morning-report")   # => true
-scheduler.job?("does-not-exist")   # => false
-scheduler.remove("morning-report")
+scheduler.job_names     # => ["morning_report"]
+scheduler.job?("morning_report")   # => true
+scheduler.job?("does_not_exist")   # => false
+scheduler.remove("morning_report")
 ```
 
 ### Manual Trigger
@@ -199,12 +201,12 @@ Trigger a registered job by name without restarting the scheduler — useful for
 or operator-driven re-runs.
 
 ```ruby
-scheduler.every("0 9 * * 1-5", name: :morning_report, timeout: 30) do
+scheduler.every("0 9 * * 1-5", name: "morning_report", timeout: 30) do
   generate_report
 end
 
-scheduler.run_now(:morning_report)  # => return value of the block
-scheduler.run_now(:missing)          # raises KeyError
+scheduler.run_now("morning_report")  # => return value of the block
+scheduler.run_now("missing")          # raises KeyError
 ```
 
 `run_now` honors `timeout:` (raises `Timeout::Error`) and respects `overlap: false`
@@ -214,7 +216,28 @@ scheduler.run_now(:missing)          # raises KeyError
 
 ```ruby
 scheduler.next_runs(from: Time.now)
-# => { "morning-report" => 2026-03-13 09:00:00 ... }
+# => { "morning_report" => 2026-03-13 09:00:00 ... }
+```
+
+### Named Tokens and Sunday Interop
+
+Three-letter month names (`JAN`–`DEC`) and weekday names (`SUN`–`SAT`) are accepted in the month and day-of-week fields, case-insensitive, in single values, lists, and ranges. In the day-of-week field, `7` is also accepted as an alias for Sunday (`0`), matching Vixie/crontab.
+
+```ruby
+Philiprehberger::CronKit.parse("0 9 * * MON-FRI")    # weekdays at 09:00
+Philiprehberger::CronKit.parse("0 0 1 JAN,JUN,DEC *") # 1st of Jan, Jun, Dec
+Philiprehberger::CronKit.parse("* * * * 7")           # every minute on Sunday (7 == 0)
+```
+
+### Day-of-Month / Day-of-Week Matching
+
+Following standard (Vixie) cron, when **both** the day-of-month and day-of-week fields are restricted (neither is `*`), a time matches when **either** field matches. When only one is restricted, only that field must match; when both are `*`, the day is unconstrained.
+
+```ruby
+# Fires on the 13th OR any Friday
+expr = Philiprehberger::CronKit.parse("0 0 13 * 5")
+expr.match?(Time.new(2026, 3, 6))  # => true  (Friday, not the 13th)
+expr.match?(Time.new(2026, 4, 13)) # => true  (13th, not a Friday)
 ```
 
 ### Supported Syntax
@@ -226,6 +249,7 @@ scheduler.next_runs(from: Time.now)
 | Range   | `1-5`      | Values from 1 through 5   |
 | Step    | `*/5`      | Every 5th value           |
 | List    | `1,3,5`   | Values 1, 3, and 5        |
+| Name    | `MON-FRI`  | Month/weekday names       |
 | Alias   | `@daily`   | Non-standard shorthand    |
 
 ### Fields
@@ -235,8 +259,8 @@ scheduler.next_runs(from: Time.now)
 | 1        | Minute        | 0-59   |
 | 2        | Hour          | 0-23   |
 | 3        | Day of month  | 1-31   |
-| 4        | Month         | 1-12   |
-| 5        | Day of week   | 0-6    |
+| 4        | Month         | 1-12 (or `JAN`-`DEC`) |
+| 5        | Day of week   | 0-6 (or `SUN`-`SAT`; `7` = Sunday) |
 
 ## API
 

data/lib/philiprehberger/cron_kit/expression.rb

@@ -30,12 +30,14 @@ module Philiprehberger
         @timezone = timezone
         @utc_offset = Timezone.utc_offset_for(timezone)
         @fields = parse_expression(@raw)
+        parts = @raw.split(/\s+/)
+        @dom_restricted = parts[2] != '*'
+        @dow_restricted = parts[4] != '*'
       end
 
       def match?(time)
         time = coerce_time(time)
-        values = [time.min, time.hour, time.day, time.month, time.wday]
-        @fields.each_with_index.all? { |set, i| set.include?(values[i]) }
+        values_match?([time.min, time.hour, time.day, time.month, time.wday])
       end
 
       # Return true if any Time in the given enumerable matches the expression.
@@ -95,7 +97,7 @@ module Philiprehberger
 
           time += 60
         end
-        raise 'no matching time found within 4 years'
+        raise Error, 'no matching time found within 4 years'
       end
 
       def scan_backward(time)
@@ -104,12 +106,36 @@ module Philiprehberger
 
           time -= 60
         end
-        raise 'no matching time found within 4 years'
+        raise Error, 'no matching time found within 4 years'
       end
 
       def field_match?(time)
-        values = [time.min, time.hour, time.day, time.month, time.wday]
-        @fields.each_with_index.all? { |set, i| set.include?(values[i]) }
+        values_match?([time.min, time.hour, time.day, time.month, time.wday])
+      end
+
+      # Minute, hour, and month must always match. Standard (Vixie) cron ORs the
+      # day-of-month and day-of-week fields when both are restricted, so
+      # `0 0 13 * 5` fires on the 13th OR any Friday.
+      def values_match?(values)
+        return false unless @fields[0].include?(values[0]) # minute
+        return false unless @fields[1].include?(values[1]) # hour
+        return false unless @fields[3].include?(values[3]) # month
+
+        day_of_week_match?(values[2], values[4])
+      end
+
+      def day_of_week_match?(day, wday)
+        dom = @fields[2].include?(day)
+        dow = @fields[4].include?(wday)
+        if @dom_restricted && @dow_restricted
+          dom || dow
+        elsif @dom_restricted
+          dom
+        elsif @dow_restricted
+          dow
+        else
+          true
+        end
       end
     end
   end

data/lib/philiprehberger/cron_kit/parser.rb

@@ -15,6 +15,20 @@ module Philiprehberger
 
       FIELD_NAMES = %w[minute hour day-of-month month day-of-week].freeze
 
+      # Three-letter month names (case-insensitive) mapped to their numeric value.
+      MONTH_NAMES = {
+        '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
+
+      # Three-letter weekday names (case-insensitive) mapped to their numeric value.
+      DAY_NAMES = {
+        'SUN' => 0, 'MON' => 1, 'TUE' => 2, 'WED' => 3, 'THU' => 4, 'FRI' => 5, 'SAT' => 6
+      }.freeze
+
+      # Sunday may be written as 7 in the day-of-week field (Vixie cron interop).
+      DOW_SUNDAY_ALIAS = 7
+
       def parse_expression(expression)
         parts = expression.split(/\s+/)
 
@@ -28,12 +42,42 @@ module Philiprehberger
       private
 
       def parse_field(field, range, name)
-        values = field.split(',').flat_map { |token| parse_token(token, range, name) }
+        normalized = normalize_names(field, name)
+        parse_range = parse_range_for(name, range)
+        values = normalized.split(',').flat_map { |token| parse_token(token, parse_range, name) }
         raise ParseError, "empty field for #{name}" if values.empty?
 
+        values = values.map { |value| value == DOW_SUNDAY_ALIAS ? 0 : value } if name == 'day-of-week'
         values.uniq.sort
       end
 
+      # Replace three-letter month/weekday names (case-insensitive) with their
+      # numeric value before numeric parsing. Names are supported in single
+      # values, lists, and ranges (e.g. MON-FRI, JAN,JUN,DEC).
+      def normalize_names(field, name)
+        table = name_table_for(name)
+        return field unless table
+
+        field.gsub(/[A-Za-z]+/) do |word|
+          table.fetch(word.upcase) do
+            raise ParseError, "invalid name #{word.inspect} in #{name} field"
+          end
+        end
+      end
+
+      def name_table_for(name)
+        case name
+        when 'month' then MONTH_NAMES
+        when 'day-of-week' then DAY_NAMES
+        end
+      end
+
+      # The day-of-week field accepts 7 as an alias for Sunday, so parsing must
+      # tolerate 7 (mapped to 0 afterwards) even though the field range is 0..6.
+      def parse_range_for(name, range)
+        name == 'day-of-week' ? (range.min..DOW_SUNDAY_ALIAS) : range
+      end
+
       def parse_token(token, range, name)
         try_wildcard(token, range) ||
           try_step(token, range, name) ||

data/lib/philiprehberger/cron_kit/scheduler.rb

@@ -18,17 +18,43 @@ module Philiprehberger
         @job_threads = {}
       end
 
+      # Register a callback invoked when a job raises an error.
+      #
+      # Called with the failing +Job+ and the +StandardError+ raised. With no
+      # block, returns the currently registered callback (or +nil+).
+      #
+      # @yieldparam job [Job] the job that failed
+      # @yieldparam error [StandardError] the error raised by the job's block
+      # @return [Proc, nil] the registered callback when called without a block
       def on_error(&block)
         return @on_error unless block
 
         @on_error = block
       end
 
+      # Number of currently executing job threads.
+      #
+      # @return [Integer] count of live job threads
       def running_jobs
         @mutex.synchronize { @running_threads.count(&:alive?) }
       end
 
+      # Register a cron job to be executed when +expression+ matches.
+      #
+      # Accepts either a cron expression string or a pre-built +Expression+.
+      # Raises +ArgumentError+ immediately if no block is provided, surfacing
+      # configuration mistakes at registration time rather than at tick time.
+      #
+      # @param expression [String, Expression] cron expression or pre-built Expression
+      # @param name [Symbol, String, nil] optional job name for lookup/removal/triggering
+      # @param timeout [Numeric, nil] kill the job if it exceeds this many seconds
+      # @param overlap [Boolean] when +false+, skip the tick if a previous run is still active
+      # @yieldparam time [Time] the tick time the job fires at
+      # @return [self]
+      # @raise [ArgumentError] if no block is provided
       def every(expression, name: nil, timeout: nil, overlap: true, &block)
+        raise ArgumentError, 'block required' unless block
+
         expr = expression.is_a?(Expression) ? expression : Expression.new(expression)
 
         @mutex.synchronize do
@@ -38,6 +64,11 @@ module Philiprehberger
         self
       end
 
+      # Names of all registered named jobs.
+      #
+      # Anonymous jobs (registered without +name:+) are omitted.
+      #
+      # @return [Array<Symbol, String>] list of registered job names
       def job_names
         @mutex.synchronize { @jobs.map(&:name).compact }
       end
@@ -54,6 +85,10 @@ module Philiprehberger
         @mutex.synchronize { @jobs.any? { |j| j.name == name } }
       end
 
+      # Remove a registered job by name.
+      #
+      # @param name [Symbol, String] the job name to remove
+      # @return [Boolean] +true+ if a matching job was removed, +false+ otherwise
       def remove(name)
         @mutex.synchronize do
           initial_size = @jobs.size
@@ -80,6 +115,12 @@ module Philiprehberger
         execute_now(job)
       end
 
+      # Upcoming run times for every named job.
+      #
+      # Anonymous jobs are omitted.
+      #
+      # @param from [Time] starting point for the lookahead (defaults to +Time.now+)
+      # @return [Hash{Symbol, String => Time}] map of job name to the next matching time
       def next_runs(from: Time.now)
         jobs = @mutex.synchronize { @jobs.dup }
 
@@ -90,6 +131,11 @@ module Philiprehberger
         end
       end
 
+      # Start the scheduler loop in a background thread.
+      #
+      # Idempotent — calling +start+ on an already-running scheduler is a no-op.
+      #
+      # @return [self]
       def start
         @mutex.synchronize do
           return self if @running
@@ -103,6 +149,9 @@ module Philiprehberger
         self
       end
 
+      # Stop the scheduler loop and wait briefly for the background thread to exit.
+      #
+      # @return [self]
       def stop
         @mutex.synchronize { @running = false }
         @thread&.join(5)
@@ -111,6 +160,9 @@ module Philiprehberger
         self
       end
 
+      # Whether the scheduler loop is currently running.
+      #
+      # @return [Boolean]
       def running?
         @mutex.synchronize { @running }
       end

data/lib/philiprehberger/cron_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CronKit
-    VERSION = '0.8.0'
+    VERSION = '0.9.0'
   end
 end

data/lib/philiprehberger/cron_kit.rb

@@ -10,6 +10,8 @@ require_relative 'cron_kit/scheduler'
 
 module Philiprehberger
   module CronKit
+    class Error < StandardError; end
+
     # Parse a 5-field cron expression and return an Expression instance.
     # Supports non-standard aliases (@hourly, @daily, etc.) and optional timezone.
     def self.parse(expression, timezone: nil)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-cron_kit
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-07-16 00:00:00.000000000 Z
 dependencies: []
 description: A zero-dependency Ruby gem for parsing 5-field cron expressions and running
   an in-process scheduler. Supports wildcards, ranges, steps, and lists.