mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
145 lines
4.1 KiB
Text
145 lines
4.1 KiB
Text
Rules System
|
|
============
|
|
A rule system should be able to evaluate conditions and perform actions, which
|
|
include continuing to process rules, or stopping. The conditions will need to
|
|
access configuration, exclusions, and tracking data.
|
|
|
|
- A constraint on total tracking time, "do not spend more than 4 hours on x".
|
|
- A constraint that only allows certain tags to be used together, to prevent
|
|
client 1 from being billed for project 2.
|
|
- A constraint that only allows multiples of 15-minute intervals.
|
|
|
|
Ref: http://martinfowler.com/bliki/RulesEngine.html
|
|
|
|
Instead of configuration, a rules system stores various settings and
|
|
configuration data as rules. There are several different types of rules, which
|
|
are loaded at launch time, and applied at various times during execution.
|
|
|
|
Some rules can be manipulated at the command line ('exclusions'), but most will
|
|
require editing the rules file. It is not intended that new users edit the
|
|
rules file, therefore some rules are automatically maintained from the command
|
|
line.
|
|
|
|
The rules are a mechanism to apply late-bound logic and data to various
|
|
functions. Whenever data changes, the rule system is run, which will run each
|
|
rule in turn, if it applies, going from top to bottom in the rules file. There
|
|
are no chained rules, but errors will terminate rule processing and program
|
|
execution.
|
|
|
|
As much functionality as possible is to be deferred to the rules.
|
|
|
|
|
|
Format
|
|
------
|
|
The rules are written in a UTF8 text file, in a known location. Other rules
|
|
files may be included:
|
|
|
|
import /path/to/other/rules
|
|
|
|
The syntax of rules is Python-like, in that indentation is significant.
|
|
|
|
Types of Rules
|
|
--------------
|
|
There are several different types of rules, for example there is the rule that
|
|
defines all exclusions:
|
|
|
|
define exclusions:
|
|
...
|
|
|
|
There are general rules triggered by changes to the data:
|
|
|
|
define rule one:
|
|
...
|
|
|
|
There are rules that define tags and their metadata:
|
|
|
|
define tag "tag1":
|
|
...
|
|
|
|
|
|
Rule Type: Exclusions
|
|
---------------------
|
|
Because exclusions are resolved at run time, and only when needed, they should
|
|
be stored in a form very close to the command line syntax, with no expansion.
|
|
For example:
|
|
|
|
$ timew define workweek mon - fri
|
|
|
|
Should be stored in a rule, whose purpose is to return a set of exclusion
|
|
intervals:
|
|
|
|
define exclusions:
|
|
include workweek mon,tue,wed,thu,fri
|
|
|
|
Further definitions will build on this rule:
|
|
|
|
$ timew define workday start 8:30am
|
|
|
|
Yields a combined:
|
|
|
|
define exclusions:
|
|
interval workweek mon,tue,wed,thu,fri
|
|
interval workday start 8:30am
|
|
|
|
Possible exclusions include:
|
|
|
|
$ timew define holidays eng-USA
|
|
$ timew define workweek mon-fri
|
|
$ timew define workday start 8:30am
|
|
$ timew define workday end 1730
|
|
$ timew define workday tue end 3pm
|
|
|
|
Yielding:
|
|
|
|
define exclusions:
|
|
interval holidays eng-USA
|
|
interval work 2015-11-26
|
|
interval workweek mon,tue,wed,thu,fri
|
|
interval workday start 8:30am
|
|
interval workday end 1730
|
|
interval workday tue end 3pm
|
|
|
|
|
|
Rule Type: General
|
|
------------------
|
|
There are rules triggered by changes to the data. In this example, rule 'one'
|
|
is a constraint that prevents the value 'foo' from exceeding three. It is
|
|
triggered by a change to 'foo', which is a DOM reference, and can prevent the
|
|
update by failing:
|
|
|
|
define rule one:
|
|
tagset tag1
|
|
if foo > 3:
|
|
error "The value of 'foo' may not exceed 3."
|
|
|
|
Note that this rule is defined as applying to the tagset 'tag1'.
|
|
|
|
|
|
Rule Type: Tag
|
|
--------------
|
|
A defined tag is a way to associate metadata with a tag, such as a description
|
|
and start/end dates for use:
|
|
|
|
define tag "tag1":
|
|
description "Description of tag1"
|
|
start 2016-01-01
|
|
end 2016-06-30
|
|
budget 20 hours per week
|
|
budget 400 hours total
|
|
|
|
|
|
Built-in Functions
|
|
------------------
|
|
There are several built-in functions, which may be used by rules:
|
|
|
|
error("...") Logs, emits and terminates
|
|
warning("...") Logs, emits and continues
|
|
info("...") Logs, emits and continues
|
|
log("...") Logs and continues
|
|
sum_week("tag1") Sums minutes in the current week for "tag1"
|
|
|
|
---
|
|
|
|
- Need to distinguish between regular time and over time, with different rates
|
|
and limits.
|
|
|