todo-txt: Racket parser and report generator for todo.txt files

#todoreport

#Introduction

The tool todoreport reads todo.txt files as specified at https://github.com/todotxt/todo.txt and displays them, grouped and sorted as specified on the command line.

For example, the command

todoreport --group-by @ --sort-by pri,-crd /path/to/todo.txt

on the command line will print the file /path/to/todo.txt,

(C) 2021-03-23 Fix faucet @home
(C) 2021-03-25 Do laundry @home
(A) 2021-03-22 Call boss @work
(A) 2021-03-24 Work on +todoreport @home
Read Racket Guide

@home
  (A) 2021-03-24 Work on +todoreport @home
  (C) 2021-03-25 Do laundry @home
  (C) 2021-03-23 Fix faucet @home
@work
  (A) 2021-03-22 Call boss @work
No context
  Read Racket Guide

Nested grouping is supported, too:

todoreport --group-by @,pri --sort-by -crd -o pri /path/to/todo.txt

gives

@home
  A
    2021-03-24 Work on +todoreport @home
  C
    2021-03-25 Do laundry @home
    2021-03-23 Fix faucet @home
@work
  A
    2021-03-22 Call boss @work
No context
  No priority
    Read Racket Guide

#Installation

#`todoreport` tool

If you don't need the todo-txt library (see below) and just want the todoreport tool (introduced above and described in more detail below), download binaries from https://releases.sschwarzer.net/todo-txt.

#`todo-txt` Racket library

Install Racket, if not already installed

https://download.racket-lang.org/ has up-to-date installation files. Linux distribution packages for Racket are often outdated.
Then use any of these three methods:
- On the command line, type
```
raco pkg install todo-txt
```
- To install the tool from the Git repository, use
```
raco pkg install git+https://git.sr.ht/~sschwarzer/todo-txt#v0.5.0
```
  possibly with a different tag. The git+https protocol requires at least Racket 8.1.
- Clone the Git repo and from inside the Git working directory run
```
raco pkg install
```

#Usage

For an overview, see the --help output. You can find more information about the options in the next section.

usage: todoreport [ <option> ... ] [<args>] ...

<option> is one of

  -g <specs>, --group-by <specs>
     Group specs
  -s <specs>, --sort-by <specs>
     Sort specs
  -o <specs>, --omit-fields <specs>
     Field omission specs
  --help, -h
     Show this help
  --
     Do not treat any remaining argument as a switch (at this level)

 Multiple single-letter switches can be combined after
 one `-`. For example, `-h-` is the same as `-h --`.

 Read todo.txt files, rearrange them and print them. See
 https://github.com/todotxt/todo.txt/blob/master/README.md for the todo.txt
 format description.

 The "specs" arguments use a subset of the following field abbreviations:
   x            completed
   pri or prio  priority
   cod          completion date ("co" for completion, "d" for date)
   crd          creation date ("cr" for creation, "d" for date)
   desc         description
   @            context (contexts are marked with @)
   +            project (projects are marked with +)
   <key>:       tag key, say, "due:" (tags are marked as key:value)

 Group and sort specs are of the form  <order><field-abbreviation> , where
 <order> is "+" or "-" for ascending or descending order, respectively.
 <order> can be omitted, in which case ascending order is assumed. Several
 field abbreviations can be combined by separating them with commas (but
 NOT spaces after the commas), for example "x,pri".

 The valid field abbreviation subsets for the different specs are:
   Sort specs: x, pri, prio, cod, crd, desc
   Group specs: x, pri, prio, cod, crd, desc, @, +, <key>:
   Field omission specs: x, pri, prio, cod, crd, auto ("auto" means that
     field omissions are added from the group specs). The idea is that if you
     group by, say, priority, listing the priority for each task is redundant.

 Group specs example:
   pri,+  Group by ascending priority. Within each such group, group by
   ascending project name.

 Sort specs example:
   -due:,desc  Sort first by descending due date. Sort tasks with the same due
     date by description in ascending order.

 Field omission specs example:
   x,crd  For each task in the output, omit the completion status (the "x"
     prefix) and the creation date. As a special rule, omitting the creation
     date also omits the completion date. This is because only omitting the
     creation date might leave a completion date, but if there's a single date
     on a line, it's supposed to be the creation date!

 After the options, specify one or more paths of todo.txt-format files. As a
 special case, if no file path is given, todoreport tries to get the path from
 the environment variable TODO_FILE .

 Example:
   todoreport -g +,due: -s pri,-crd,desc -o auto my_todo.txt another_todo.txt

 See the project website for more: https://sr.ht/~sschwarzer/todo-txt

#Grouping, sorting and omitting fields

todoreport will group the read tasks according to the --group-by option, then inside each group, sort the tasks according to the --sort-by option. The --omit-fields option can exclude fields from the task lines in the output.

The so-called group specs and sort specs consist of an order indicator (for ascending or descending order) and a task field to group/sort by. The abbreviations for the task fields follow the todo.txt format, if possible. For example, the "context" field is specified with "@" because contexts for tasks are written as "@home" or "@work". See the help output for how the task fields are written.

Since a task can have multiple contexts, it may appear in multiple groups if grouping by context. The same applies to grouping by project.

You can also group by tags. For example, to group by due date, use --group-by due: (note the trailing colon).

If more than one sort spec is provided, the tasks in the groups are sorted first according to the first sort spec, then, for the same field value in the first sort spec, sorted according to the second sort spec, and so on. Check the example at the beginning of this file. In case of a tie (say, you sort only by priority and some tasks have the same priority), the original order from the file is kept.

Note that if you specify multiple group specs and/or sort specs, separate them with a comma, but don't put a space after the comma.

The --group-by and/or --sort-by options are optional. If neither option is used, the tasks will be displayed in the order they appear in the input file(s).

You can use --omit-fields to omit certain data from the output of each task line. You can omit only simple fields, not fields like projects or tags. That would be more complicated and may give odd results. For example, imagine a task description "Fix bug in +todo-txt", which would be turned into "Fix bug in".

Note that if you specify crd (for the creation date), the completion date will also be omitted. The reason is that if a task has both a completion date and a creation date, removing only the creation date would make the completion date appear as the creation date.

As a special case, you can use "auto" for --omit-fields. The effect is as if you had specified all the simple fields from --group-by. For example, if you use --group-by pri,@ --omit-fields auto, the task lines will omit the priority field.

If the above explanations still sound confusing, experiment with different values for the --group-by, --sort-by and --omit-fields options. To see the effects of the options more clearly, your task file should contain different data for the properties you group or sort by. For example, to see the effect of grouping by priority, your tasks should have different priorities. It's also helpful to have tasks without the property, in the previous example tasks without a priority.

#File paths

You can specify more than one file path. In this case, todoreport will read the files in the given order and treat all tasks as if they came from the same file. Empty lines in the files are ignored.

As a special case, if you don't specify any paths, todoreport will try to take the path of a todo.txt file from the environment variable TODO_FILE. This is the same environment variable that the CLI tool at https://github.com/todotxt/todo.txt-cli uses to find a default file.

#Contributing

You can view and enter tickets at https://todo.sr.ht/~sschwarzer/todo-txt .

If you want to contribute patches, you can generate them with git format-patch (see https://git-scm.com/docs/git-format-patch ) and attach them to a ticket. I recommend you first discuss your planned changes in a ticket before investing time in a patch.

#License

MIT license, see https://opensource.org/licenses/MIT

#Author

Stefan Schwarzer

~sschwarzer/todo-txt