Todo-txt: todo.txt parser and report tool

Show & Tell
1

I've written a library and command line tool to process files following the todo.txt format.

todo.txt format overview

Each line in a todo.txt file is of the form:

x (A) 2021-12-30 2021-12-28 Task with a project +my-project and a context @my-context

where almost all parts are optional.

The parts are:

  • x if the task is completed, optional
  • (capital-letter) for the priority, optional
  • Completion date, optional
  • Creation date, optional. If there's a single date, it's the creation date.
  • Description. Apart from regular text, the description can contain:
    • zero or more projects, starting with a +, followed by any non-whitespace characters
    • zero or more contexts, starting with a @, followed by any non-whitespace characters
    • zero or more tags of the form key:value. Tags are often used for a due date, for example due:2021-12-30.

There's a more detailed description here.

Racket library

It's possible to create tasks, sort them and group them. Sorting only changes the order of tasks, whereas grouping (which also involves sorting of the groups) creates a nested structure. The library allows arbitrary nesting of groups and "nested" sorting of tasks within the groups.

Details are in the library documentation.

Command line tool

The command line tool, todoreport, reads one or more files in todo.txt format and groups and sorts them as specified by the user.

Example

Given the file mytodo.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

the command

todoreport --group-by pri,@ --sort-by -crd,desc mytodo.txt

prints

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

In the command invocation, pri stands for priority, @ for context, crd for creation date and desc for description. The - before crd means descending instead of ascending sorting.

Help output

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

<option> is one of

  --group-by <specs>, -g <specs>
     Group specs
  --sort-by <specs>, -s <specs>
     Sort 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.
 
 Group and sort specs are of the form  <order><field-abbreviation> .
 
 <order> is "+" or "-" for ascending or descending order, respectively.
 <order> can be omitted, in which case ascending order is assumed.
 
 <field-abbreviation> is one of the following task fields to group or sort by:
   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)
 The last three can only be used in a group spec.
 
 Group spec 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.
 
 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 my_todo.txt another_todo.txt

Feedback

I'm interested in feedback on the features, the documentation and the code.

5 Likes