# Todo-txt: todo.txt parser and report tool

**URL:** <https://racket.discourse.group/t/todo-txt-todo-txt-parser-and-report-tool/499>\
**Category:** Show & Tell\
**Created:** [December 30, 2021, 6:34pm UTC](https://racket.discourse.group/t/todo-txt-todo-txt-parser-and-report-tool/499 "2021-12-30T18:34:38Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![sschwarzer](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/sschwarzer/32/1940_2.png) [@sschwarzer](https://racket.discourse.group/u/sschwarzer)\
**Post date:** [December 30, 2021, 6:34pm UTC](https://racket.discourse.group/t/todo-txt-todo-txt-parser-and-report-tool/499/1 "2021-12-30T18:34:38Z")

</div>

I've written a [library and command line tool](https://pkgs.racket-lang.org/package/todo-txt) to process files following the [todo.txt format](https://github.com/todotxt/todo.txt).

# todo.txt format overview

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

```scheme
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](https://github.com/todotxt/todo.txt).

# 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](https://docs.racket-lang.org/todo-txt/index.html).

# Command line tool

The [command line tool](https://git.sr.ht/~sschwarzer/todo-txt/tree/main/item/README.md), `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`

```none
(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

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

```

prints

```none
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

```none
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](https://git.sr.ht/~sschwarzer/todo-txt/tree).