philiprehberger-cron_parser 0.1.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32817318714cb93a510d59bfae5592462669488da4ee176d3985d484889f48d7
-  data.tar.gz: ad3ebb67b51c6e6b93a1126779950b5097b04ba6c935d7c8406250c5f5637f4a
+  metadata.gz: d11c034aa656522a0e2ca5e145ca68f974b1b0eb9aeafad15797ee5a53d859f1
+  data.tar.gz: 874e7abb865fa66511d7a407e7e0cc4ea0dfd8e8a637ff75225cffc9db5f0206
 SHA512:
-  metadata.gz: 04572d61d279af7901ad03bc56f041e0e0fc7083323b240639fb8fa4d3646ad340976c22051ed5e84a3d79471c63b8a39a983f245aa44ab276c2f88aeed0db6e
-  data.tar.gz: 61d578083cf566b3add7df47b14203d8c3ef6815128d89fd3cf2a86c1d952702168a085ae175f1b1f1d75d38c509d460bec09852366a6c9ded1ed4cb1c275bd4
+  metadata.gz: c8053224dd61f4defd352fbdf106351f995de7b16b6f10b610a40e99c47f577c0b27d241587aa74cd4299da2d7a4601c6879844eb63d68ce47dfcaa383ce5847
+  data.tar.gz: f830772d6a686fec8dcf8f857a68b4be1f162bf70f0ebde4146f7228b44f5aadc18dbe567ce8570fcd4d5c5fa3125ab2ef56313978cec0320caa5b7796d458b5

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-09
+
+### Added
+- Named cron aliases (`@hourly`, `@daily`, `@midnight`, `@weekly`, `@monthly`, `@yearly`, `@annually`) with case-insensitive matching
+- `valid?` and `validate` now accept alias expressions
+
+## [0.2.0] - 2026-04-03
+
+### Added
+- Named month support (JAN-DEC) in cron expressions
+- Named weekday support (SUN-SAT) in cron expressions
+- `valid?` method for non-raising expression validation
+- `validate` method returning structured field-level errors
+- `description` alias for `human_readable`
+
+## [0.1.5] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
 ## [0.1.4] - 2026-03-31
 
 ### Changed

data/README.md

@@ -56,6 +56,44 @@ cron = Philiprehberger::CronParser.new('30 9 * * 1-5')
 cron.human_readable  # => "at minute 30, at hour 9, on weekday 1,2,3,4,5"
 ```
 
+### Named Months and Weekdays
+
+Use named months (JAN-DEC) and weekdays (SUN-SAT) in cron expressions. Names are case-insensitive and work in ranges and lists.
+
+```ruby
+Philiprehberger::CronParser.new('0 0 1 JAN *')         # first of January
+Philiprehberger::CronParser.new('0 0 1 JAN-MAR *')     # first of Jan-Mar
+Philiprehberger::CronParser.new('0 0 * * MON')         # every Monday
+Philiprehberger::CronParser.new('0 0 * * MON-FRI')     # weekdays
+Philiprehberger::CronParser.new('0 0 * * MON,WED,FRI') # specific days
+Philiprehberger::CronParser.new('0 0 * * 1,WED,5')     # mixed numeric and named
+```
+
+### Named Aliases
+
+Standard crontab aliases are supported (case-insensitive):
+
+```ruby
+Philiprehberger::CronParser.new('@hourly')    # => 0 * * * *
+Philiprehberger::CronParser.new('@daily')     # => 0 0 * * *
+Philiprehberger::CronParser.new('@midnight')  # alias for @daily
+Philiprehberger::CronParser.new('@weekly')    # => 0 0 * * 0
+Philiprehberger::CronParser.new('@monthly')   # => 0 0 1 * *
+Philiprehberger::CronParser.new('@yearly')    # => 0 0 1 1 *
+Philiprehberger::CronParser.new('@annually')  # alias for @yearly
+```
+
+### Validation
+
+```ruby
+Philiprehberger::CronParser.valid?('*/5 * * * *')  # => true
+Philiprehberger::CronParser.valid?('60 * * * *')   # => false
+
+result = Philiprehberger::CronParser.validate('60 25 * * *')
+result[:valid]   # => false
+result[:errors]  # => ["minute field: Value 60 out of range (0-59)", "hour field: Value 25 out of range (0-23)"]
+```
+
 ### Supported Syntax
 
 Standard 5-field cron expressions (minute hour day month weekday):
@@ -66,6 +104,8 @@ Philiprehberger::CronParser.new('*/5 * * * *')     # every 5 minutes
 Philiprehberger::CronParser.new('0 9-17 * * *')    # hourly 9am-5pm
 Philiprehberger::CronParser.new('0 9,12,17 * * *') # specific hours
 Philiprehberger::CronParser.new('0 0 1 * *')       # first of month
+Philiprehberger::CronParser.new('0 0 1 JAN-MAR *') # named months
+Philiprehberger::CronParser.new('0 9 * * MON-FRI') # named weekdays
 ```
 
 ## API
