cron-parser 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MmU1MjNiNWI4Mzc3MjQ0NjZmNGEyODljM2QzMDkyZWExY2M4NDYxNA==
+  data.tar.gz: !binary |-
+    YmUzOGY2MzkwYjYxMWVlM2FjMGVmNjMxNDU5NjNhZDlhMjc0YmViYg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ODQxOWMwNDdlOTQxNTM5OWQyNTBkODE0ZjRlZTliNmE1MDJmNzRhYzVkMDYz
+    MGVkYWU1MjU2MTk5MjFkODk3ZDk4N2E0OTlhY2Q3OTZiYzdlYjcxOTBjNWE4
+    MDY1MWNlZDA0YTQxNjJjNjZjMjY4ZjIyZTBhZjYzYzljZDgyNjI=
+  data.tar.gz: !binary |-
+    ZjcyZjVmN2ZmZmE3MjA4MzMxNzEwMGJiODI1Yjc4ODVkMmM3N2MyNzg3YTk4
+    NTM5YjU3MTcyNWZlODlkOGQ3MDM4ZjU4OGUyMDNjNTMwY2M4OTljNzEzOWMy
+    YWI3NmExMTk2ZTI1MmQxNDM0NWNjZTllY2E2MmM1MWZhM2VhYWU=

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+Gemfile.lock
+*.bk
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,8 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - jruby-19mode
+  - rbx-19mode
+notifications:
+  recipients:
+    - the@vishaltelangre.com

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+### 0.1.1 (Next Release)
+
+* Your contribution here.
+
+### 0.1.0 (10/20/2013)
+
+* Initial public release - [@vishaltelangre](https://github.com/vishaltelangre).

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2013 Vishal Telangre.
+
+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,125 @@
+Cron::Parser
+============
+
+[![Gem Version](https://badge.fury.io/rb/cron-parser.png)](http://badge.fury.io/rb/cron-parser)
+[![Build Status](https://travis-ci.org/vishaltelangre/cron-parser.png?branch=master)](https://travis-ci.org/vishaltelangre/cron-parser)
+
+Dissect your Cron pattern!
+
+## Installation
+
+Install gem by using following command:
+
+    gem install cron-parser
+
+or add it to your Gemfile as:
+
+```ruby
+gem 'cron-parser', require: 'cron'
+```
+
+## Usage
+
+Well, using `Cron::Parser` is really easy, take a look at following example:
+
+```ruby
+require 'cron'
+
+# so you have got a pattern, which you want to dissect:
+dirty_cron_pattern = "38,37/40,39 */6,01,2 21-30/3,30,31 * MON,2-4"
+
+# ask `Cron::Parser` to dissect it, and it will do that nasty job for you:
+
+>> parsed_pattern = Cron::Parser.new(dirty_cron_pattern)
+# => #<Cron::Parser:0x973860c> { :pattern => "38,37/40,39 */6,01,2 21-30/3,30,31 * MON,2-4", :fields => {:minute=>#<Cron::Parser::MinuteField:0x9736ab4> { :pattern => "38,37/40,39", :warning => '37/40' is valid but confusing pattern, :meaning => "at 37th, 38th minute" }, :hour=>#<Cron::Parser::HourField:0x9743bd8> { :pattern => "*/6,01,2", :meaning => "on 12am, 1am, 2am, 6am, 12pm, 6pm" }, :day_of_month=>#<Cron::Parser::DayOfMonthField:0x9537768> { :pattern => "21-30/3,30,31", :meaning => "on days: 21st, 24th, 27th, 30th, 30th, 31st" }, :month=>#<Cron::Parser::MonthField:0x9586110> { :pattern => "*", :meaning => "every month" }, :day_of_week=>#<Cron::Parser::DayOfWeekField:0x958f224> { :pattern => "MON,2-4", :meaning => "on Tuesday, Wednsday, Thursday, Monday" }} }
+
+# you can do it other way too, if you like:
+
+>> Cron::Parser.parse(dirty_cron_pattern)
+# => "at 37th, 38th minute; on 12am, 1am, 2am, 6am, 12pm, 6pm; on days: 21st, 24th, 27th, 30th, 30th, 31st; every month; on Tuesday, Wednsday, Thursday, Monday"
+
+# this is same as below:
+
+>> parsed_pattern.meaning
+# => "at 37th, 38th minute; on 12am, 1am, 2am, 6am, 12pm, 6pm; on days: 21st, 24th, 27th, 30th, 30th, 31st; every month; on Tuesday, Wednsday, Thursday, Monday"
+
+# also, `parsed_pattern.humanize` produces the same result as above.
+
+# further exploration methods you can use:
+
+>> parsed_pattern.fields
+# => {:minute=>#<Cron::Parser::MinuteField:0x9736ab4> { :pattern => "38,37/40,39", :warning => '37/40' is valid but confusing pattern, :meaning => "at 37th, 38th minute" }, :hour=>#<Cron::Parser::HourField:0x9743bd8> { :pattern => "*/6,01,2", :meaning => "on 12am, 1am, 2am, 6am, 12pm, 6pm" }, :day_of_month=>#<Cron::Parser::DayOfMonthField:0x9537768> { :pattern => "21-30/3,30,31", :meaning => "on days: 21st, 24th, 27th, 30th, 30th, 31st" }, :month=>#<Cron::Parser::MonthField:0x9586110> { :pattern => "*", :meaning => "every month" }, :day_of_week=>#<Cron::Parser::DayOfWeekField:0x958f224> { :pattern => "MON,2-4", :meaning => "on Tuesday, Wednsday, Thursday, Monday" }}
+
+>> parsed_pattern.minute_field
+# => #<Cron::Parser::MinuteField:0x9736ab4> { :pattern => "38,37/40,39", :warning => '37/40' is valid but confusing pattern, :meaning => "at 37th, 38th minute" }
+
+# similarly, see: `parsed_pattern.hour_field`, `parsed_pattern.day_of_month_field`, `parsed_pattern.month_field`, `parsed_pattern.day_of_week_field`
+
+>> parsed_pattern.minute_field.pattern
+# => "38,37/40,39"
+
+>> parsed_pattern.minute_field.meaning
+# => "at 37th, 38th minute"
+
+>> parsed_pattern.minute_field.warning
+# => "'37/40' is valid but confusing pattern"
+
+>> parsed_pattern.warnings
+# => ["for 'minute' field: '37/40' is valid but confusing pattern"]
+```
+
+What about wrong or invalid patterns, huh?
+
+```ruby
+>> Cron::Parser.new(1)
+# raises InvalidCronPatternError: cron pattern must be a string
+
+>> Cron::Parser.new("* * *")
+# raises InvalidCronPatternError: cron pattern must contain exact 5 fields seperated by whitespaces
+
+>> Cron::Parser.new("* * * * 1-10")
+# raises InvalidDayOfWeekFieldError: value: '10' not allowed for 'day_of_week' field, run: 'Cron::Parser::DayOfWeekField.allowed_values' to know valid values
+
+>> Cron::Parser::DayOfWeekField.allowed_values
+# => ["0", "1", "2", "3", "4", "5", "6", "7", "00", "01", "02", "03", "04", "05", "06", "07", "SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
+
+>> Cron::Parser::DayOfWeekField.allowed_special_characters
+# => ["*", "/", ",", "-"]
+```
+
+## Important Notes
+* This parser is based upon the specifications of `crontab(5)`.
+* Following are the pattern fields, and respective allowed values:
+
+    *    *    *    *    *
+    ┬    ┬    ┬    ┬    ┬
+    │    │    │    │    │
+    │    │    │    │    │
+    │    │    │    │    └───── day_of_week (0-7) (0 or 7 is Sun, or use 3-letter names)
+    │    │    │    └────────── month (1-12, or use 3-letter names)
+    │    │    └─────────────── day_of_month (1-31)
+    │    └──────────────────── hour (0-23)
+    └───────────────────────── minute (0-59)
+
+* When specifying day of week, both day 0 and day 7 will be considered Sunday.
+* Ranges & Lists of numbers are allowed.
+* Ranges or lists of names are not allowed.
+* Ranges can include 'steps', so `1-9/2` is the same as `1,3,5,7,9`.
+* Months or days of the week can be specified by name.
+* Use the first three letters of the particular day or month (case doesn't matter).
+
+## Contributing
+
+You're encouraged to contribute to this gem.
+
+* Fork this project.
+* Make changes, write tests (run `rake` to check existing test coverage).
+* Report bugs, comment on and close open issues.
+* Update [CHANGELOG](CHANGELOG.md).
+* Make a pull request, bonus points for topic branches.
+
+## Copyright and License
+
+Copyright (c) 2013, Vishal Telangre and [Contributors](CHANGELOG.md). All Rights Reserved.
+
+This project is licenced under the [MIT License](LICENSE.md).

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'bundler/gem_tasks'
+
+Bundler.setup(:default, :development)
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList["spec/**/*_spec.rb"]
+end
+
+task :default => :spec

data/cron-parser.gemspec

@@ -0,0 +1,23 @@
+$:.push File.expand_path("../lib", __FILE__)
+$:.push File.expand_path("../lib/extras", __FILE__)
+$:.push File.expand_path("../lib/cron", __FILE__)
+$:.push File.expand_path("../lib/cron/parser", __FILE__)
+
+require "cron/parser/version"
+
+Gem::Specification.new do |s|
+  s.name = "cron-parser"
+  s.version = Cron::Parser::VERSION
+  s.authors = [ "Vishal Telangre" ]
+  s.email = "the@vishaltelangre.com"
+  s.platform = Gem::Platform::RUBY
+  s.required_rubygems_version = '>= 1.3.6'
+  s.files = `git ls-files`.split("\n")
+  s.require_paths = [ "lib", "lib/extras", "lib/cron", "lib/cron/parser" ]
+  s.homepage = "http://github.com/vishaltelangre/cron-parser"
+  s.licenses = [ "MIT" ]
+  s.summary = "Dissect your Cron patterns!"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rspec"
+  s.add_dependency "activesupport"
+end

data/lib/cron.rb

@@ -0,0 +1,12 @@
+require          "active_support/inflector"
+require_relative "extras/custom_errors"
+require_relative "extras/extensions"
+require_relative "cron/parser"
+require_relative "cron/parser/field"
+require_relative "cron/parser/minute_field"
+require_relative "cron/parser/hour_field"
+require_relative "cron/parser/day_of_month_field"
+require_relative "cron/parser/month_field"
+require_relative "cron/parser/day_of_week_field"
+
+class Cron; end

data/lib/cron/parser.rb

@@ -0,0 +1,102 @@
+class Cron
+  class Parser
+    attr_reader :pattern,
+                :fields,
+                :meaning, # umm, let me think about it
+                :warnings
+
+    FIELDS = %w{ minute hour day_of_month month day_of_week }
+
+    def initialize(pattern = nil)
+      @pattern = pattern
+      @fields  = {}; FIELDS.map { |field| @fields[field.to_sym] = nil }
+      validate! # and don't ask to dissect it!
+      @meaning = humanize # being human, wtf!
+    end
+
+    # Inspects the parsed pattern, displays fields in pattern along with their
+    # meanings.
+    def inspect
+      %Q{
+          #<#{self.class.name}:#{Object::o_hexy_id(self)}>
+          {
+            :pattern => "#@pattern",
+            :fields  => #{@fields.inspect}
+          }
+      }.squish
+    end
+
+    # Alias of `meaning` getter method.
+    # Returns human readable meaning for cron pattern after parsing it.
+    def humanize
+      @fields.collect do |_, field|
+        field.meaning
+      end.join("; ").chomp("; ")
+    end
+
+    # Returns warnings in pattern fields if any, occured while parsing those
+    # fields.
+    def warnings
+      warnings = @fields.collect do |_, field|
+        "for '#{field.field_name}' field: #{field.warning}" if field.warning
+      end.compact.join(", ").chomp(", ").split(", ")
+    end
+
+    # Alias of `new` method.
+    def self.parse(pattern = nil) # oh, that sounds ridiculous!
+      self.new(pattern).humanize
+    end
+
+    def method_missing(method, *args, &block)
+      super unless field_methods.include? method
+      self.class.send(:define_method, method) do
+        @fields[method.to_s.sub('_field', '').to_sym]
+      end and self.send(method, *args)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      field_methods.include? method || super
+    end
+
+    private
+
+    # Internal method to validate the cron pattern. Raises errors if pattern is
+    # invalid.
+    def validate!
+      unless @pattern.kind_of? String
+        raise InvalidCronPatternError.new("cron pattern must be a string".squish)
+      end
+      fix_common_typos! # how nasty!
+      # do you know that cron has some pretty good fields, huh?
+      # go and,
+      validate_fields!
+    end
+
+    # Internal method to validate each field in the pattern.
+    def validate_fields!
+      pattern_fields = @pattern.split
+      if pattern_fields.size != FIELDS.size
+        raise InvalidCronPatternError.new("cron pattern must contain exact
+                        #{FIELDS.size} fields seperated by whitespaces".squish)
+      end
+      FIELDS.map.with_index do |field, index|
+        field_class           = self.class.name + "::" + field.split("_"). \
+                                map(&:capitalize).join + "Field".squish.   \
+                                classify
+        @fields[field.to_sym] = field_class.safe_constantize.              \
+                                new(pattern_fields[index])
+      end
+    end
+
+    # Internal method to clean up the frequently made typos and mistakes in
+    # the cron pattern.
+    def fix_common_typos!
+      # well, I don't know what kind of typos people do!
+      @pattern.squish!
+    end
+
+    def field_methods
+      self.fields.keys.map{|f| (f.to_s + "_field").to_sym }
+    end
+  end
+end

data/lib/cron/parser/day_of_month_field.rb

@@ -0,0 +1,20 @@
+class Cron::Parser
+  class DayOfMonthField < Field
+    def self.allowed_values; ("1".."9").to_a + ("01".."31").to_a   end
+    def self.upper_bound;                self.allowed_values.last  end
+    def self.lower_bound;                self.allowed_values.first end
+    def self.allowed_special_characters; %w{ * / , - }             end
+    def self.specifications
+      super
+    end
+
+    # Creates partial meaning (sentence) for the day of month field's pattern.
+    def self.generate_meaning(list, unit)
+      meaning = ""
+      meaning += self.field_preposition(unit)
+      meaning += " days: "
+      meaning += list.map(&:to_s).map(&:ordinalize).join(", ")
+      meaning
+    end
+  end
+end

data/lib/cron/parser/day_of_week_field.rb

@@ -0,0 +1,51 @@
+class Cron::Parser
+  class DayOfWeekField < Field
+    def self.allowed_values
+      ("0".."7").to_a + ("00".."07").to_a + %w{ sun mon tue wed thu fri
+                                                sat }.map(&:upcase)
+    end
+
+    def self.allowed_special_characters; %w{ * / , - }             end
+    def self.upper_bound;                "0"                       end
+    def self.lower_bound;                "7"                       end
+
+    # Adds some day of week field-specific extra regular expressions to super
+    # class's `specifications` method.
+    def self.specifications
+      extra_specs = [
+        {
+         rule: /\A(?<day>(sun|mon|tue|wed|thu|fri|sat))\Z/i,
+         yields: ->(day, options) do
+           return [day] if options[:exclude_preposition]
+           return self.generate_meaning([day], options[:unit])
+         end,
+         for_fields: %w{ day_of_week }
+        },
+      ]
+      super + extra_specs
+    end
+
+    # Creates partial meaning (sentence) for the day of week field's pattern.
+    def self.generate_meaning(list, unit)
+      meaning = ""
+      meaning += self.field_preposition(unit)
+      meaning += " "
+      meaning += list.map{ |d| self.ascii_weekday(d) }.uniq.join(", ")
+      meaning
+    end
+
+    # Converts a numerical day of week value or 3-letter day of week value to
+    # human-readable week-day value.
+    def self.ascii_weekday(day)
+      case day.to_s.downcase
+      when "0", "00", "7", "07", "sun"; "Sunday"
+      when "1", "01", "mon";            "Monday"
+      when "2", "02", "tue";            "Tuesday"
+      when "3", "03", "wed";            "Wednsday"
+      when "4", "04", "thu";            "Thursday"
+      when "5", "05", "fri";            "Friday"
+      when "6", "06", "sat";            "Saturday"
+      end
+    end
+  end
+end

data/lib/cron/parser/field.rb

@@ -0,0 +1,213 @@
+class Cron::Parser
+  class Field
+    attr_reader :pattern,
+                :meaning,
+                :warning
+
+    def initialize(pattern)
+      raise NotImplementedError.new("'Cron::Parser::Field' can't be initialized
+                         directly".squish) if self.class == Cron::Parser::Field
+      @pattern = pattern   # for current field only
+      @warning = nil
+      @meaning = validate! # current field
+    end
+
+    def inspect
+      %Q{
+          #<#{self.class.name}:#{Object::o_hexy_id(self)}>
+          {
+           :pattern => "#@pattern",
+           #{":warning => #@warning," if @warning}
+           :meaning => "#@meaning"
+          }
+      }.squish
+    end
+
+    # Recognizes and validates the current field in cron pattern.
+    # FYI, all magic happens over here!
+    def validate!
+      investigate_invalid_values!
+
+      meaning    = ""
+      halt_loop  = false
+      match_data = nil
+      list       = []
+      values     = @pattern.split(",")
+      options    = {
+                     unit: self.field_name,
+                     exclude_preposition: true
+                   }
+
+      # iterate over all comma seperated values for current field
+      values.map.with_index do |value, index|
+        # look whether the value matches any of regex rule
+        self.class.specifications.map do |spec|
+          next unless spec[:for_fields].include? self.field_name
+          next if (match_data = spec[:rule].match(value)).nil?
+
+          # some special kind of values can dominate all other values for
+          # current field, e.g. value such as '*'
+          if spec[:can_dominate_all]
+            meaning   = spec[:yields].(*match_data.captures, options)
+            halt_loop = true and break
+          end
+
+          list << spec[:yields].(*match_data.captures, options)
+
+          # some values are confusing or ambiguous, e.g. '8/2' -- but crontab
+          # allows such values, but they can halt next comma seperated values
+          # from being parsed for the current field of cron pattern
+          if spec[:can_halt]
+            @warning  = "'#{value}' is valid but confusing pattern"
+            halt_loop = true
+            break
+          end
+          # stop looking for other regex rules if values is matched here
+          break if match_data
+        end
+        # stop iterating over comma seperated values if special-purpose flag:
+        # `halt_loop` is set to `true` somewhere
+        break if halt_loop
+      end
+
+      list = list.flatten.uniq.map(&:to_s).sort
+      list = list.map(&:to_i).sort if !!(/minute|hour|day_of_month/ =~ field_name)
+      if meaning.==("") and list.empty?
+        raise invalid_field_error_class.new("\"#{self.field_name}\" field's
+                                                pattern is invalid".squish)
+      end
+      meaning = self.class.generate_meaning(list, field_name) if meaning.==("")
+      meaning
+    end
+
+    # List of regular expressions to match the different kind of values in cron
+    # pattern fields, also produces partial meaning for the matched values
+    def self.specifications
+      [
+       {
+         # e.g.: "*"
+         rule: /\A\*\Z/,
+         yields: ->(options) do
+           "every " + options[:unit].split("_").join(" ")
+         end,
+         for_fields: %w{ minute hour day_of_month month day_of_week },
+         can_dominate_all: true
+       },
+       {
+         # e.g.: "*/2"
+         rule: /\A\*\/(?<step>\d+)\Z/,
+         yields: ->(step, options) do
+           range = []
+           (self.lower_bound.to_i..self.upper_bound.to_i).map do |value|
+             range << value if value.modulo(step.to_i).zero?
+           end
+           list = range.any? ? range : [step]
+           return list if options[:exclude_preposition]
+           return self.generate_meaning(list, options[:unit])
+         end,
+         for_fields: %w{ minute hour day_of_month month day_of_week }
+       },
+       {
+         # e.g.: "4"
+         rule: /\A(?<value>\d+)\Z/,
+         yields: ->(value, options) do
+           return [value] if options[:exclude_preposition]
+           return self.generate_meaning([value], options[:unit])
+         end,
+         for_fields: %w{ minute hour day_of_month month day_of_week }
+       },
+       {
+         # e.g.: "3-26"
+         rule: /\A(?<from>\d+)\-(?<to>\d+)\Z/,
+         yields: ->(from, to, options) do
+           range = (from..to).to_a
+           list  = range.any? ? range : [from]
+           return list.map(&:to_i) if options[:exclude_preposition]
+           return self.generate_meaning(list, options[:unit])
+         end,
+         for_fields: %w{ minute hour day_of_month month day_of_week }
+       },
+       {
+         # e.g.: "3-26/2"
+         rule: /\A(?<from>\d+)\-(?<to>\d+)\/(?<step>\d+)\Z/,
+         yields: ->(from, to, step, options) do
+           range = self.range_step_values(from.to_i, to.to_i, step.to_i)
+           return range if options[:exclude_preposition]
+           return self.generate_meaning(range, options[:unit])
+         end,
+         for_fields: %w{ minute hour day_of_month month day_of_week }
+       },
+       {
+         # e.g.: "12/3"
+         rule: /\A(?<value>\d+)\/\d+\Z/,
+         yields: ->(value, options) do
+           return [value] if options[:exclude_preposition]
+           return self.generate_meaning([value], options[:unit])
+         end,
+         for_fields: %w{ minute hour day_of_month month day_of_week },
+         can_halt: true
+       }
+      ]
+    end
+
+    # Checks for invalid characters and values for the current field.
+    def investigate_invalid_values!
+      invalids = @pattern.split(/,|\/|\-/).uniq.collect do |value|
+        value unless self.class.allowed_values.to_a.include?(value.upcase)
+      end.compact
+      invalids.delete("*")
+
+      err = nil
+      if invalids.include?('') || invalids.include?(' ')
+        err = "#{field_name} field's pattern is invalid, please run:
+            '#{self.class}.allowed_values' to know valid values".squish
+      elsif invalids.any?
+        err = "value: '#{invalids.join(', ')}' not allowed for '#{field_name}'
+        field, run: '#{self.class}.allowed_values' to know valid values".squish
+      end
+      raise self.invalid_field_error_class.new(err) if err
+    end
+
+    # Returns current field's name, for e.g. 'minute', 'hour', and likewise.
+    def field_name
+      self.class.name.split("::").last.downcase.sub("of", "_of_").          \
+                                sub("field", "").downcase
+    end
+
+    def self.field_name; self.new.field_name end
+
+    # Returns preposition for the current field to be prepended while generating
+    # meaning (partial sentence).
+    def self.field_preposition(field)
+      case field
+      when "minute"
+        "at"
+      when "hour", "day_of_month", "day_of_week"
+        "on"
+      when "month"
+        "in"
+      else
+        "at"
+      end
+    end
+
+    # An algorithm calculates and returns values exist for the expression
+    # <from>-<to>/<step>.
+    def self.range_step_values(from, to, step)
+      values = [from]
+      (from..to).map do |value|
+        value += step
+        if (value == values.last + step) and value <= to
+          values.push value
+        end
+      end
+      values
+    end
+
+    # Generates error class for the current cron field.
+    def invalid_field_error_class
+      ("Invalid" + self.field_name.split("_").map(&:capitalize).join +      \
+                               "FieldError").classify.safe_constantize
+    end
+  end
+end

data/lib/cron/parser/hour_field.rb

@@ -0,0 +1,56 @@
+class Cron::Parser
+  class HourField < Field
+    def self.allowed_values; ("0".."9").to_a + ("00".."23").to_a   end
+    def self.upper_bound;                self.allowed_values.last  end
+    def self.lower_bound;                self.allowed_values.first end
+    def self.allowed_special_characters; %w{ * / , - }             end
+    def self.specifications
+      super
+    end
+
+    # Converts 24-hour value to 12-hour am/pm value.
+    def self.to_12h(hour)
+      case hour.to_i
+      when 0
+        "12am"
+      when 1..11
+        hour.to_s + "am"
+      when 12
+        hour.to_s + "pm"
+      when 13..23
+        (hour - 12).to_s + "pm"
+      end
+    end
+
+    # Sorts a given array of 12-hour am/pm values in a clockwise order starting
+    # from midnight (like: 12am, 1am, 2am, ..., 11am, 12pm, 1pm, 2pm, ..., 11pm)
+    def self.sort_by_12h(hours_array)
+      hour_priority_map = {
+        "12am" => 1, "1am" => 2, "2am" => 3, "3am" => 4, "4am" => 5, "5am" => 6,
+        "6am" => 7, "7am" => 8, "8am" => 9, "9am" => 10, "10am" => 11,
+        "11am" => 12, "12pm" => 13, "1pm" => 14, "2pm" => 15, "3pm" => 16,
+        "4pm" => 17, "5pm" => 18, "6pm" => 19, "7pm" => 20, "8pm" => 21,
+        "9pm" => 22, "10pm" => 23, "11pm" => 24
+      }
+      arr_with_priorities = hours_array.collect do |hour|
+        hour_priority_map[hour]
+      end.sort
+      return_arr = []
+      arr_with_priorities.map do |priority|
+        hour_priority_map.each_pair do |hr, pr|
+          return_arr << hr if pr == priority
+        end
+      end.flatten
+      return_arr
+    end
+
+    # Creates partial meaning (sentence) for the hour field's pattern.
+    def self.generate_meaning(list, unit)
+      meaning = ""
+      meaning += self.field_preposition(unit)
+      meaning += " "
+      meaning += list.map(&:to_i).map{ |h| self.to_12h(h) }.join(", ")
+      meaning
+    end
+  end
+end

data/lib/cron/parser/minute_field.rb

@@ -0,0 +1,22 @@
+class Cron::Parser
+  class MinuteField < Field
+    def self.allowed_values; ("0".."9").to_a + ("00".."59").to_a   end
+    def self.upper_bound;                self.allowed_values.last  end
+    def self.lower_bound;                self.allowed_values.first end
+    def self.allowed_special_characters; %w{ * / , - }             end
+    def self.specifications
+      super
+    end
+
+    # Creates partial meaning (sentence) for the minute field's pattern.
+    def self.generate_meaning(list, unit)
+      meaning = ""
+      meaning += self.field_preposition(unit)
+      meaning += " "
+      meaning += list.map(&:to_s).map(&:ordinalize).join(", ")
+      meaning += " "
+      meaning += unit
+      meaning
+    end
+  end
+end

data/lib/cron/parser/month_field.rb

@@ -0,0 +1,61 @@
+class Cron::Parser
+  class MonthField < Field
+    def self.allowed_values
+      ("1".."9").to_a + ("01".."12").to_a + %w{ jan feb mar apr may jun
+                                                jul aug sep oct nov dec
+                                              }.map(&:upcase)
+    end
+
+    def self.allowed_special_characters; %w{ * / , - }             end
+    def self.upper_bound;                "1"                       end
+    def self.lower_bound;                "12"                      end
+
+    # Adds some month field-specific extra regular expressions to super class's
+    # `specifications` method.
+    def self.specifications
+      extra_specs = [
+        {
+          rule: /\A
+                (?<month>
+                (jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)
+                )
+                \Z/ix,
+         yields: ->(month, options) do
+           return [month] if options[:exclude_preposition]
+           return self.generate_meaning([month], options[:unit])
+         end,
+         for_fields: %w{ month }
+        },
+      ]
+      super + extra_specs
+    end
+
+    # Creates partial meaning (sentence) for the month field's pattern.
+    def self.generate_meaning(list, unit)
+      meaning = ""
+      meaning += self.field_preposition(unit)
+      meaning += " "
+      meaning += list.map{ |m| self.ascii_month(m) }.join(", ")
+      meaning
+    end
+
+    # Converts a numerical month value or 3-letter month value to human-readable
+    # month value.
+    def self.ascii_month(month)
+      case month.to_s.downcase
+      when "1", "01", "jan";            "January"
+      when "2", "02", "feb";            "February"
+      when "3", "03", "mar";            "March"
+      when "4", "04", "apr";            "April"
+      when "5", "05", "may";            "May"
+      when "6", "06", "jun";            "June"
+      when "7", "07", "jul";            "July"
+      when "8", "08", "aug";            "August"
+      when "9", "09", "sep";            "September"
+      when "10", "oct";                 "October"
+      when "11", "nov";                 "November"
+      when "12", "dec";                 "December"
+      end
+    end
+  end
+end

data/lib/cron/parser/version.rb

@@ -0,0 +1,5 @@
+class Cron
+  class Parser
+    VERSION = '0.1.0'
+  end
+end

data/lib/extras/custom_errors.rb

@@ -0,0 +1,7 @@
+InvalidCronPatternError     = Class.new(ArgumentError)
+
+InvalidMinuteFieldError     = Class.new(ArgumentError)
+InvalidHourFieldError       = Class.new(ArgumentError)
+InvalidDayOfMonthFieldError = Class.new(ArgumentError)
+InvalidMonthFieldError      = Class.new(ArgumentError)
+InvalidDayOfWeekFieldError  = Class.new(ArgumentError)

data/lib/extras/extensions.rb

@@ -0,0 +1,35 @@
+module StringExtensions
+  # Adds 'th', 'nd', 'st' like ordinal to numerical (string) values.
+  # e.g. 22nd, 40th, 1st etc.
+  def ordinalize
+    match = /\A(?<int>\d+)\Z|\A(?<real>\d+\.\d+)\Z/.match(self)
+    raise NameError.new("cannot ordinalize non-numeric value") unless match
+    num = match[:int] ? self.to_i : self.to_f
+    "#{num}#{num.to_s.ordinal}"
+  end
+
+  def ordinal
+    ActiveSupport::Inflector.ordinal(self)
+  end
+
+  # Removes extra whitespaces from the string.
+  def squish
+    dup.squish!
+  end
+
+  # Destructive version of `squish` method.
+  def squish!
+    strip!
+    gsub!(/\s+/, ' ')
+    self
+  end
+end
+
+class String; self.send :include, StringExtensions end
+
+class Object
+  # Generate hex value for requester object in argument.
+  def self.o_hexy_id(requester) # that's not "oh sexy lady", or is it?!
+    "0x" + (requester.object_id << 1).to_s(16)
+  end
+end

data/spec/cron/parser_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+
+class Cron
+  describe Parser do
+
+    let(:parser_klass) { Cron::Parser }
+
+    spec_fields = %w{ minute hour day_of_month month day_of_week }
+
+    it "should check invalid pattern" do
+      expect { parser_klass.new }.to raise_error(InvalidCronPatternError, /cron pattern must be a string/)
+      expect { parser_klass.new("") }.to raise_error(InvalidCronPatternError, /cron pattern must contain exact/)
+    end
+
+    context "initialized with correct pattern" do
+      subject { parser_klass.new("* * * * *") }
+
+      specify { expect(subject).to be_an_instance_of(parser_klass) }
+
+      specify { should have_exactly(5).fields }
+
+      it "should respond to all public instance methods" do
+        methods = [:pattern, :fields, :meaning, :warnings, :humanize, :inspect] + spec_fields.map(&:to_sym).map { |f| f = "#{f}_field" }
+        methods.each do |method|
+          subject.should respond_to(method)
+        end
+      end # respond to public instance methods
+
+      context "checks each instance field" do
+        it "check minute_field instance" do
+          expect(subject.minute_field).to eq(subject.fields[:minute])
+        end
+        it "check hour_field instance" do
+          expect(subject.hour_field).to eq(subject.fields[:hour])
+        end
+        it "check day_of_month_field instance" do
+          expect(subject.day_of_month_field).to eq(subject.fields[:day_of_month])
+        end
+        it "check month_field instance" do
+          expect(subject.month_field).to eq(subject.fields[:month])
+        end
+        it "check day_of_week_field instance" do
+          expect(subject.day_of_week_field).to eq(subject.fields[:day_of_week])
+        end
+      end # context each instance field
+    end # context correct pattern
+
+    context "well, start with kind of patterns..." do
+      context "wrong patterns tests" do
+
+        describe "minute" do
+          wrong_min_patterns = ["-1 * * * *", "3- * * * *", "60 * * * *", "1,2,b * * * *", "1-03,3/,6 * * * *", "5--6, * * * *", "(2,3),5 * * * *"]
+          wrong_min_patterns.each do |pattern|
+            it "for PATTERN: \"#{pattern}\" it raises error" do
+              expect { parser_klass.new(pattern) }.to raise_error(InvalidMinuteFieldError)
+            end
+          end
+        end # context wrong minute pattern
+
+        describe "hour" do
+          wrong_hr_patterns = ["* -1 * * *", "* 3- * * *", "* 24 * * *", "* 1pm * * *", "* 3/,4 * * *", "* 5--10 * * *", "* 20%5 * * *"]
+          wrong_hr_patterns.each do |pattern|
+            it "for PATTERN: \"#{pattern}\" it raises error" do
+              expect { parser_klass.new(pattern) }.to raise_error(InvalidHourFieldError)
+            end
+          end
+        end # context wrong hour pattern
+
+        describe "day_of_month" do
+          wrong_dom_patterns = ["* * 0 * *", "* * -1 * *", "* * 3- * *", "* * 32 * *", "* * 1st * *", "* * 3/,5,6 * *", "* * 5--10 * *", "* * 2^2 * *"]
+          wrong_dom_patterns.each do |pattern|
+            it "for PATTERN: \"#{pattern}\" it raises error" do
+              expect { parser_klass.new(pattern) }.to raise_error(InvalidDayOfMonthFieldError)
+            end
+          end
+        end # context wrong day_of_month pattern
+
+        describe "month" do
+          wrong_mnth_patterns = ["* * * 0 *", "* * * -1 *", "* * * 3- *", "* * * 13 *", "* * * MARC *", "* * * 1st *", "* * * 3/,5,6 *", "* * * 5--10 *", "* * * @ *"]
+          wrong_mnth_patterns.each do |pattern|
+            it "for PATTERN: \"#{pattern}\" it raises error" do
+              expect { parser_klass.new(pattern) }.to raise_error(InvalidMonthFieldError)
+            end
+          end
+        end # context wrong month pattern
+
+        describe "day_of_week" do
+          wrong_dow_patterns = ["* * * * -1", "* * * * 3-", "* * * * 8", "* * * * sunday", "* * * * 2nd", "* * * * 3/", "* * * * 1--6", "* * * * %"]
+          wrong_dow_patterns.each do |pattern|
+            it "for PATTERN: \"#{pattern}\" it raises error" do
+              expect { parser_klass.new(pattern) }.to raise_error(InvalidDayOfWeekFieldError)
+            end
+          end
+        end # context wrong day_of_week pattern
+      end # context invalid patterns' tests
+
+      context "valid patterns tests" do
+
+        def test_valid_pattern(pattern = "", meaning = "", warnings = [])
+          parsed_obj = parser_klass.new(pattern)
+          parsed_obj.meaning.should == meaning
+          parsed_obj.warnings.should == warnings
+        end
+
+        valid_data = [
+          ["* * * * *", "every minute; every hour; every day of month; every month; every day of week", []],
+          ["04 * * * *", "at 4th minute; every hour; every day of month; every month; every day of week", []],
+          ["5 0 * * *", "at 5th minute; on 12am; every day of month; every month; every day of week", []],
+          ["15 14 1 * *", "at 15th minute; on 2pm; on days: 1st; every month; every day of week", []],
+          ["0 22 * * 1-5", "at 0th minute; on 10pm; every day of month; every month; on Monday, Tuesday, Wednsday, Thursday, Friday", []],
+          ["23 0-23/2 * * *", "at 23rd minute; on 12am, 2am, 4am, 6am, 8am, 10am, 12pm, 2pm, 4pm, 6pm, 8pm, 10pm; every day of month; every month; every day of week", []],
+          ["5 4 * * sun", "at 5th minute; on 4am; every day of month; every month; on Sunday", []],
+          ["0 4 8-14 * *", "at 0th minute; on 4am; on days: 8th, 9th, 10th, 11th, 12th, 13th, 14th; every month; every day of week", []],
+          ["5-12,1,59 4-10/2,11 */6,28,29 1-3,Nov,Dec *", "at 1st, 5th, 6th, 7th, 8th, 9th, 10th, 11th, 12th, 59th minute; on 4am, 6am, 8am, 10am, 11am; on days: 6th, 12th, 18th, 24th, 28th, 29th, 30th; in January, February, March, December, November; every day of week", []],
+          ["38,37/40,39 1/2,3 26,27/2,30,31 * MON", "at 37th, 38th minute; on 1am; on days: 26th, 27th; every month; on Monday", ["for 'minute' field: '37/40' is valid but confusing pattern", "for 'hour' field: '1/2' is valid but confusing pattern", "for 'day_of_month' field: '27/2' is valid but confusing pattern"]],
+        ]
+
+        valid_data.map do |item|
+          pattern, meaning, warnings = item
+          display_msg  = "for PATTERN: \"#{pattern}\""
+          display_msg += "\n\tmeaning: \"#{meaning}\""
+          display_msg += "\n\twarnings: #{warnings}" if warnings.any?
+
+          it display_msg do
+            test_valid_pattern(pattern, meaning, warnings)
+          end
+        end
+
+      end # context valid patterns' tests
+    end # context start with kind of patterns
+  end # describe Parser
+end # class Cron

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'rubygems'
+require 'rspec'
+require 'cron'
+require 'cron/parser'
+require 'extras/custom_errors'
+require 'extras/extensions'

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: cron-parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vishal Telangre
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: the@vishaltelangre.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- CHANGELOG.md
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- cron-parser.gemspec
+- lib/cron.rb
+- lib/cron/parser.rb
+- lib/cron/parser/day_of_month_field.rb
+- lib/cron/parser/day_of_week_field.rb
+- lib/cron/parser/field.rb
+- lib/cron/parser/hour_field.rb
+- lib/cron/parser/minute_field.rb
+- lib/cron/parser/month_field.rb
+- lib/cron/parser/version.rb
+- lib/extras/custom_errors.rb
+- lib/extras/extensions.rb
+- spec/cron/parser_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/vishaltelangre/cron-parser
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+- lib/extras
+- lib/cron
+- lib/cron/parser
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.2
+signing_key: 
+specification_version: 4
+summary: Dissect your Cron patterns!
+test_files: []