magenda.py
is a Python 3 script for creating an agenda of task-list items in
GitHub Flavored Markdown files.
Task-list items are
list items with one of the task-list item markers [ ]
, [x]
, or [X]
after
the list marker.
This script recognises various metadata in the first line of a task-list item. For this line, the following general format is assumed:
<indentation>? <list marker> <task-list item marker> <title> <mention>* <hashtag>* <date-tag>?
For example:
- [ ] buy presents: #shopping
- [ ] buy Christmas presents @NN #christmas #due:2020-12-24
Here @NN
is a mention, #christmas
and #shopping
are hashtags, and the
date-tag #due:2020-12-24
is a due-date specification. Indented
task-list items like the second one are taken to be subtasks.
The script is released 'as is' with no warranty under the GNU General Public License, version 2.0.
It requires the following Python 3 package:
On Debian-based systems, the prerequisite can be installed as follows:
sudo apt-get install python3-blessings
Usage:
magenda.py [-c] [--completed-tasks]
[-C] [--force-color]
[-d <num>] [--days <num>]
[-n] [--line-number]
[-r] [--reversed]
[-s] [--subtasks]
[-u] [--undated-tasks]
<Markdown file(s)>
magenda.py [-v] [--version]
magenda.py [-h] [--help]
Running the script with -s
and -u
options on a Markdown file.md
containing
the task-list items above will generate the following output:
Thu 24 Dec
file.md:buy Christmas presents @NN #christmas
Undated
file.md:buy presents #shopping
Given these options, subtasks and undated tasks are considered in addition to
dated tasks. In order to restrict the date range, use the -d
option with the
number of days from today as an argument. The -r
option reverses the date
order. Line numbers can be output in addition to file names by means of the
option -n
.
By default, only uncompleted tasks (i.e. task-list items with the task-list item
marker [ ]
) are taken into account. With the -c
option, completed tasks
(task-list items with the task-list item markers [x]
or [X]
) are listed
instead; in this case, dates are determined on the basis of date-tags like
#done:2020-12-24
.
In a terminal, the output is pretty-printed. The -C
option preserves colors
and formatting codes when piping the output through
GNU less or similar programs.
Andreas Nolda (andreas@nolda.org)