Org-mode agenda is a notoriously complex system. It is really great from a user’s perspective, but a nightmare for a programmer wanting to tap into its generation. A long time ago I have had an idea for a productivity tool which would compute my “agenda score” (for lack of a better name), where each task not yet done would contribute to a total of some kind of “penalty” points – and more of them depending on how long the task is overdue.
However, I am probably too stupid to be able to understand what is going on under the hood of org-agenda, and I started to look for better ways. There do exist some tools which might help with that – org-super-agenda being one of them, but there are probably others. Still, I felt this is not the best way.
I decided to drop my idea (at least until I have more time and motivation to get back to it). After some time, however, I came back to org-agenda, this time from another direction. I wanted to understand some obscure parameters Org uses to customize the agenda, and decided it would be nice to be able to test the agenda in an automated way. This way, I discovered a truly hidden gem: org-batch-agenda. It is a macro that takes a string argument and generates a text-only agenda to the standard output. (Notice that it uses princ, which in particular means that all the coloring gets lost in the process. Given how complicated translating Emacs faces to ANSI codes seems to be, this is a good idea.)
It’s especially interesting that this is a macro and not a function. Head over to the Org manual to find out why, there is a good reason!
But wait, there’s more! If you want to do some programmatic operations on the agenda data, you may find the human-readable output of org-batch-agenda suboptimal. In that case, you can use its cousin org-batch-agenda-csv. It does pretty much the same thing, only the result is in the csv format. The manual even gives an example of a Perl script postprocessing this kind of output; of course, you can easily do all sorts of cool stuff with csv data. Here is an example invocation:
emacs -Q --batch --eval='(org-batch-agenda-csv "a" org-agenda-files (quote ("~/my-org-file.org")) org-agenda-span (quote day))'
Note that we use the handy special form (quote ...), which is equivalent to '..., but avoids the dreaded single quote in the Bash single-quote-delimited string. (If you need a single quote in such a circumstance, you need to say e.g. 'single'"'"'quote', which is awful.)
Now having a possibility to batch-generate a csv file with Org agenda opens a lot of possibilities. Automated agenda testing is one of them; a simple web application serving your agenda to the browser in e.g. your smartphone is another. I am sure you could think of many others. Happy hacking!
CategoryEnglish, CategoryBlog, CategoryEmacs, CategoryOrgMode