{dialga}

Purpose

{dialga} is an R package that lets you build and interpret standard cron expressions using familiar R syntax.

Cron is software for scheduling computer tasks (‘cron jobs’). Cron strings detail concisely the required schedule. They require a specific format, like "0/15 * 1,3,20 6 0,6", but it can be difficult to remember how to structure them.

Read more in the accompanying blog post and report any bugs you might find.

Install

Install from GitHub with help from {remotes}:

install.packages("remotes")  # if not already installed
remotes::install_github("matt-dray/dialga")
library(dialga)

If you want to be able to have the cron string output copied directly to your clipboard, you’ll need to install the {clipr} package to your machine with install.packages("clipr") as well. You don’t have to install it if you don’t want to.

Demonstration

There’s currently two functions: r2cron() takes integer vectors as inputs to time-period arguments and spits out a cron string, and cron2eng() takes a valid cron string and prints out a readable English version. See ?dialga::r2cron() and ?dialga::cron2eng() for further details.

Simple

A simple example of r2cron(): how would you specify the 28th minute past 11PM every day?

x <- dialga::r2cron(
  minutes = 28, 
  hours = 23  # 24-hour clock
)

x
#> [1] "28 23 * * *"

Note that you can use the argument clip = TRUE to have the output copied to your system’s clipboard so you can paste it elsewhere. You must install the {clipr} package separately if you want this functionality.

To interpret the output—and confirm we got what we expected—we can pass that cron string into cron2eng().

dialga::cron2eng(x)
#> Cron string '28 23 * * *' means:
#>   - minute(s) 28
#>   - hour(s) 11PM
#>   - every day(s) of the month
#>   - every month(s)
#>   - any day(s) of the week

The output isn’t sophisticated, but it communicates the point.

You could even pipe these functions together to go from R to English.

library(magrittr)  # for %>%

dialga::r2cron(minutes = 28, hours = 23) %>% 
  dialga::cron2eng()
#> Cron string '28 23 * * *' means:
#>   - minute(s) 28
#>   - hour(s) 11PM
#>   - every day(s) of the month
#>   - every month(s)
#>   - any day(s) of the week

Complex

A more complicated (i.e. contrived) request might be ‘every 20 minutes from the zeroth minute of 3PM, 4PM and 5PM, on the 1st days of April, October and November, plus every weekend’:

y <- dialga::r2cron(
 minutes = seq(0, 59, 20),
 hours = 15:17,  # 24-hr clock
 days_month = 1,
 months = c(4, 10, 11),
 days_week = c(1, 7)  # Sunday is '1'
)

y
#> [1] "0/20 15-17 1 4,10,11 0,6"

And in English:

dialga::cron2eng(y)
#> Cron string '0/20 15-17 1 4,10,11 0,6' means:
#>   - every 20 minute(s) starting from minute(s) 0
#>   - hour(s) 3PM to 5PM
#>   - day(s) of the month 1
#>   - month(s) April, October and November
#>   - and day(s) of the week Sunday and Saturday

Warnings

As a courtesy, you’ll be warned when unlikely dates arise:

dialga::r2cron(days_month = 28:31, months = 2)
#> Warning in dialga::r2cron(days_month = 28:31, months = 2): 
#>   Sure? There's no 31st in Feb, Apr, Jun, Sept nor Nov.
#> Warning in dialga::r2cron(days_month = 28:31, months = 2): 
#>   Sure? There's no 30th in Feb.
#> Warning in dialga::r2cron(days_month = 28:31, months = 2): 
#>   Sure? 29 Feb is only in leap years.
#> [1] "* * 28-31 2 *"

Actual scheduling tools

If on Unix/Linux, you can use the {cronR} package to schedule tasks from R. The Windows alternative is the {taskscheduleR} package. I typically use the web service crontab.guru to build cron expressions. It was helpful for checking {dialga}’s functionality.

Code of Conduct

Please note that the {dialga} project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.