From 2232ff7a210f5b217202e57133b9e21afa435c87 Mon Sep 17 00:00:00 2001
From: Paul Beckingham <paul@beckingham.net>
Date: Tue, 16 Apr 2013 01:23:32 -0400
Subject: [PATCH] Documentation

- Started the new parser documentation.
---
 doc/misc/parser/README          |  77 ++++++++++++++
 doc/misc/parser/expressions.txt |  34 +++++++
 doc/misc/parser/grammar.txt     | 173 ++++++++++++++++++++++++++++++++
 3 files changed, 284 insertions(+)
 create mode 100644 doc/misc/parser/README
 create mode 100644 doc/misc/parser/expressions.txt
 create mode 100644 doc/misc/parser/grammar.txt

diff --git a/doc/misc/parser/README b/doc/misc/parser/README
new file mode 100644
index 000000000..d60806542
--- /dev/null
+++ b/doc/misc/parser/README
@@ -0,0 +1,77 @@
+The main focus of the 2.4.0 release is a new command line parser that has more
+capabilities, and fewer quirks and bugs.
+
+
+Improvements needed:
+
+- Assorted quoting issues.  If this command is issued, then the quoting should
+  be obeyed:
+
+    task add one project:'Bob\'s Project'
+    task add "one 'two' three"
+    task add 'one "two" three'
+    task add 'one \'two\' three'
+    task add "one \"two\" three"
+
+- The process of splitting and rejoining tokens causes this kind of problem:
+
+    "one (two) three" --> "one ( two) three"
+
+- Any formatting in the input that makes it past the shell should be preserved.
+
+- The '--' token should faithfully cause no further parsing - lexing only.
+
+- The ability to perform simple math:
+
+    task add one due:eoy wait:due-2wks scheduled:wait-1wk
+
+  When processed left to right, this command has referential integrity.
+
+- An attribute value must be a single argument, but can be presented in several
+  equivalent ways:
+
+    wait:due-2wks
+    wait:'due-2wks'
+    wait:"due-2wks'
+    wait:"due -2wks'
+    wait:"due - 2wks'
+    wait:due\ -\ 2wks
+
+
+Grammar:
+
+To achieve the above, a formal grammar will be developed, otherwise a hand-
+crafted parser is going to be unmaintainable.  See the grammar.txt file for the
+formal definition.
+
+This grammar.txt will be embedded into task as a single-string document, then
+itself parsed and used.  This has several advantages:
+
+- It allows the grammar to be discussed in its purest form, with an
+  authoritative document as a definition.
+- It allows the grammar to be tweaked at a high level without code changes.
+- It allows a developer to experiment with grammar.
+
+
+Expressions:
+
+The expression evaluator will be capable of applying any supported filter.
+
+The expression evaluator will also be capable of evaluating fragments of output
+from the parser, yielding a single value.  As an example, the command line:
+
+  task add one due:eoy wait:due-2wks
+
+Is parsed as:
+
+  raw     | add     one    due:eoy    wait:due-2wks
+  type    | command string attr       attr
+  subtype | read
+  attr    |         desc   due        wait
+  value   |                eval 'eoy' eval 'due-2wks'
+
+The eval needs of this command are:
+
+  'eoy'      == date literal
+  'due-2wks' == <dom> - <duration>
+
diff --git a/doc/misc/parser/expressions.txt b/doc/misc/parser/expressions.txt
new file mode 100644
index 000000000..2a125e48b
--- /dev/null
+++ b/doc/misc/parser/expressions.txt
@@ -0,0 +1,34 @@
+The expression evaluator allows powerful filters and modifications.
+
+There are four data types, just like UDAs:
+
+    string             project, description
+    date               due, wait ...
+    duration           recur
+    numeric            urgency
+
+There are several forms of literals:
+
+    rc.name            configuration
+    <dom>              task-specific data
+    <numeric>          numbers
+    <date>             either ISO-8601 or rc.dateformat dates
+    <duration>         either ISO-8601 or durations
+
+There are several supported operators:
+
+    +                  addition, concatenation
+    -                  subtraction, unary minus
+    *                  multiplication
+    /                  division
+    ( )                precedence
+    and or xor not !  logical operators
+    < <= > >=          relation operators
+    = !=               equality operators
+    ~ !~               match operators
+
+There are also helper operators to perform odd operations:
+
+    __hastag__         presence of a tag
+    __notag__          absence of a tag
+
diff --git a/doc/misc/parser/grammar.txt b/doc/misc/parser/grammar.txt
new file mode 100644
index 000000000..0470f7038
--- /dev/null
+++ b/doc/misc/parser/grammar.txt
@@ -0,0 +1,173 @@
+The command line needs to obey a grammar.  It is then against this grammar that
+bugs will be identified.
+
+Conventions:
+  - Literals are double-quoted.
+  - "*", "+" and "?" suffixes have POSIX semantics.
+  - Low-level primitives are in <brackets>.
+  - @reports for dynamic lists such as custom report names.
+
+
+The general form of commands is:
+
+  task [ all-commands ]
+
+
+This breaks down into a supported grammar:
+
+  command         ::= all-commands?
+                    ;
+
+  all-commands    ::= custom-report
+                    | read-command
+                    | write-command
+                    | special-command
+                    ;
+
+  custom-report   ::= filter? @report ;
+  read-command    ::= ;
+  write-command   ::= ;
+  special-command ::= ;
+
+  filter          ::= expression ;
+
+  expression      ::= ;
+
+Dynamic lists:
+
+  @report         ::= all custom reports ;
+
+Low-level:
+
+  dom             ::= context-value
+                    | system-value
+                    | rc-value
+                    | task-value
+                    ;
+
+  context-value   ::= "context.program"
+                    | "context.args"
+                    | "context.width"
+                    | "context.height"
+                    ;
+
+  system-value    ::= "system.version"
+                    | "system.os"
+                    ;
+
+  rc-value        ::= "rc." name
+                    ;
+
+  task-value      ::= <id> "." attribute
+                    | <uuid> "." attribute
+                    ;
+             
+  literal         ::= <string>
+                    | <numeric>
+                    | <date>
+                    | <duration>
+                    ;
+
+Supported primitives:
+
+  <id>
+  <uuid>
+  <override>
+  <string>
+  <numeric>
+  <date>
+  <duration>
+
+
+
+---
+
+Default:
+  task
+
+Custom reports:
+  task <filter> active
+  task <filter> all
+  task <filter> blocked
+  task <filter> blocking
+  task <filter> completed
+  task <filter> list
+  task <filter> long
+  task <filter> ls
+  task <filter> minimal
+  task <filter> newest
+  task <filter> next
+  task <filter> oldest
+  task <filter> overdue
+  task <filter> ready
+  task <filter> recurring
+  task <filter> unblocked
+  task <filter> waiting
+
+Build-in read-only:
+  task <filter> burndown.daily
+  task <filter> burndown.monthly
+  task <filter> burndown.weekly
+  task          calendar [due|<month> <year>|<year>] [y]
+  task          colors [sample | legend]
+  task          columns [substring]
+  task <filter> count
+  task          diagnostics
+  task          execute <external command>
+  task <filter> export
+  task <filter> ghistory.annual
+  task <filter> ghistory.monthly
+  task          help
+  task <filter> history.annual
+  task <filter> history.monthly
+  task <filter> ids
+  task <filter> information
+  task          logo
+  task <filter> projects
+  task          reports
+  task          show [all | substring]
+  task <filter> stats
+  task <filter> tags
+  task          timesheet [weeks]
+  task          udas
+  task <filter> uuids
+  task          version
+  task          _aliases
+  task          _columns
+  task          _commands
+  task          _config
+  task <filter> _ids
+  task <filter> _projects
+  task          _show
+  task <filter> _tags
+  task          _udas
+  task <filter> _urgency
+  task <filter> _uuids
+  task          _version
+  task          _zshcommands
+  task <filter> _zshids
+  task <filter> _zshuuids
+
+Write commands:
+  task          add <mods>
+  task <filter> annotate <mods>
+  task <filter> append <mods>
+  task          config [name [value | '']]
+  task <filter> delete <mods>
+  task <filter> denotate <pattern>
+  task <filter> done <mods>
+  task <filter> duplicate <mods>
+  task <filter> edit
+  task          import <file> [<file> ...]
+  task          log <mods>
+  task          merge <URL>
+  task <filter> modify <mods>
+  task <filter> prepend <mods>
+  task          pull <URL>
+  task          push <URL>
+  task <filter> start <mods>
+  task <filter> stop <mods>
+  task <filter> summary
+  task          synchronize
+  task          undo
+