Documentation

- Started the new parser documentation.
This commit is contained in:
Paul Beckingham 2013-04-16 01:23:32 -04:00
parent 1641bcf592
commit 2232ff7a21
3 changed files with 284 additions and 0 deletions

77
doc/misc/parser/README Normal file
View file

@ -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>

View file

@ -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

173
doc/misc/parser/grammar.txt Normal file
View file

@ -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