taskloop 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe54ad9d9bfec60de30dcda7607bae029880697f8e3300f3d8f5ca720d1e3b61
-  data.tar.gz: 1963fb584f8fbb3fdde0d72008a19a3c8568c0b4fe3dc5939a3df22360370cee
+  metadata.gz: 83ec59acf2460d59fa1f95974b90e3a5944dd41deb44a17969f82d283c475f39
+  data.tar.gz: f6e98ab37a5933243b2b3c8275c4295553aa83da0bb41e971ee9c4515c1d4f50
 SHA512:
-  metadata.gz: 534de276e8ced9600bbecc3f7a07a4de578d3addee053ddcacacad7b284e9e59b40f9bde0cd309a2075e0f5ff3692f8c2fc38a9ff08ccedabfae933c792d5e52
-  data.tar.gz: 529cdbe0ea94872d8960fba3a1b7eba0520d5bd2b0d09ae5f1319c698b20fc63c9d6acb957c0f239e0958e58f0f908531c26caed504956b6c4ae73eaf70f51e4
+  metadata.gz: 24074e16853283c1a33d9ccc177ef5dd13ae3202f14e09e735699ce8f02b29c499c3c00e0aec78416ae2521d79922896bc7f75fcc29d4af20e817b5dffefe60f
+  data.tar.gz: 9e5ca8fce4a681a12f2d7d91cef006932bd62daf6319186a30c1885c133997f67df38a6d370b9ed6693003f42ff9f283b1bfa621ce4628cbbdc2d2e2563dd1e3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    taskloop (0.2.0)
+    taskloop (0.3.0)
       claide (~> 1.0.3)
 
 GEM

data/README-cn.md

