For the last few years, my life has been managed entirely by a single text file in my home directory called .plan. This file has held all of my to-do tasks for quite some time, and was even available over the Finger protocol at one point 1, which is why it's called .plan instead of todo.txt.
My .plan file has served me well. I had it organized by day. Each day would have a heading and a list of tasks to do on that day. If I wanted to postpone a task, I just cut the line from under one day and pasted it under another. If I wanted to duplicate a task, I would just copy and paste it. Recently, however, I've been trying to track smaller things, like showering and exercising. By writing these things down on my list, I am much more likely to do them, as basic as they may seem. This is become problematic because I have a whole list of tasks that I have to copy to each day. It would be much easier if I could just write them once, and have them automatically recur.
With this goal in mind, I sought to find a different system for managing my tasks. I wanted something equally minimal though, although I knew I would be introducing some code—and with it, some complexity—if I were to get all the features I wanted. The best thing I found was Todo.txt, a simple text file format for managing tasks. However, I found a few problems with it:
These shortcomings led me to develop a new todo list format called Todo.json. Todo.json, as the name might suggest, uses JSON to store tasks. I chose JSON because once you have a JSON parser, it is extremely easy to parse and work with. It is also still human-readable and editable, should that be necessary. JSON allows tasks to have structured metadata and even more complex constructs such as subtasks. Additionally, I included some metadata for recurring tasks and postponing tasks. Finally, tasks can be tagged as a way of denoting categories, and they can be marked as complete.
Of course, the disadvantage to Todo.json is that it is no longer as simple as opening up a text file and plopping your thoughts down in it. While you could still do this in theory, JSON is a little unwieldy for that. So, you would probably want a tool to manage this file for you. However, I think the advantages outweigh this disadvantage. I was able to write a command line interface for Todo.json in C in just a few hours. Granted, it is a basic interface, but a rather functional and elegant one, although I may rewrite it in later because it was more just for a proof of concept.
As far as JSON schemas go, Todo.json is fairly simple. It looks like this:
{
"tasks": [
{
"description": "Here is a task",
"tags": [ "personal" ],
"complete": false,
"postponed": "2023-08-19",
"recur": {
"on": [ "Mon", "Wed", "Fri" ],
"until" "2023-12-16"
},
"tasks": [
{
"description": "This is a subtask",
"complete": false
}
]
}
]
}
This shows the complete schema for Todo.json. A Todo.json file is a JSON object that contains an array of tasks. A task is defined to be a JSON object with some or all of the fields shown above. Note that tasks can be nested arbitrarily deep, and nested tasks have the same format as their parent tasks. The only required keys in a task object are description and complete. All other keys are optional.
Notice that tasks do not have a unique ID stored in the JSON itself. This is because an application may need no such thing. Applications utilizing this format should come up with their own way of identifying tasks if necessary. For example, a GUI application just allows the user to tap or click on tasks to manage them, so no IDs are needed, but a CLI application would probably want to number tasks to give users an easy way of identifying them when specifying operations to be performed. My initial implementation uses the index of the task in its task array to identify it. Subtasks are identified by adding a period to the index of their parent task and then specifying the index of the subtask.
Tasks should be presented in the order they are listed in the JSON file. Rearranging tasks in via an application should rearrange them in the file. It should be possible to nest and un-nest tasks. Tasks that are marked as complete, or postponed for a future date should not be displayed by default, but may be toggled. Tasks can be filtered by their tags, which are just arbitrary user-defined strings.
Dates are presented as strings for portability. Todo.json makes no provision for time zones or other complex features; tasks can recur on the specified days of the week, until a specified date.
Recurring tasks can be handled in a number of different ways. The behavior that I have chosen to go with for now is as follows: when a recurring task is marked as complete, instead of setting complete to true, the application computes the next date that the task would recur on, and sets postponed to that date. Other behaviors are possible though; an application could mark the task as complete and then un-mark it when it recurs, for example.
I designed this format to work with a local file, but there is no reason it couldn't work over HTTP or some other network protocol to sync tasks across devices. In fact, I may build out an HTTP API for managing my own tasks with at some point, but for now, I just keep my Todo.json file synced with the rest of my documents via CVS.
This afternoon, I completed my initial revision and got all my tasks moved over to my Todo.json file. I now manage my todo list entirely with my command line tool, which I have yet to document. If I ever get around to writing the documentation, I will release the tool to the public. Actually, you can already read the source code by checking it out from my CVS repository. Note that it depends on Cytoplasm, so you'll have to get the source code for Telodendria as well.
With Todo.json, I can quickly and easily add tasks, tag them as either personal or for school or something else, postpone them to future dates, and set them to recur on certain weekdays until an absolute date. That's about all I could ask from a todo list program, so this works good enough for me.
I think eventually it would be neat to build out an HTTP API and a simple little web application, but I do like my plain text and command line programs, so I'll probably stick with it for a while. That being said, if you decide you do want to use Todo.json in your application, feel free to reach out and let me know about it!
© 2019-2024 Jordan Bancino.