taskwarrior/doc/misc/parser

The main focus of the 2.4.0 release is a new command line parser that has more
capabilities with 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 to be 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>