Docs: Added rules.txt

doc/notes.txt

@@ -69,25 +69,6 @@ access configuration, exclusions, and tracking data.
 
 Ref: http://martinfowler.com/bliki/RulesEngine.html
 
-Example rules (assuming Python-like syntax):
-
-  define rule exclusions:
-    holidays eng-USA
-    workweek mon,tue,wed,thu,fri
-    workday start 510
-    workday end 1050
-    workday tue end 900
-    resolution 1min
-
-  define rule my_rule:
-    if sum_week(+tag1) > 12:
-      fail "The 'tag1' tag cannot exceed 12 hours/wk"
-
-  (needs work)
-
-  The 'sum_week' function is an example of exposed functionality, and there
-  needs to be many of these, in order to make the rule system capable.
-
 
 Tags
 ----
@@ -161,15 +142,6 @@ On that same timeline, here are some example tracked intervals:
                         |
                         now
 
-Here is the example data storage for the above workweek:
-
-      define rule exclusions:
-        holidays eng-USA
-        workweek mon,tue,wed,thu,fri
-        workday start 510
-        workday end 1050
-        workday tue end 900
-
 Time tracking is based on the inclusion intervals derived from the above rule.
 For week 48 those would be:
 
@@ -483,47 +455,6 @@ P: There is a use-case for double tracking.  Suppose I am a manager, and I do th
    Could also define overlap.  This could be implemented using Rules.
 
 
-
-   On to Rules...  The above, written in pseudo-python could be:
-
-   define rule xyz:
-      if tag == “foo” and start > 2015-12-31:
-          fail “tag ‘foo’ only valid until 2015-12-31"
-
-   So what we thought of in tw as configuration, could now be a rule.  This approach covers several configurable settings, and is equivalent to:
-
-   tag.foo.end_date=2015-12-31
-   tag.foo.fail.message=tag ‘foo’ only valid until 2015-12-31
-
-   Same thing.  But a rule has the potential to take multiple actions, or make the condition more complex.  Therefore, more flexible.
-F: So a rule could be invoked “once” after creating it to “translate” these un-explicit dates to real ones.
-   like an activation.
-P: Maybe.  Definitely if ‘EOM’ appears on the command line it gets expanded.  I would think writing EOM in a rule file would be a mistake.
-   Notice that for the rule syntax, “define”, “if” and “fail” are all keywords that take arguments.  Easy to parse/run.
-F: yes.
-   Would timew group rules? Create some “namespace” for rules? So only certain rules are evaluated for certain tags?
-   would there be genereal rules? for all.(edited)
-   rule precedence? ordering of rules?
-   Just asking.(edited)
-P: Yes.  I did a fair amount of reading about rule systems.  Here is briefly what I learned:
-   A rule system is just a way to iterate over a set of data items and apply late-bound logic.  That is, it’s a loop that applies every rule in turn to the subject.
-   You need a way to maybe not run every rule.  This can be done by storing them in memory, having scanned them to see what data is read to trigger them, then using that to filter a subset of the rules to apply.
-   Chaining rules is hard.  Precedence is hard.
-   Having different species of rules is a good idea.
-   in other words, if the rule is:
-
-   define rule one:
-      if foo > 3:
-          fail “Error”
-
-   Then the rule is triggered by a change in foo.  If foo isn’t changing, skip the rule, and assume it ran the last time foo was changed, and will run the next time also.
-   Precedence can be simply top to bottom.
-   Species:
-
-   define rule_type1 abc:
-      ….
-
-
 P: Final topic on my list: Data Format, and it’s very short.
    data is a text file.  one line per day.
    Example:

doc/rules.txt

@@ -0,0 +1,109 @@
+Rules System
+============
+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 rule exclusions:
+    interval workweek mon,tue,wed,thu,fri
+
+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'.
+
+
+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 rule 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 rule exclusions:
+    interval workweek mon,tue,wed,thu,fri
+    interval workday start 8:30am
+
+Possible exclusions include:
+
+  $ timew 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 rule exclusions:
+    interval holidays eng-USA
+    interval workweek mon,tue,wed,thu,fri
+    interval workday start 8:30am
+    interval workday end 1730
+    interval workday tue end 3pm
+
+
+Built-in Functions
+------------------
+There are several built-in functions, which may be used by rules:
+
+  error   "An error occurred"
+  warning "You have been warned"
+  info    "Yuo have been notified"
+
+An error call terminates processing.
+
+  sum_week("tag1")
+
+The 'sum_week' will sum minutes in the current week for the tagset "tag1".
+
+---
+