/
README.Rmd
123 lines (83 loc) · 5.41 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(dialga)
```
<img src="https://raw.githubusercontent.com/matt-dray/stickers/master/output/dialga_hex.png" width="150" align="right">
# {dialga}
<!-- badges: start -->
[](https://www.repostatus.org/#inactive)
[](https://github.com/matt-dray/dialga/actions)
[](https://codecov.io/gh/matt-dray/dialga?branch=main)
[](https://www.codefactor.io/repository/github/matt-dray/dialga)
[](https://www.rostrum.blog/2021/04/10/dialga/)
<!-- badges: end -->
## Purpose
{dialga} is an R package that lets you build and interpret standard [cron expressions](https://en.wikipedia.org/wiki/Cron#CRON_expression) 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](https://www.rostrum.blog/2021/04/10/dialga/) and [report any bugs](https://github.com/matt-dray/dialga/issues) you might find.
## Install
Install from GitHub with help from {remotes}:
```{r eval=FALSE}
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](https://cran.r-project.org/package=clipr) 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?
```{r r2cron-simple}
x <- dialga::r2cron(
minutes = 28,
hours = 23 # 24-hour clock
)
x
```
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](https://cran.r-project.org/package=clipr) 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()`.
```{r cron2eng-simple}
dialga::cron2eng(x)
```
The output isn't sophisticated, but it communicates the point.
You could even pipe these functions together to go from R to English.
```{r simple-pipe, message=FALSE}
library(magrittr) # for %>%
dialga::r2cron(minutes = 28, hours = 23) %>%
dialga::cron2eng()
```
### 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':
```{r r2cron-complex}
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
```
And in English:
```{r cron2eng-complex}
dialga::cron2eng(y)
```
### Warnings
As a courtesy, you'll be warned when unlikely dates arise:
```{r}
dialga::r2cron(days_month = 28:31, months = 2)
```
## Actual scheduling tools
If on Unix/Linux, you can use [the {cronR} package](https://github.com/bnosac/cronR) to schedule tasks from R. The Windows alternative is [the {taskscheduleR} package](https://github.com/bnosac/taskscheduleR). I typically use the web service [crontab.guru](https://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](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.