@@ -0,0 +1,273 @@
+![](https://chuquan-public-r-001.oss-cn-shanghai.aliyuncs.com/sketch-images/taskloop-logo-white.png?x-oss-process=image/resize,w_800)
+
+[![Platforms](https://img.shields.io/badge/Platforms-macOS_Linux-yellowgreen)](https://img.shields.io/badge/Platforms-macOS_Linux-Green)
+[![License](https://img.shields.io/badge/License-MIT-orange)](https://img.shields.io/badge/License-MIT-orange)
+[![Gem](https://img.shields.io/badge/Gem-0.3.0-blue)](https://img.shields.io/badge/Gem-0.3.0-blue)
+
+[English](https://github.com/baochuquan/taskloop/README.md)
+
+Taskloop 是一款基于 crontab 进行了优化的定时任务管理器。
+
+与 crontab 相比，taskloop 提供了更加语义化的语法规则。除了支持 crontab 语法之外，taskloop 还实现了一些扩展，比如循环次数、开始/结束时间、日志查询、环境
+变量导入等。
+
+# Features
+
+- [x] 环境变量导入/删除/查看
+- [x] 任务日志查询，taskloop 日志查询
+- [x] 任务发布/撤销
+- [x] 全局开关支持 taskloop 启动/关闭
+- [x] 语义化的语法规则
+    - [x] time specific rule
+    - [x] time scope rules
+        - [x] before scope rule
+        - [x] between scope rule
+        - [x] after scope rule
+    - [x] time interval rule
+    - [x] loop count rule
+    - [x] execution boundary rules
+        - [x] start point boundary rule
+        - [x] end point boundary rule
+    - [x] date list rule
+    - [x] time list rule
+
+# Installation
+
+安装 gem 并通过执行以下命令将其添加到应用程序的 Gemfile 中：
+
+    $ bundle add taskloop
+
+如果没有使用 bundler 来管理依赖项，请通过执行以下命令安装 gem：
+
+    $ gem install taskloop
+
+# Usage
+Taskloop 提供了一系列工作流命令，以及一组语法规则供用户自定义任务。
+
+在使用 taskloop 时，我们建议你使用 git 项目或本地目录来管理所有定时任务。这并不意味着你必须将任务管理集中在一个地方。你可以使用多个 git
+项目或目录来管理不同类型的定时任务。Taskloop 支持这些不同的管理方式。这些只是建议而已。
+
+接下来介绍一下 taskloop 的标准工作流程。
+
+## 启动
+在开始使用 taskloop 之前，您需要执行 `taskloop launch` 命令来全局启动 taskloop。
+
+相应的，taskloop 也提供了一个 `taskloop shutdown` 命令来支持全局关闭 taskloop。
+
+## 初始化 Taskfile
+Taskfile 用于描述自定义任务，一个 Taskfile 中可以描述多个任务。因此，我们可以在目录下执行 `taskloop init` 命令来生成 Taskfile，并在
+Taskfile 中描述具体的定时任务。
+
+## 自定义定时任务
+执行 `taskloop init` 命令后，会在当前目录下自动生成一个 Taskfile 模板文件。模板文件展示了如何描述任务，包括为每个任务指定哪些属性、哪些属性是
+必需的、哪些属性是可选的。
+
+如下所示是 Taskfile 模板文件：
+```shell
+# 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
+```
+
+在文件的开头，我们可以使用 `env` 语法为 Taskfile 中的任务定义环境变量。
+
+`env` 语法有两个参数，第一个是环境变量的名称，第二个是环境变量的值。我们可以多次使用 `env` 语法来定义多个环境变量。这些环境变量可以被 Taskfile
+中的所有任务共享。
+
+```shell
+env <ENV_NAME1> <ENV_VALUE1>
+env <ENV_NAME2> <ENV_VALUE2>
+env <ENV_NAME3> <ENV_VALUE3>
+...
+```
+
+每个任务都需要使用 `TaskLoop::Task.new` 语法进行初始化，并在 `do` 闭包中设置属性。任务有两个必需属性，`name` 和 `path`，其余属性是可选属
+性。如果未设置任何可选属性，那么任务将每分钟执行一次。
+
+关于可选属性，有些属性支持多种规则，但不同时支持多个规则。如果在任务描述中多次设置某个属性，则最后一次设置将覆盖之前的所有设置。
+
+`week` 属性支持两种规则：`ScopeRule` 和 `SpecificRule`。设置 `week` 属性时，必须使用 taskloop 预定义的符号，如：`:Sun` 表示星期天。
+这些符号的具体定义可以查看 `lib/taskloop/task/task_property.rb` 中 `WEEK` 的定义。
+
+`year` 属性支持三种规则：`ScopeRule`、`SpecificRule` 和 `IntervalRule`。设置 `year` 属性时，可以直接使用数字来表示年份或间隔年数。关于
+年份属性，taskloop 中没有预定义的符号。
+
+`month` 属性支持三种规则：`ScopeRule`、`SpecificRule` 和 `IntervalRule`。定义 `month` 属性时，必须使用预定义的月份符号来设置 
+`ScopeRule` 和 `SpecificRule`，例如：`:Aug` 表示八月。 对于 `IntervalRule`，直接使用数字即可，用于表示间隔的月数。这些符号的具体定义可以
+查看 `lib/taskloop/task/task_property.rb` 中 `MONTH` 的定义。
+
+`day` 属性支持三种规则：`ScopeRule`、`SpecificRule` 和 `IntervalRule`。其表示月份中的第几天，taskloop 为其预定义了符号，如：`:day7` 
+表示某月的第 7 天，依此类推。对于这些符号的具体定义，可以查看 `lib/taskloop/task/task_property.rb` 中 `DAY` 的定义。
+
+`hour` 属性支持三种规则：`ScopeRule`、`SpecificRule` 和 `IntervalRule`。当你设置 `hour` 属性时，你可以直接使用数字来表示小时值或间隔小
+时数。
+
+`minute` 属性支持三种规则：`ScopeRule`、`SpecificRule` 和 `IntervalRule`。当你设置 `minute` 属性时，你可以直接使用数字来表示分钟值或间
+隔分钟数。
+
+`date` 属性也用于设置日期。当你对 `year`、`month` 和 `day` 属性使用 `SpecificRule` 时，请不要同时设置 `date` 属性。当你为 `year`、
+`month` 和 `day` 属性设置 `SpecificRule` 时， 只能设置一个日期，但是当你使用 `date` 属性时，你可以设置一系列日期。这种可以设置一系列日期的
+规则在任务循环中称为 `DateListRule`。在使用 `DateListRule` 时，可以传入一系列代表日期的字符，例如：“2023-8-1”。
+
+`time` 属性也用于设置时间。当你对 `hour` 和 `minute` 属性使用 `SpecificRule` 时，请不要同时设置 `time` 属性。当你为 `hour` 和 
+`minute` 属性设置 `SpecificRule` 时，只能设置一个时间，但是当你使用 `time` 属性时，你可以设置一个时间列表。这种可以设置时间列表的规则在
+taskloop 中被称为 `TimeListRule`。使用 `TimeListRule` 时，可以传入一系列代表时间的字符，例如：“10:00:00”。
+
+`loop` 属性用于指示定时任务的执行次数，其唯一支持的规则为 `LoopRule`。使用 `LoopRule` 时，只需要传入一个表示执行次数的数字即可。
+
+`start_point` 属性用于指示任务最早执行时间，它支持的规则是为 `StartPointBoundaryRule`。使用 `StartPointBoundaryRule` 时，需要传入表示
+开始时间的字符串，如：“2023-10-1 10:00:00”。
+
+`end_point` 属性用于指示任务的最后执行时间，它支持的规则称为 `EndPointBoundaryRule`。使用 `EndPointBoundaryRule` 时，需要传入表示结束
+时间的字符串，如：“2023-10-30 10:00:00”。
+
+## Deploy
+在定义或修改 Taskfile 后，你可以执行 `taskloop deploy` 命令进行部署。部署成功后，taskloop 才会真正按照你定义的规则去执行定时任务。
+
+如果部署 Taskfile 后发现问题，可以重新编辑并再次部署。或者也可以直接通过 `taskloop undeploy` 命令取消部署，从而避免造成严重后果。
+
+# Advanced Usage
+## 环境变量
+关于环境变量，Taskfile 支持定义本地环境变量。此外，taskloop 还提供 `taskloop env` 命令来支持导入/删除/查看环境变量。例如：
+
+```shell
+# 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
+```
+
+## 任务列表
+如果我们想查看 taskloop 中正在运行哪些计划任务，这时候我们可以使用 `taskloop list` 命令。如下所示：
+
+```shell
+$ taskloop list
+```
+
+## 日志查询
+如果我们想查询任务的执行日志，可以使用 `taskloop log` 命令，它支持查看特定任务的日志和系统的日志。如下所示：
+
+```shell
+# 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
+通过上文，我们知道任务的不同属性对应着不同的规则。接下来介绍一下这些规则的具体用法。
+
+## IntervalRule
+如果你想每隔一段时间执行一个任务，你需要使用 `IntervalRule`。支持 `IntervalRule` 的属性包括 `year`、`month`、`day`、`hour`、`minute`。
+当你在不同的属性上使用 `IntervalRule` 时，它们的单位是不同的，最终 taskloop 会组合计算出它们执行任务的时间间隔。
+
+`IntervalRule` 的语法是 `interval`，`IntervalRule` 的使用示例如下所示。
+
+```ruby
+# 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
+如果你想指定在某个时间范围内执行的任务，那么你可以使用 `ScopeRule`。事实上，`ScopeRule` 包含三种特定类型的规则，分别是 `BeforeScopeRule`、
+`BetweenScopeRule`、`AfterScopeRule`。支持 `ScopeRule` 的属性包括 `week`、`year`、`month`、`day`、`hour`、`min`。以下是
+`ScopeRule` 用法的一些示例。
+
+```ruby
+# 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
+如果你想指定某个时间单位来执行，那么你可以使用 `SpecificRule`。其使用 `at` 语法。支持 `SpecificRule` 的属性包括 `week`、`year`、`month`、
+`day`、`hour`、`min`。以下是 `SpecificRule` 用法的一些示例。
+
+```ruby
+# execute at 10 o'clock
+t.hour = at 10
+t.minute = at 0
+```
+
+## DateListRule
+如果要指定一个或多个日期来执行任务，可以使用 `DateListRule`，它使用 `date` 语法。仅 `date` 属性支持 `DateListRule`。以下是 `DateListRule` 
+的示例。
+
+```ruby
+# execute at 2023-10-1, 2023-10-15, 2023-10-30
+t.date = date "2023-10-1", "2023-10-15", "2023-10-30"
+```
+
+## TimeListRule
+如果要指定执行一次或多次任务，可以使用 `TimeListRule`，它使用 `time` 语法。只有 `time` 属性支持 `TimeListRule`。以下是 `TimeListRule`
+的示例。
+
+```ruby
+# execute at 10:00:00, 11:00:00, 12:00:00
+t.time = time "10:00:00", "11:00:00", "12:00:00"
+```
+
+## LoopRule
+如果你想控制任务的执行次数，可以使用 `LoopRule`，它使用 `loop` 语法。只有 `loop` 属性支持 `LoopRule`。以下是 `LoopRule` 的示例。
+
+```ruby
+# only execute 5 times
+t.loop = loop 5
+```
+
+## StartPointBoundaryRule
+如果你希望任务在特性时间之后开始执行，那么你可以使用 `StartPointBoundaryRule`，它使用 `from` 语法。仅 `start_point` 属性支持 
+`StartPointBoundaryRule`。以下是 `StartPointBoundaryRule` 的示例。
+
+```ruby
+# 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
+如果你希望任务在特定时间后停止执行，那么你可以使用 `EndPointBoundaryRule`，它使用 `to` 语法。仅 `end_point` 属性支持 `EndPointBoundaryRule`。
+以下是 `EndPointBoundaryRule` 的示例。
+
+```ruby
+# the task will end after 2023-10-1 10:00:00
+t.end_point = to "2023-10-1: 10:00:00"
+```
+
+# Contributing
+欢迎在 GitHub 上提交 issue 和 PR：https://github.com/baochuquan/taskloop。
+
+# License
+Taskloop 在 MIT 许可证下发布。 
+

data/README.md

@@ -1,12 +1,38 @@
-![](https://chuquan-public-r-001.oss-cn-shanghai.aliyuncs.com/sketch-images/taskloop-logo-white.png)
+![](https://chuquan-public-r-001.oss-cn-shanghai.aliyuncs.com/sketch-images/taskloop-logo-white.png?x-oss-process=image/resize,w_800)
 
-# Taskloop
+[![Platforms](https://img.shields.io/badge/Platforms-macOS_Linux-yellowgreen)](https://img.shields.io/badge/Platforms-macOS_Linux-Green)
+[![License](https://img.shields.io/badge/License-MIT-orange)](https://img.shields.io/badge/License-MIT-orange)
+[![Gem](https://img.shields.io/badge/Gem-0.3.0-blue)](https://img.shields.io/badge/Gem-0.3.0-blue)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/taskloop`. To experiment with that code, run `bin/console` for an interactive prompt.
+[简体中文](https://github.com/baochuquan/taskloop/blob/main/README-cn.md)
 
-TODO: Delete this and the text above, and describe your gem
+Taskloop is a scheduled task manager optimized based on crontab. 
 
-## Installation
+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
+
+- [x] Environment variable import/remove/list
+- [x] Task log query, taskloop log query
+- [x] Task deploy/undeploy
+- [x] Global switch to enable/disable taskloop
+- [x] user-friendly and semantic syntax rules
+  - [x] time specific rule
+  - [x] time scope rules
+    - [x] before scope rule
+    - [x] between scope rule
+    - [x] after scope rule
+  - [x] time interval rule
+  - [x] loop count rule
+  - [x] execution boundary rules
+    - [x] start point boundary rule
+    - [x] end point boundary rule
+  - [x] date list rule
+  - [x] time list rule
+
+# Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
@@ -16,16 +42,261 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install taskloop
 
-## Usage
+# 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:
+```shell
+# 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.
+
+```shell
+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:
+
+```shell
+# 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:
+
+```shell
+$ 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:
+
+```shell
+# 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.
+
+```ruby
+# 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.
+
+```ruby
+# 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.
+
+```ruby
+# 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`.
+
+```ruby
+# 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`.
+
+```ruby
+# 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`.
+
+```ruby
+# 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`.
 
-TODO: Write usage instructions here
+```ruby
+# the task will start from 2023-10-1 10:00:00 at the earliest
+t.start_point = from "2023-10-1: 10:00:00"
+```
 
-## Development
+## 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`.
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+# the task will end after 2023-10-1 10:00:00
+t.end_point = to "2023-10-1: 10:00:00"
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/baochuquan/taskloop.
 
-## Contributing
+# License
+Taskloop is released under the MIT license. 
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/taskloop.

data/lib/taskloop/command/env.rb

@@ -6,7 +6,7 @@ module TaskLoop
 
     self.description = <<-DESC
       The `taskloop env` command can be used to deal with global environment variable related operations. 
-      For example, you can export environment variables into taskloop with `--global-export=VAR1,VAR2...` options.
+      For example, you can export environment variables into taskloop with `--import=VAR1,VAR2...` options.
       Beside, you can list all the global environment variables exported in taskloop.
       All above operations are based on ~/.taskloop/environments file. If you want more details about global environment
       variables, check and edit ~/.taskloop/environments by yourself.
@@ -14,14 +14,14 @@ module TaskLoop
 
     def self.options
       [
-        ['--global-import=VAR1,VAR2...', 'Import one or more global environment variables into taskloop.'],
-        ["--global-remove=VAR1,VAR2...", 'Remove one or more global environment variables from taskloop.']
+        ['--import=VAR1,VAR2...', 'Import one or more global environment variables into taskloop.'],
+        ["--remove=VAR1,VAR2...", 'Remove one or more global environment variables from taskloop.']
       ].concat(super)
     end
 
     def initialize(argv)
-      @import = argv.option('global-import')
-      @remove = argv.option('global-remove')
+      @import = argv.option('import')
+      @remove = argv.option('remove')
       super
     end
 

data/lib/taskloop/command/init.rb

@@ -26,15 +26,18 @@ module TaskLoop
 
 TaskLoop::Task.new do |t|
   t.name        = 'TODO: task name. <Required>'
-  t.path        = 'TODO: task job path. For exmaple, t.path = "./Job.sh". <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: start point boundary rule. <Optional"
+  t.start_point = "TODO: start point boundary rule. <Optional>"
+  t.end_point   = "TODO: end point boundary rule. <Optional>"
 end
       DESC
       file.puts content

data/lib/taskloop/rules/after_scope_rule.rb

@@ -66,11 +66,13 @@ module TaskLoop
       when :month then
         result = current.month >= value
       when :week then
-        result = current.wday >= (value % TaskLoop::WEEK_BASE)
+        result = current.wday >= value
       when :day then
         result = current.day >= value
       when :hour then
         result = current.hour >= value
+      when :minute then
+        result = current.min >= value
       end
       return result
     end

data/lib/taskloop/rules/before_scope_rule.rb

@@ -65,11 +65,13 @@ module TaskLoop
       when :month then
         result = current.month <= value
       when :week then
-        result = current.wday <= (value % TaskLoop::WEEK_BASE)
+        result = current.wday <= value
       when :day then
         result = current.day <= value
       when :hour then
         result = current.hour <= value
+      when :minute then
+        result = current.min <= value
       end
       return result
     end

data/lib/taskloop/rules/between_scope_rule.rb

@@ -105,11 +105,13 @@ module TaskLoop
       when :month then
         result = left <= current.month && current.month <= right
       when :week then
-        result = (left % TaskLoop::WEEK_BASE) <= current.wday && current.wday <= (right % TaskLoop::WEEK_BASE)
+        result = left <= current.wday && current.wday <= right
       when :day then
         result = left <= current.day && current.day <= right
       when :hour then
         result = left <= current.hour && current.hour <= right
+      when :minute then
+        result = left <= current.min && current.min <= right
       end
       return result
     end

data/lib/taskloop/rules/rule.rb

@@ -3,7 +3,7 @@ module TaskLoop
 
     UNIT = {
       :unknown     => 0,
-      :minute      => 1,      # support interval/specific syntax
+      :minute      => 1,      # support interval/scope/specific syntax
       :hour        => 2,      # support interval/scope/specific syntax
       :day         => 3,      # support interval/scope/specific syntax
       :month       => 4,      # support interval/scope/specific syntax

data/lib/taskloop/rules/specific_rule.rb

@@ -39,7 +39,7 @@ module TaskLoop
       when :month then
         result = vals.include?(current.month)
       when :week then
-        result = vals.include?(TaskLoop::WEEK_BASE + current.wday)
+        result = vals.include?(current.wday)
       when :day then
         result = vals.include?(current.day)
       when :hour then

data/lib/taskloop/task/task.rb

@@ -98,10 +98,7 @@ module TaskLoop
               break
             end
           end
-
         end
-
-
       end
 
       if has_ymd? && has_time?

data/lib/taskloop/task/task_property.rb

@@ -222,9 +222,16 @@ module TaskLoop
     # interval syntax
     #   - interval
     #     - example: interval 5.minute
+    # scope syntax
+    #   - before
+    #     - example: before 9
+    #   - between
+    #     - example: between 10, 12
+    #   - after
+    #     - example: after 11
     def minute=(rule)
-      unless rule.is_a?(SpecificRule) || rule.is_a?(IntervalRule)
-        raise TypeError, "the rule of minute must be SpecificRule or IntervalRule"
+      unless rule.is_a?(SpecificRule) || rule.is_a?(ScopeRule)  || rule.is_a?(IntervalRule)
+        raise TypeError, "the rule of minute must be SpecificRule or ScopeRule or IntervalRule"
       end
       @minute = rule
       @minute.unit = :minute

data/lib/taskloop/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TaskLoop
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/sig/task_loop/task_property.rbs

@@ -56,9 +56,9 @@ module TaskLoop
 
     def loop_count: () -> Integer
 
-    def minute: () -> [SpecificRule | IntervalRule]
+    def minute: () -> [SpecificRule | ScopeRule | IntervalRule]
 
-    def minute=: ([SpecificRule | IntervalRule]) -> void
+    def minute=: ([SpecificRule | ScopeRule | IntervalRule]) -> void
 
     def month: () -> [SpecificRule | ScopeRule | IntervalRule | DefaultRule]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taskloop
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - baochuquan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-31 00:00:00.000000000 Z
+date: 2023-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: claide
@@ -39,6 +39,7 @@ files:
 - ".idea/vcs.xml"
 - Gemfile
 - Gemfile.lock
+- README-cn.md
 - README.md
 - Rakefile
 - exe/taskloop