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