mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
171 lines
4.6 KiB
Text
171 lines
4.6 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/rule/file
|
|
|
|
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:
|
|
workweek mon,tue,wed,thu,fri
|
|
|
|
Further definitions will build on this rule:
|
|
|
|
$ timew define workday start 8:30am
|
|
|
|
Yields a combined:
|
|
|
|
define exclusions:
|
|
workweek mon,tue,wed,thu,fri
|
|
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:
|
|
holidays eng-USA
|
|
work 2015-11-26
|
|
workweek mon,tue,wed,thu,fri
|
|
workday start 8:30am
|
|
workday end 1730
|
|
workday tue end 3pm
|
|
|
|
If you want to track your lunch breaks, then you would make a tag for it, and
|
|
track it like any other project. If you do not want to track that time, add an
|
|
exclusion for it.
|
|
|
|
|
|
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
|
|
overlap yes
|
|
|
|
|
|
rule Type: Logging
|
|
------------------
|
|
A logoging rule manages all log-related controls:
|
|
|
|
define logging:
|
|
file "/path/to/log"
|
|
debug off
|
|
level info
|
|
|
|
|
|
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.
|
|
|
|
- The general form is:
|
|
|
|
$ timew define A B C
|
|
|
|
define A
|
|
B C
|
|
|
|
- A nice feature would be to define a ':keyword' using the rules, which would
|
|
replace the notion of macros/aliases.
|
|
|