Taskloop is a scheduled task manager optimized based on crontab.
Compared to crontab, taskloop offers more user-friendly and semantic syntax rules. In addition to supporting crontab syntax, taskloop also provides some extensions, such as the number of loops, start/end time, log query, environment variable import, etc.
Features
- Environment variable import/remove/list
- Task log query, taskloop log query
- Task deploy/undeploy
- Global switch to enable/disable taskloop
- user-friendly and semantic syntax rules
- time specific rule
- time scope rules
- before scope rule
- between scope rule
- after scope rule
- time interval rule
- loop count rule
- execution boundary rules
- start point boundary rule
- end point boundary rule
- date list rule
- time list rule
Installation
Install the gem and add to the application's Gemfile by executing:
$ bundle add taskloop
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install taskloop
Usage
TaskLoop provides a series of commands for workflows, as well as a set of syntax rules for users to customize their tasks.
When using taskloop, we recommend that you use a git project or a local directory to manage all your scheduled tasks. This doesn't mean that you have to centralize management in just one place; of course, you can use multiple git projects or directories to manage different types of scheduled tasks. Taskloop supports these different management methods; these are just recommendations.
Next, let's introduce the standard workflow of Taskloop.
Launch
Before you start using taskloop, you need to execute the taskloop launch
command to globally launch taskloop.
Correspondingly, taskloop also provides a taskloop shutdown
command to globally shutdown taskloop.
Init Taskfile
A Taskfile is used to describe custom tasks, and multiple tasks can be described in one Taskfile. Therefore, we can
execute the taskloop init
command in a directory to generate a Taskfile and describe specific tasks in the Taskfile.
Customize Scheduled Task
After you execute the taskloop init
command, a Taskfile template file will be automatically generated in the current
directory. The template file describes how to describe a task, including which attributes are specified
for each task, which attributes are required, and which attributes are optional.
The following is the Taskfile template file:
# env to set environment variables which are shared by all tasks defined in the Taskfile. <Optional>
# env "ENV_NAME", "ENV_VALUE"
TaskLoop::Task.new do |t|
t.name = 'TODO: task name. <Required>'
t.path = 'TODO: task job path. For example, t.path = "./Job.sh". <Required>'
t.week = 'TODO: week rule. <Optional>'
t.year = "TODO: year rule. <Optional>"
t.month = "TODO: month rule. <Optional>"
t.day = "TODO: day rule. <Optional>"
t.hour = "TODO: hour rule. <Optional>"
t.minute = "TODO: minute rule. <Optional>"
t.date = "TODO: date list rule. <Optional>"
t.time = "TODO: time list rule. <Optional>"
t.loop = "TODO: loop count. <Optional>"
t.start_point = "TODO: start point boundary rule. <Optional>"
t.end_point = "TODO: end point boundary rule. <Optional>"
end
At the beginning of the file, we can define environment variables for the tasks in the Taskfile, using the env
syntax.
The env syntax takes two arguments, the first is the name of the environment variable and the second is the value of the environment variable. We can use the env syntax multiple times to define multiple environment variables. These environment variables are shared by all tasks in the Taskfile.
env <ENV_NAME1> <ENV_VALUE1>
env <ENV_NAME2> <ENV_VALUE2>
env <ENV_NAME3> <ENV_VALUE3>
...
Every task needs to be initialized using the TaskLoop::Task.new
syntax, and set the property in the do
closure.
There are two required attributes of a task, name
and path
, and the rest are optional attributes. If none of the
optional properties is set, the task will be executed every minute.
Regarding optional attributes, some attributes support multiple rules, but do not support rules at the same time. If a property is set multiple times in a task description, the last setting will override all previous settings.
The week
attribute implements two rules: ScopeRule
and SpecificRule
. When you set the week attribute, you must use
the symbols defined by taskloop, such as: :Sun
means Sunday. For the specific definition of these symbols, you can
check the definition of WEEK
in lib/taskloop/task/task_property.rb
.
The year
attribute implements three rules: ScopeRule
, SpecificRule
and IntervalRule
. When you set the year
property, you can directly use numbers to represent the year or interval. Regarding the year attribute, there is no
predefined symbols for taskloop.
The month
attribute implements three rules: ScopeRule
, SpecificRule
and IntervalRule
. When defining the month
property, you have to set ScopeRule
and SpecificRule
with predefined month symbols, such as: :Aug
means August.
For IntervalRule
, just use a number directly, which is used to represent the number of months in the interval. For the
specific definition of these symbols, you can check the definition of MONTH
in lib/taskloop/task/task_property.rb
.
The day
attribute implements three rules: ScopeRule
, SpecificRule
and IntervalRule
. It indicates the day of the
month,taskloop has predefined symbols for it, such as: :day7
means the 7th day of a certain month, and so on. For the
specific definition of these symbols, you can check the definition of DAY
in lib/taskloop/task/task_property.rb
.
The hour
attribute implements three rules: ScopeRule
, SpecificRule
and IntervalRule
. When you set the hour
property, you can directly use numbers to represent hour value or interval.
The minute
attribute implements three rules: ScopeRule
, SpecificRule
and IntervalRule
. When you set the minute
property, you can directly use numbers to represent minute value or interval.
The date
attribute is also used to set the date. When you use SpecificRule
for year
, month
and day
property,
please don't set date
property at the same time. When you set SpecificRule
for year
, month
and day
attribute,
you can only set one date, but when you use date
attribute, you can set a list of dates. This kind of rule that can
set a series of dates is called DateListRule
in taskloop. When using DateListRule
, you can pass in a series of
characters representing the date, for example: "2023-8-1".
The time
attribute is also used to set the time. When you use SpecificRule
for hour
and minute
property, please
don't set time
property at the same time. When you set SpecificRule
for hour
and minute
attribute, you can only
set one time, but when you use time
attribute, you can set a time list. This kind of rule that can set a time list is
called TimeListRule
in taskloop. When using TimeListRule
, you can pass in a series of characters representing the
time, for example: "10:00:00".
The loop
attribute is used to indicate the execution times of the scheduled task, and the only supported rule is
called LoopRule
. When using LoopRule
, you only need to pass in a number indicating the number of executions.
The start_point
attribute is used to indicate the earliest execution time of the task, and the rule it supports is
called StartPointBoundaryRule
. When using StartPointBoundaryRule
, you need to pass in a string representing the
start time, such as: "2023-10-1 10:00:00".
The end_point
attribute is used to indicate the last execution time of the task, and the rule it supports is called
EndPointBoundaryRule
. When using EndPointBoundaryRule
, you need to pass in a string representing the end time, such
as: "2023-10-30 10:00:00".
Deploy
After you define or modify the Taskfile, you can execute the taskloop deploy
command to deploy. After the deployment
is successful, the taskloop will actually execute the scheduled tasks according to the rules you defined.
If you find a problem after deploying the Taskfile, you can re-edit it and deploy it again. Or you can undeploy it
directly through the taskloop undeploy
command to avoid serious consequences.
Advanced Usage
Environment Variable
Regarding environment variables, Taskfile supports defining local environment variables. In addition, taskloop also
provides a taskloop env
command to support importing/deleting/viewing environment variables. For example:
# to list all the global environment variables
$ taskloop env
# to import PATH and RUBY_HOME
$ taskloop env --import=PATH,RUBY_HOME
# to remove MY_HOME environment variable
$ taskloop env --remove=MY_HOME
List Task
If we want to see which scheduled tasks are running in the taskloop, we can use the taskloop list command at this time. For example:
$ taskloop list
Log Query
If we want to query the execution log of the task, we can use the taskloop log
command, which supports the log of
specific tasks and the log of the system. For example:
# to query the log of task which is named "morning tip"
$ taskloop log --task-name="morning tip"
# to query the system log of taskloop
$ taskloop log --cron
Rules
In above, we know that different attributes of tasks refer to different rules. Next, let's introduce the specific usage of these rules.
IntervalRule
If you want to execute a task every period of time, you need to use IntervalRule
. Attributes that support
IntervalRule
include year
, month
, day
, hour
, minute
. When you use IntervalRule
on different properties, their units are
different, and finally taskloop will calculate the time interval of their combination to execute the task.
The syntax of IntervalRule
is interval
, and the usage example of IntervalRule
is shown below.
# execute the task every 5 minutes
t.minute = interval 5
# execute the task every 1 hour and 10 minutes
t.hour = interval 1
t.minute = interval 5
ScopeRule
If you want to specify the task to execute within a time range, then you can use ScopeRule
. In fact, ScopeRule
contains three specific types of rules, which are BeforeScopeRule
, BetweenScopeRule
, AfterScopeRule
. Attributes
that support ScopeRule
include week
, year
, month
, day
, hour
, minute
. Here are a few examples of
ScopeRule
usage.
# executed between 10 o'clock and 19 o'clock
t.hour = between 10, 19
# execute before 30 minutes of the hour
t.minute = before 30
# executed after october
t.month = after :Oct
# execute within working days
t.week = between :Mon, :Fri
SpecificRule
If you want to specify a certain time unit to execute, then you can use SpecificRule
. which uses at
syntax. Attributes that support SpecificRule
include week
, year
, month
, day
, hour
, minute
. Here are a few
examples of SpecificRule
usage.
# execute at 10 o'clock
t.hour = at 10
t.minute = at 0
DateListRule
If you want to specify one or more dates to execute the task, you can use DateListRule
, which uses date
syntax. Only
date
attribute support DateListRule
. Here is an example of DateListRule
.
# execute at 2023-10-1, 2023-10-15, 2023-10-30
t.date = date "2023-10-1", "2023-10-15", "2023-10-30"
TimeListRule
If you want to specify one or more times to execute the task, you can use TimeListRule
, which uses time
syntax. Only
time
attribute support TimeListRule
. Here is an example of TimeListRule
.
# execute at 10:00:00, 11:00:00, 12:00:00
t.time = time "10:00:00", "11:00:00", "12:00:00"
LoopRule
If you want to control the number of executions of tasks, you can use LoopRule
, which uses loop
syntax. Only loop
attribute support
LoopRule
. Here is an example of LoopRule
.
# only execute 5 times
t.loop = loop 5
StartPointBoundaryRule
If you want to set the earliest time when the task will be executed for the first time, then you can use
StartPointBoundaryRule
, which uses from
syntax. Only start_point
attribute support StartPointBoundaryRule
. Here
is an example of StartPointBoundaryRule
.
# the task will start from 2023-10-1 10:00:00 at the earliest
t.start_point = from "2023-10-1: 10:00:00"
EndPointBoundaryRule
If you want to prevent tasks from executing after a certain time, then you can use EndPointBoundaryRule
, which uses
to
syntax. Only end_point
attribute support EndPointBoundaryRule
. Here is an example of EndPointBoundaryRule
.
# the task will end after 2023-10-1 10:00:00
t.end_point = to "2023-10-1: 10:00:00"
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/baochuquan/taskloop.
License
Taskloop is released under the MIT license.