@@ -73,11 +113,14 @@ Philiprehberger::CronParser.new('0 0 1 * *')       # first of month
 | Method | Description |
 |--------|-------------|
 | `CronParser.new(expr)` | Parse a 5-field cron expression |
+| `CronParser.valid?(expr)` | Check if expression is valid (returns boolean) |
+| `CronParser.validate(expr)` | Validate with structured field-level errors |
 | `Expression#next(from:)` | Calculate the next matching time |
 | `Expression#prev(from:)` | Calculate the previous matching time |
 | `Expression#next_n(n, from:)` | Calculate the next N matching times |
 | `Expression#matches?(time)` | Check if a time matches the expression |
 | `Expression#human_readable` | Human-readable description of the expression |
+| `Expression#description` | Alias for `human_readable` |
 
 ## Development
 

data/lib/philiprehberger/cron_parser/expression.rb

@@ -14,8 +14,13 @@ module Philiprehberger
         weekday: { min: 0, max: 6 }
       }.freeze
 
-      WEEKDAY_NAMES = { 'minute' => nil, 'hour' => nil, 'day' => nil, 'month' => nil,
-                        'weekday' => nil }.freeze
+      FIELD_NAMES_MAP = {
+        minute: nil,
+        hour: nil,
+        day: nil,
+        month: Field::MONTH_NAMES,
+        weekday: Field::WEEKDAY_NAMES
+      }.freeze
 
       HUMAN_LABELS = {
         minute: 'minute',
@@ -25,19 +30,33 @@ module Philiprehberger
         weekday: 'day of week'
       }.freeze
 
-      # @return [String] the original expression
+      ALIASES = {
+        '@yearly' => '0 0 1 1 *',
+        '@annually' => '0 0 1 1 *',
+        '@monthly' => '0 0 1 * *',
+        '@weekly' => '0 0 * * 0',
+        '@daily' => '0 0 * * *',
+        '@midnight' => '0 0 * * *',
+        '@hourly' => '0 * * * *'
+      }.freeze
+
+      # @return [String] the original (post-alias expansion) expression
       attr_reader :expression
 
-      # @param expr [String] a 5-field cron expression
+      # @param expr [String] a 5-field cron expression or named alias (e.g. "@daily")
       # @raise [Error] if the expression is invalid
       def initialize(expr)
-        @expression = expr.strip
+        stripped = expr.strip
+        stripped = ALIASES[stripped.downcase] if stripped.start_with?('@')
+        raise Error, "Unknown cron alias: #{expr.strip}" if stripped.nil?
+
+        @expression = stripped
         parts = @expression.split(/\s+/)
         raise Error, "Expected 5 fields, got #{parts.size}: #{@expression}" unless parts.size == 5
 
         @fields = {}
         FIELD_RANGES.each_with_index do |(name, range), index|
-          @fields[name] = Field.new(parts[index], **range)
+          @fields[name] = Field.new(parts[index], min: range[:min], max: range[:max], names: FIELD_NAMES_MAP[name])
         end
       end
 
@@ -100,6 +119,11 @@ module Philiprehberger
         parts.compact.join(', ')
       end
 
+      # Alias for human_readable
+      #
+      # @return [String]
+      alias description human_readable
+
       private
 
       def find_occurrence(from, direction:)

data/lib/philiprehberger/cron_parser/field.rb

@@ -4,16 +4,29 @@ module Philiprehberger
   module CronParser
     # Parses a single cron field (minute, hour, day, month, weekday)
     class Field
+      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
+
+      WEEKDAY_NAMES = {
+        'SUN' => 0, 'MON' => 1, 'TUE' => 2, 'WED' => 3,
+        'THU' => 4, 'FRI' => 5, 'SAT' => 6
+      }.freeze
+
       # @return [Array<Integer>] the expanded set of valid values
       attr_reader :values
 
       # @param expr [String] the field expression (e.g. "*/5", "1,3,5", "1-10")
       # @param min [Integer] the minimum valid value
       # @param max [Integer] the maximum valid value
+      # @param names [Hash, nil] optional name-to-value mapping for this field
       # @raise [Error] if the expression is invalid
