mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-07-07 20:06:36 +02:00
Documentation
- Started the new parser documentation.
This commit is contained in:
parent
1641bcf592
commit
2232ff7a21
3 changed files with 284 additions and 0 deletions
77
doc/misc/parser/README
Normal file
77
doc/misc/parser/README
Normal 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>
|
||||||
|
|
34
doc/misc/parser/expressions.txt
Normal file
34
doc/misc/parser/expressions.txt
Normal 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
173
doc/misc/parser/grammar.txt
Normal 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
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue