philiprehberger-cron_parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0fcde713c9e0d9e084402949a564bca9cf764b9fb1e60d7a1d065dd50a46662
+  data.tar.gz: 4c15cf6a91d629c565437079e02bb92ff1d7a33218ea042e770e759c5a7a1ef7
+SHA512:
+  metadata.gz: be56c15d393e12a8ffedccd297b696214400f871901559e3f38ae2a5c8356a0a136e5a3746db13890f06eef3b811ef9342ad37a827ce6127e75fb8ff25eedcd4
+  data.tar.gz: 68e86137912eebb04792836c6501a72e578628fdda9b48e5c8312f7ffd33d0af1c32dc2ab1634059d140b381f02129ae2a0f78e9f775036ec8414c392f3408b9

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Standard 5-field cron expression parsing (minute hour day month weekday)
+- Next and previous occurrence calculation
+- Batch next-N occurrence lookup
+- Time matching against cron patterns
+- Human-readable cron description output
+- Support for wildcards, ranges, steps, and lists

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# philiprehberger-cron_parser
+
+[![Tests](https://github.com/philiprehberger/rb-cron-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-cron-parser/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-cron_parser.svg)](https://rubygems.org/gems/philiprehberger-cron_parser)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-cron-parser)](LICENSE)
+
+Cron expression parser for calculating next and previous occurrences
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-cron_parser"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-cron_parser
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/cron_parser"
+
+cron = Philiprehberger::CronParser.new('0 9 * * 1-5')
+cron.next(from: Time.now)   # => next weekday at 9:00 AM
+cron.prev(from: Time.now)   # => previous weekday at 9:00 AM
+```
+
+### Next Occurrences
+
+```ruby
+cron = Philiprehberger::CronParser.new('*/15 * * * *')
+cron.next_n(5, from: Time.now)  # => next 5 quarter-hour times
+```
+
+### Matching
+
+```ruby
+cron = Philiprehberger::CronParser.new('0 9 * * *')
+cron.matches?(Time.new(2026, 3, 22, 9, 0, 0))  # => true
+cron.matches?(Time.new(2026, 3, 22, 10, 0, 0)) # => false
+```
+
+### Human-Readable Description
+
+```ruby
+cron = Philiprehberger::CronParser.new('30 9 * * 1-5')
+cron.human_readable  # => "at minute 30, at hour 9, on weekday 1,2,3,4,5"
+```
+
+### Supported Syntax
+
+Standard 5-field cron expressions (minute hour day month weekday):
+
+```ruby
+Philiprehberger::CronParser.new('* * * * *')       # every minute
+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
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `CronParser.new(expr)` | Parse a 5-field cron expression |
+| `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 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/cron_parser/expression.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative 'field'
+
+module Philiprehberger
+  module CronParser
+    # Represents a parsed 5-field cron expression
+    class Expression
+      FIELD_RANGES = {
+        minute: { min: 0, max: 59 },
+        hour: { min: 0, max: 23 },
+        day: { min: 1, max: 31 },
+        month: { min: 1, max: 12 },
+        weekday: { min: 0, max: 6 }
+      }.freeze
+
+      WEEKDAY_NAMES = { 'minute' => nil, 'hour' => nil, 'day' => nil, 'month' => nil,
+                        'weekday' => nil }.freeze
+
+      HUMAN_LABELS = {
+        minute: 'minute',
+        hour: 'hour',
+        day: 'day of month',
+        month: 'month',
+        weekday: 'day of week'
+      }.freeze
+
+      # @return [String] the original expression
+      attr_reader :expression
+
+      # @param expr [String] a 5-field cron expression
+      # @raise [Error] if the expression is invalid
+      def initialize(expr)
+        @expression = expr.strip
+        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)
+        end
+      end
+
+      # Check if a given time matches this cron expression
+      #
+      # @param time [Time] the time to check
+      # @return [Boolean]
+      def matches?(time)
+        @fields[:minute].matches?(time.min) &&
+          @fields[:hour].matches?(time.hour) &&
+          @fields[:day].matches?(time.day) &&
+          @fields[:month].matches?(time.month) &&
+          @fields[:weekday].matches?(time.wday)
+      end
+
+      # Calculate the next occurrence after the given time
+      #
+      # @param from [Time] the starting time
+      # @return [Time] the next matching time
+      # @raise [Error] if no match found within 4 years
+      def next(from: Time.now)
+        find_occurrence(from, direction: :forward)
+      end
+
+      # Calculate the previous occurrence before the given time
+      #
+      # @param from [Time] the starting time
+      # @return [Time] the previous matching time
+      # @raise [Error] if no match found within 4 years
+      def prev(from: Time.now)
+        find_occurrence(from, direction: :backward)
+      end
+
+      # Calculate the next N occurrences after the given time
+      #
+      # @param count [Integer] the number of occurrences to find
+      # @param from [Time] the starting time
+      # @return [Array<Time>] the next N matching times
+      def next_n(count, from: Time.now)
+        results = []
+        current = from
+        count.times do
+          current = self.next(from: current)
+          results << current
+          current += 60
+        end
+        results
+      end
+
+      # Return a human-readable description of the expression
+      #
+      # @return [String]
+      def human_readable
+        parts = []
+        parts << minute_description
+        parts << hour_description
+        parts << day_description
+        parts << month_description
+        parts << weekday_description
+        parts.compact.join(', ')
+      end
+
+      private
+
+      def find_occurrence(from, direction:)
+        step = direction == :forward ? 60 : -60
+        current = round_to_minute(from) + step
+        limit = 4 * 365 * 24 * 60 # 4 years in minutes
+
+        limit.times do
+          return current if matches?(current)
+
+          current += step
+        end
+
+        raise Error, "No matching time found within 4 years"
+      end
+
+      def round_to_minute(time)
+        Time.new(time.year, time.month, time.day, time.hour, time.min, 0, time.utc_offset)
+      end
+
+      def minute_description
+        describe_field(:minute, 'every minute', 'at minute')
+      end
+
+      def hour_description
+        describe_field(:hour, nil, 'at hour')
+      end
+
+      def day_description
+        describe_field(:day, nil, 'on day')
+      end
+
+      def month_description
+        describe_field(:month, nil, 'in month')
+      end
+
+      def weekday_description
+        describe_field(:weekday, nil, 'on weekday')
+      end
+
+      def describe_field(name, wildcard_text, prefix)
+        field = @fields[name]
+        range = FIELD_RANGES[name]
+        all_values = (range[:min]..range[:max]).to_a
+
+        if field.values == all_values
+          wildcard_text
+        else
+          "#{prefix} #{field.values.join(',')}"
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/cron_parser/field.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CronParser
+    # Parses a single cron field (minute, hour, day, month, weekday)
+    class Field
+      # @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
+      # @raise [Error] if the expression is invalid
+      def initialize(expr, min:, max:)
+        @min = min
+        @max = max
+        @values = parse(expr).sort.freeze
+      end
+
+      # Check if a value matches this field
+      #
+      # @param value [Integer] the value to check
+      # @return [Boolean]
+      def matches?(value)
+        @values.include?(value)
+      end
+
+      private
+
+      def parse(expr)
+        result = []
+        expr.split(',').each do |part|
+          result.concat(parse_part(part.strip))
+        end
+        result.uniq
+      end
+
+      def parse_part(part)
+        case part
+        when '*'
+          (@min..@max).to_a
+        when /\A\*\/(\d+)\z/
+          step = Regexp.last_match(1).to_i
+          raise Error, "Invalid step: #{step}" if step.zero?
+
+          (@min..@max).step(step).to_a
+        when /\A(\d+)-(\d+)(?:\/(\d+))?\z/
+          range_start = Regexp.last_match(1).to_i
+          range_end = Regexp.last_match(2).to_i
+          step = Regexp.last_match(3)&.to_i || 1
+          validate_range!(range_start, range_end)
+          raise Error, "Invalid step: #{step}" if step.zero?
+
+          (range_start..range_end).step(step).to_a
+        when /\A\d+\z/
+          value = part.to_i
+          validate_value!(value)
+          [value]
+        else
+          raise Error, "Invalid cron field expression: #{part}"
+        end
+      end
+
+      def validate_range!(range_start, range_end)
+        validate_value!(range_start)
+        validate_value!(range_end)
+        raise Error, "Invalid range: #{range_start}-#{range_end}" if range_start > range_end
+      end
+
+      def validate_value!(value)
+        return if value >= @min && value <= @max
+
+        raise Error, "Value #{value} out of range (#{@min}-#{@max})"
+      end
+    end
+  end
+end

data/lib/philiprehberger/cron_parser/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CronParser
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/cron_parser.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'cron_parser/version'
+require_relative 'cron_parser/field'
+require_relative 'cron_parser/expression'
+
+module Philiprehberger
+  module CronParser
+    class Error < StandardError; end
+
+    # Parse a cron expression and return an Expression instance
+    #
+    # @param expr [String] a 5-field cron expression (minute hour day month weekday)
+    # @return [Expression] the parsed expression
+    # @raise [Error] if the expression is invalid
+    def self.new(expr)
+      Expression.new(expr)
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-cron_parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 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.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/cron_parser.rb
+- 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
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-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
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Cron expression parser for calculating next and previous occurrences
+test_files: []