From 36b791d7e04b06d386d4aacf51e088bcb38a711b Mon Sep 17 00:00:00 2001 From: Joscha Date: Sat, 8 Sep 2018 21:53:40 +0000 Subject: [PATCH] Plan how the program should work and add docs --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ plan.txt | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) diff --git a/README.md b/README.md index 4fb3c5c..bf17779 100644 --- a/README.md +++ b/README.md @@ -1 +1,66 @@ # task-machine + +A TUI client for the [todo.txt](https://github.com/todotxt/todo.txt) format, written in Haskell, +that supports automatically creating new tasks based on template tasks. + +For an introduction to the file format, see the [todo.txt readme](https://github.com/todotxt/todo.txt/blob/master/README.md). + +## Template tasks + +Template tasks allow for automatically creating new tasks on certain dates. + +They work by evaluating a formula for the current day. +If the formula evaluates to `true`, a new task gets added to the current day using the template text specified. +If it evaluates to `false`, nothing happens. + +When creating a template task, a start date can be specified. +In that case, the formula will be evaluated for every day from the starting date to the current date. + +Once all tasks are added, the starting date will be set to one day after the current date automatically, +to avoid evaluating any day twice, even if no starting date was specified initially. + +Template tasks are inspired by Ben Crowell's [when](https://github.com/bcrowell/when) calendar program. + +### Format + +This is the format for template tasks. +The square brackets `[]` indicate an optional part of the syntax. +The curly braces `{}` are part of the syntax. + +`# [start-date] {when-formula} [priority] template-text` + +- The `#` signals that this line is a template task, not a normal task. + +- *Optional*: All days from `start-date` to the current date are tested when creating new tasks. +It should be in the `YYYY-MM-DD` format. +If no `start-date` is specified, it is assumed to be the current date. + +- The `when-formula` is evaluated in order to decide whether a new task should be created for a day. + +- *Optional*: The `priority` is a regular todo.txt priority, for example `(E)`. + +- The `template-text` is pretty much a normal task description. +The only difference is that it supports date expressions. + +#### Examples + +`# 2018-09-08 {day_of_week == fri} clean the kitchen @home` + +`# {d2018-10-20 - today >= 0} (A) daily every day up to (and including) 2018-10-20 with priority A` + +`# {day == 20 && month == 10} Tom's birthday ({year - 1978} years old)` +(if Tom was born on 1978-10-20) + +### Date expression + +***TODO***: Document properly once it's actually implemented + +- *date* + - *number* → *date* +- *date* - *date* → *number* +- *number* + - \* / *number* → *number* +- *number* == != > < >= <= *number* → *boolean* +- *boolean* && || == != *boolean* → *boolean* + +### When formula + +### Template text diff --git a/plan.txt b/plan.txt index 8abe8d2..a3dd28d 100644 --- a/plan.txt +++ b/plan.txt @@ -1,3 +1,76 @@ +Inspired by https://github.com/todotxt/todo.txt + +-----< Basic concept >----- +The program loads and operates on one todo file at a time. +A todo file is a text file where (with a few exceptions) every line is one todo item. + +-----< Functionality >----- +- load file (parsing) +- save file + +- prune completed tasks + +- "running tasks": +Two-line structure that contains: +1. A line to determine when, and set variables (both using calendar formulas) +2. A "task recipe" that can use $variables (for birthdays etc.) +Running tasks are computed in the order they appear in the file. + +-----< How it works >----- +1. $ todo work.todo +2. load the entire file + 2.1 parse lines + 2.2 preserve structuring of the file: empty lines, comments, order + 2.3 if there's any errors, abort instead of possibly overwriting the file with wrong data later +3. calculate any running tasks + 3.1 look at the last-calculated date, current date and task duration + 3.2 calculate new tasks and append them to the file + 3.3 update last-calculated date of the task + 3.4 save updates +4. present user interface (TUI) + 4.1 show tasks + 4.2 search and order tasks + 4.3 check tasks + 4.4 Optional: delete tasks + 4.5 Optional: create new tasks + 4.5 Optional: edit existing tasks (modify text, priority, ...) +5. overwrite file with new changes + 5.1 instant mode + 5.1.1 after initial running task calculation + 5.1.2 whenever any task was changed (checked, edited, deleted, ...) + 5.2 deferred mode + 5.2.1 save on user save action + 5.2.2 save on close + 5.3 default mode: instant mode? + +-----< The file format >----- +normal tasks: +[x] [priority] [[completion-date] creation-date] text +where completion-date can only be specified if the task was actually completed + +running tasks: +# [running-date] when-formula template + +text: +- may include any amount of +projects and @contexts + (+projects and @contexts are case insensitive) +- may include key:value specifiers + (key and value must consist of non-whitespace characters which are not colons) + (keys are case insensitive too) + +template: +- consists of any string +- may include {expressions} which are when-formulas + (if the when-formula returns a date, the expression is replaced by its YYYY-MM-DD representation) + (if the when-formula returns a number, the expression is replaced by that number) + (if the when-formula returns a boolean, the expression is replaced by "yes" or "no") + +-----< Examples/Testing >----- +The program should work with all https://github.com/todotxt/todo.txt compliant todo files. +"Running tasks" are merely an extension of the todo format. +They use a syntax similar to what I expect comments would look in todo.txt 2.0. +In todo.txt compliant programs, they simply show up as not completed tasks. + Starting the program - read command line options - export default config