-      def initialize(expr, min:, max:)
+      def initialize(expr, min:, max:, names: nil)
         @min = min
         @max = max
+        @names = names
         @values = parse(expr).sort.freeze
       end
 
@@ -35,6 +48,17 @@ module Philiprehberger
         result.uniq
       end
 
+      def resolve_name(token)
+        return token.to_i if token.match?(/\A\d+\z/)
+
+        raise Error, "Invalid cron field expression: #{token}" unless @names
+
+        value = @names[token.upcase]
+        raise Error, "Invalid name '#{token}' for this field" unless value
+
+        value
+      end
+
       def parse_part(part)
         case part
         when '*'
@@ -44,9 +68,9 @@ module Philiprehberger
           raise Error, "Invalid step: #{step}" if step.zero?
 
           (@min..@max).step(step).to_a
-        when %r{\A(\d+)-(\d+)(?:/(\d+))?\z}
-          range_start = Regexp.last_match(1).to_i
-          range_end = Regexp.last_match(2).to_i
+        when %r{\A([a-zA-Z0-9]+)-([a-zA-Z0-9]+)(?:/(\d+))?\z}
+          range_start = resolve_name(Regexp.last_match(1))
+          range_end = resolve_name(Regexp.last_match(2))
           step = Regexp.last_match(3)&.to_i || 1
           validate_range!(range_start, range_end)
           raise Error, "Invalid step: #{step}" if step.zero?
@@ -56,6 +80,10 @@ module Philiprehberger
           value = part.to_i
           validate_value!(value)
           [value]
+        when /\A[a-zA-Z]+\z/
+          value = resolve_name(part)
+          validate_value!(value)
+          [value]
         else
           raise Error, "Invalid cron field expression: #{part}"
         end

data/lib/philiprehberger/cron_parser/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CronParser
-    VERSION = '0.1.4'
+    VERSION = '0.3.0'
   end
 end

data/lib/philiprehberger/cron_parser.rb

@@ -8,6 +8,8 @@ module Philiprehberger
   module CronParser
     class Error < StandardError; end
 
+    FIELD_ORDER = %i[minute hour day month weekday].freeze
+
     # Parse a cron expression and return an Expression instance
     #
     # @param expr [String] a 5-field cron expression (minute hour day month weekday)
@@ -16,5 +18,46 @@ module Philiprehberger
     def self.new(expr)
       Expression.new(expr)
     end
+
+    # Check if a cron expression is valid without raising
+    #
+    # @param expr [String] a 5-field cron expression
+    # @return [Boolean]
+    def self.valid?(expr)
+      Expression.new(expr)
+      true
+    rescue Error
+      false
+    end
+
+    # Validate a cron expression and return structured errors
+    #
+    # @param expr [String] a 5-field cron expression
+    # @return [Hash] { valid: true/false, errors: [String] }
+    def self.validate(expr)
+      errors = []
+      stripped = expr.strip
+      if stripped.start_with?('@')
+        alias_expanded = Expression::ALIASES[stripped.downcase]
+        return { valid: false, errors: ["Unknown cron alias: #{stripped}"] } if alias_expanded.nil?
+
+        stripped = alias_expanded
+      end
+      parts = stripped.split(/\s+/)
+
+      unless parts.size == 5
+        return { valid: false, errors: ["Expected 5 fields, got #{parts.size}"] }
+      end
+
+      FIELD_ORDER.each_with_index do |name, index|
+        range = Expression::FIELD_RANGES[name]
+        names_map = Expression::FIELD_NAMES_MAP[name]
+        Field.new(parts[index], min: range[:min], max: range[:max], names: names_map)
+      rescue Error => e
+        errors << "#{name} field: #{e.message}"
+      end
+
+      { valid: errors.empty?, errors: errors }
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-cron_parser
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-09 00:00:00.000000000 Z
 dependencies: []
 description: Parse standard 5-field cron expressions and calculate next/previous occurrences,
   match times against patterns, and generate human-readable descriptions.
@@ -25,11 +25,11 @@ files:
 - lib/philiprehberger/cron_parser/expression.rb
 - lib/philiprehberger/cron_parser/field.rb
 - lib/philiprehberger/cron_parser/version.rb
-homepage: https://github.com/philiprehberger/rb-cron-parser
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-cron_parser
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-cron-parser
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-cron_parser
   source_code_uri: https://github.com/philiprehberger/rb-cron-parser
   changelog_uri: https://github.com/philiprehberger/rb-cron-parser/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-cron-parser/issues