Cron::Parser

Dissect your Cron pattern!

Installation

Install gem by using following command:

gem install cron-parser

or add it to your Gemfile as:

gem 'cron-parser', require: 'cron'

Usage

Well, using Cron::Parser is really easy, take a look at following example:

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?

>> 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.
Make a pull request, bonus points for topic branches.

Copyright and License

This project is licenced under the MIT License.