alpinweis/cronex

Ruby library that converts cron expressions into human readable strings

Cronex

A Ruby library that converts cron expressions into human readable strings. Translated to Ruby from cron-expression-descriptor (C#) via cron-parser (Java).

Original Author & Credit: Brady Holt (http://www.geekytidbits.com).

Features

• Supports all cron expression special characters including: * / , - ? L W #
• Supports 5, 6 (w/ seconds or year), or 7 (w/ seconds and year) part cron expressions
• Provides casing options (sentence, title, lower)
• Support for non-standard non-zero-based week day numbers
• Supports printing to locale specific human readable format
• Supports displaying times in specific timezones

For a quick intro to cron see Quartz Cron Tutorial.

Available Locales

• English
• Brazilian
• French
• German
• Italian
• Romanian
• Russian

Installation

Add this line to your application's Gemfile:

gem 'cronex'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install cronex

Usage

Zero based day of week

Cronex::ExpressionDescriptor.new('*/5 15 * * 1-5').description
=> Every 5 minutes, at 3:00 PM, Monday through Friday

Cronex::ExpressionDescriptor.new('0 0/30 8-9 5,20 * ?').description
=> Every 30 minutes, between 8:00 AM and 9:59 AM, on day 5 and 20 of the month

Non-zero based day of week

Cronex::ExpressionDescriptor.new('*/5 15 * * 1-5', zero_based_dow: false).description
=> Every 5 minutes, at 3:00 PM, Sunday through Thursday

Localization

Cronex::ExpressionDescriptor.new('30 2 * 2 1-5', locale: 'fr').description
=> À 2:30 AM, lundi à vendredi, seulement en février

Timezones

Cronex::ExpressionDescriptor.new('0-10 11 * * *', timezone: 'America/Los_Angeles').description
=> Every minute between 4:00 AM and 4:10 AM # PDT or
=> Every minute between 3:00 AM and 3:10 AM # PST

Strict quartz-scheduler implementation support

Cronex::ExpressionDescriptor.new('* * * * *', strict_quartz: true).description
=> Cronex::ExpressionError (Error: Expression only has 5 parts. For 'strict_quartz' option, at least 6 parts are required)

See spec tests for more examples.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

cronex's Issues

Backwards option ?

I'm looking for an option where users can write human readable statements and it spits out a cron,
would that be easy to add / does that already exist ?

Incorrect description when using last day of month in a range for DoM

Hi there,

I think I've found a bug when parsing cron expressions that use L in the DoM field within a range. Here's a breakdown:

Cron expression: * * 25-L * *
Current value: Every minute, between day 25 and L of the month
Expected value: Every minute, between day 25 and the last day of the month or something approaching that.

Thanks so much for this great gem, we save schedules for people in a cron format, and make it human-readable for users using this gem.

Let me know if I can help in any way to get this fixed.

Leading zeros cause ArgumentError

Hey I ran into this problem recently with my project, cron strings that have fields with leading zeros fail. An example string would be "10 09 * * *" which should return "At 9:10" but it wails with the following error:

ArgumentError (invalid value for Integer(): "09"):

Cannot parse range sets

The following cron times cannot be parsed although they are valid.

20 8,15 * * 0-1,3-6
0 7 * * 0-3,5-6
55,25 2-21,23 * * 0,1,3,5,6
55,25 2-7,10-21,23 * * 2,4

Unicode dependency compilation issues

Hello! When installing this gem on ruby 3.3 I get an error when it tries to install the unicode dependency:

In Gemfile:
  cronex was resolved to 0.13.0, which depends on
    unicode

and a lot of text like:

unicode.c:37:7: warning: 'RB_OBJ_TAINTED' is deprecated: taintedness turned out to be a wrong idea. [-Wdeprecated-declarations]
  if (OBJ_TAINTED(src))

Obviously, this is not cronex, but because cronex uses unicode to handle case transformation it breaks. Luckily, someone is already working on a fix: blackwinter/unicode#11

I also wonder if this gem needs the unicode dependency. I made the following change to the transform_case method and all the tests still passed:

def transform_case(desc, case_type = :lower)
  case case_type
  when :sentence
-   desc.sub(/\b[[:word:]]/u) { |s| Unicode.upcase(s) }
+   desc.sub(/\b[[:word:]]/u) { |s| s.upcase }
  when :title
-   desc.gsub(/\b[[:word:]]/u) { |s| Unicode.upcase(s) }
+   desc.gsub(/\b[[:word:]]/u) { |s| s.upcase }
  else
-   Unicode.downcase(desc)
+   desc.downcase
  end
end

Although I'm not sure the tests are exhaustive here and I understand unicode can be complex. I'm totally open to the idea that this is not an adequate fix.

Suggestion: Move locale and timezone into options

It would be nicer if all options - including locale and timezone - are treated the same.

The fact that there is an empty hash in the below call, is not very "ruby":

Cronex::ExpressionDescriptor.new('* * * * *", {}, "fr").description

The problem is even more evident when you want to only set timezone

Cronex::ExpressionDescriptor.new('* * * * *", {}, nil, "New York").description

Would be clearer and nicer (and dare I say idiomatic....) to do:

Cronex::ExpressionDescriptor.new('* * * * *", locale: 'fr', timezone: "New York").description

Timezone conversion doesn't change the days

The day of month / day of the week are not updated when changing the timezone. For example:

Cronex::ExpressionDescriptor.new('0 22 * * 1-5', {}, 'en', 'UTC').description
# => "At 10:00 PM, Monday through Friday"
Cronex::ExpressionDescriptor.new('0 22 * * 1-5', {}, 'en', 'Pacific/Auckland').description
# => "At 11:00 AM, Monday through Friday"

We can see that it's still Monday through Friday in Pacific/Auckland when it should be Tuesday through Saturday because NZDT is 13 hours ahead (see: https://savvytime.com/converter/utc-to-nzst/mar-2-2020/10pm).

Can you think of a good way to support this? I had a look at the code but it looks pretty complicated.

Wrong parse for days jump

When trying to parse this kind of rule:
30 7 1-31/2 * *
i get:
Alle(ai) 7:30 AM, ogni 2 giorni, , tra il giorno 1 e il 31 del mese

So there are two consecutive commas. I tried to figure out on myself but I got lost in the code.

Cannot parse multiple range hours

The program gives error when parsing rules like * 20-23,0-18 * * * so I needed to split it in two rules.

Add executable command

I'd like to be able to use cronex as a quick command line utility. Would it be possible to add an executable command that takes cron lines and turns them into a more human readable format?

$ cronex '*/5 15 * * 1-5'
Every 5 minutes, at 3:00 PM, Monday through Friday

I'd be happy to work on this if it sounds like an interesting feature.

tzinfo update

Hi there looks like "cronex" has dependency on tzinfo version which blocks update of it.

Bundler could not find compatible versions for gem "tzinfo":
  In Gemfile:
    tzinfo (~> 2.0.0)

    cronex was resolved to 0.9.0, which depends on
      tzinfo (~> 1.2.5)

could you please make changes in gemspec to support the newest version of tzinfo? Thank you