mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
Apply 'one sentence, one line'
Signed-off-by: Thomas Lauf <thomas.lauf@tngtech.com>
This commit is contained in:
Thomas Lauf
parent
a30a2a1a8b
commit
0d56d1c790
1 changed files with 32 additions and 53 deletions
|
|
@ -1,31 +1,26 @@
|
|||
Rules System
|
||||
============
|
||||
The Timewarrior rule system reads your timewarrior.cfg file and
|
||||
uses the combination of configuration settings and logic within to:
|
||||
The Timewarrior rule system reads your timewarrior.cfg file and uses the combination of configuration settings and logic within to:
|
||||
|
||||
- Define configuration and customization details
|
||||
- Define tags, exclusions, constraints
|
||||
- Define various policies
|
||||
|
||||
On non-Unix systems config file is expected in ~/.timewarrior directory.
|
||||
On Unix systems, if legacy ~/.timewarrior directory doesn't exist, config is
|
||||
read from $XDG_CONFIG_HOME/timewarrior directory (if not specified,
|
||||
$XDG_CONFIG_HOME defaults to ~/.config).
|
||||
On Unix systems, if legacy ~/.timewarrior directory doesn't exist, config is read from $XDG_CONFIG_HOME/timewarrior directory (if not specified, $XDG_CONFIG_HOME defaults to ~/.config).
|
||||
|
||||
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 be able to terminate rule processing and
|
||||
program execution.
|
||||
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 be able to terminate rule processing and program execution.
|
||||
|
||||
As much functionality as possible is to be deferred to the rules system, which
|
||||
will initially be minimal, but grow to become more capable.
|
||||
As much functionality as possible is to be deferred to the rules system, which will initially be minimal, but grow to become more capable.
|
||||
|
||||
|
||||
Format
|
||||
------
|
||||
The rules are written as UTF8 text in the timewarrior.cfg text file. Other
|
||||
rules files may be included:
|
||||
The rules are written as UTF8 text in the timewarrior.cfg text file.
|
||||
Other rules files may be included:
|
||||
|
||||
import /path/to/other/rule/file
|
||||
|
||||
|
|
@ -34,8 +29,7 @@ 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:
|
||||
There are several different types of rules, for example there is the rule that defines all exclusions:
|
||||
|
||||
define exclusions:
|
||||
...
|
||||
|
|
@ -60,8 +54,7 @@ There are rules that will serve as hooks:
|
|||
|
||||
Rule Type: Exclusions
|
||||
---------------------
|
||||
Because exclusions are resolved at run time, and only when needed, they should
|
||||
be stored in a readily-interpreted form:
|
||||
Because exclusions are resolved at run time, and only when needed, they should be stored in a readily-interpreted form:
|
||||
|
||||
define exclusions:
|
||||
monday = <8:00:00 12:00:00-12:45:00 >17:30:00
|
||||
|
|
@ -74,17 +67,15 @@ be stored in a readily-interpreted form:
|
|||
2016_01_01 = Working
|
||||
2016_01_02 = Off
|
||||
|
||||
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.
|
||||
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:
|
||||
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 rules:
|
||||
one:
|
||||
|
|
@ -97,8 +88,7 @@ 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:
|
||||
A defined tag is a way to associate metadata with a tag, such as a description and start/end dates for use:
|
||||
|
||||
define tags:
|
||||
"tag1":
|
||||
|
|
@ -112,8 +102,7 @@ and start/end dates for use:
|
|||
|
||||
Rule Type: Theme
|
||||
----------------
|
||||
A color theme is defined by a rule, and consists of color definitions for
|
||||
various report and feedback elements:
|
||||
A color theme is defined by a rule, and consists of color definitions for various report and feedback elements:
|
||||
|
||||
define theme:
|
||||
description = "A monochrome, 256-color theme"
|
||||
|
|
@ -125,20 +114,16 @@ various report and feedback elements:
|
|||
color2 = "white on blue"
|
||||
...
|
||||
|
||||
The palette group is a list (more is better) of themed colors for use when auto-
|
||||
coloring tags.
|
||||
The palette group is a list (more is better) of themed colors for use when auto-coloring tags.
|
||||
|
||||
There is only one theme namespace, so if multiple themes are imported, the last
|
||||
one can override all the prior theme settings. This means themes can be layered,
|
||||
but they would need to be designed for this.
|
||||
There is only one theme namespace, so if multiple themes are imported, the last one can override all the prior theme settings.
|
||||
This means themes can be layered, but they would need to be designed for this.
|
||||
|
||||
|
||||
Rule Type: Hook
|
||||
---------------
|
||||
While there may not be hooks in the traditional sense, with fixed arguments,
|
||||
there will be rules that have the same role. Hook rules will allow an internal
|
||||
event to trigger a rule that calls an external script, and passes an arbitrary
|
||||
set of arguments.
|
||||
While there may not be hooks in the traditional sense, with fixed arguments, there will be rules that have the same role.
|
||||
Hook rules will allow an internal event to trigger a rule that calls an external script, and passes an arbitrary set of arguments.
|
||||
|
||||
[Mechanism TBD]
|
||||
|
||||
|
|
@ -154,8 +139,7 @@ set of arguments.
|
|||
on_modify:
|
||||
...
|
||||
|
||||
These rules can run an external script and provide arguments, based on rules
|
||||
DOM access:
|
||||
These rules can run an external script and provide arguments, based on rules DOM access:
|
||||
|
||||
define rules:
|
||||
on_modify:
|
||||
|
|
@ -164,8 +148,7 @@ DOM access:
|
|||
|
||||
Rules Type: Hint
|
||||
----------------
|
||||
Hints may be defined using the rules system, to augment the built-in hints that
|
||||
are used by almost every command.
|
||||
Hints may be defined using the rules system, to augment the built-in hints that are used by almost every command.
|
||||
|
||||
define hints:
|
||||
staff:
|
||||
|
|
@ -177,8 +160,7 @@ are used by almost every command.
|
|||
|
||||
--- Raw Notes ---
|
||||
|
||||
- Need to distinguish between regular time and over time, with different rates
|
||||
and limits.
|
||||
- Need to distinguish between regular time and over time, with different rates and limits.
|
||||
|
||||
- Policy support involves things like:
|
||||
- warn after 40 hrs/wk
|
||||
|
|
@ -186,8 +168,7 @@ are used by almost every command.
|
|||
- auto-tag intervals that exceed 40 hrs/wk
|
||||
- auto-tag intervals during exclusion time
|
||||
|
||||
- Need to distinguish between rules that will be supported at 1.0.0, and the
|
||||
long term enhancements.
|
||||
- Need to distinguish between rules that will be supported at 1.0.0, and the long term enhancements.
|
||||
|
||||
- There will need to be several built-in functions, for use by rules:
|
||||
|
||||
|
|
@ -198,12 +179,10 @@ are used by almost every command.
|
|||
|
||||
These are not good examples.
|
||||
|
||||
- Need reports to help users doing fixed-rate work - finding the longest task
|
||||
for example.
|
||||
- Need reports to help users doing fixed-rate work - finding the longest task for example.
|
||||
|
||||
- If an interval has more than one tag with a defined color, and is being
|
||||
rendered, then use the first tag color. It doesn't really matter which.
|
||||
|
||||
- Use display granularity/resolution to see more or less details. This would
|
||||
combine nicely with a tag hierarchy. (Tomas Babej)
|
||||
- If an interval has more than one tag with a defined color, and is being rendered, then use the first tag color.
|
||||
It doesn't really matter which.
|
||||
|
||||
- Use display granularity/resolution to see more or less details.
|
||||
This would combine nicely with a tag hierarchy. (Tomas Babej)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue