philiprehberger-cron_parser 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32817318714cb93a510d59bfae5592462669488da4ee176d3985d484889f48d7
-  data.tar.gz: ad3ebb67b51c6e6b93a1126779950b5097b04ba6c935d7c8406250c5f5637f4a
+  metadata.gz: eeb369c781ff5bf8c316b443bf97ee4786ed74e11842f7f5de81a9071418bdb2
+  data.tar.gz: ee7c9d64bae3aee0f9a7b617197e32c6af9816d09ad372c80031d748082f9ab2
 SHA512:
-  metadata.gz: 04572d61d279af7901ad03bc56f041e0e0fc7083323b240639fb8fa4d3646ad340976c22051ed5e84a3d79471c63b8a39a983f245aa44ab276c2f88aeed0db6e
-  data.tar.gz: 61d578083cf566b3add7df47b14203d8c3ef6815128d89fd3cf2a86c1d952702168a085ae175f1b1f1d75d38c509d460bec09852366a6c9ded1ed4cb1c275bd4
+  metadata.gz: c95125f661ce1799d954dc8766c494b784db4fcc7ccd1ad37ca638b4cd3a6a807560fa9640868d2a9eb91e89e8323604868a3f27fecf797324571f7d6d341b48
+  data.tar.gz: c1464aa92d9df184418b6e211864f2ea30c7444822c955c5772482e2c7e24d10c5dc395de909c4baf7e17436cee4aba87c20a7ff72fd3241ab3c5049a3781ba2

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,30 @@ 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
+```
+
+### 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 +90,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 +99,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',
@@ -37,7 +42,7 @@ module Philiprehberger
 
         @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 +105,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.2.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,40 @@ 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
+      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.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-03 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