org: Extracting agenda information
A.10 Extracting agenda information
==================================
Org provides commands to access agenda information for the command line
in Emacs batch mode. This extracted information can be sent directly to
a printer, or it can be read by a program that does further processing
of the data. The first of these commands is the function
‘org-batch-agenda’, that produces an agenda view and sends it as ASCII
text to STDOUT. The command takes a single string as parameter. If the
string has length 1, it is used as a key to one of the commands you have
configured in ‘org-agenda-custom-commands’, basically any key you can
use after ‘C-c a’. For example, to directly print the current TODO
list, you could use
emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
If the parameter is a string with 2 or more characters, it is used as
a tags/TODO match string. For example, to print your local shopping
list (all items with the tag ‘shop’, but excluding the tag ‘NewYork’),
you could use
emacs -batch -l ~/.emacs \
-eval '(org-batch-agenda "+shop-NewYork")' | lpr
You may also modify parameters on the fly like this:
emacs -batch -l ~/.emacs \
-eval '(org-batch-agenda "a" \
org-agenda-span (quote month) \
org-agenda-include-diary nil \
org-agenda-files (quote ("~/org/project.org")))' \
| lpr
which will produce a 30-day agenda, fully restricted to the Org file
‘~/org/projects.org’, not even including the diary.
If you want to process the agenda data in more sophisticated ways,
you can use the command ‘org-batch-agenda-csv’ to get a comma-separated
list of values for each agenda item. Each line in the output will
contain a number of fields separated by commas. The fields in a line
are:
category The category of the item
head The headline, without TODO keyword, TAGS and PRIORITY
type The type of the agenda entry, can be
todo selected in TODO match
tagsmatch selected in tags match
diary imported from diary
deadline a deadline
scheduled scheduled
timestamp appointment, selected by timestamp
closed entry was closed on date
upcoming-deadline warning about nearing deadline
past-scheduled forwarded scheduled item
block entry has date block including date
todo The TODO keyword, if any
tags All tags including inherited ones, separated by colons
date The relevant date, like 2007-2-14
time The time, like 15:00-16:50
extra String with extra planning info
priority-l The priority letter if any was given
priority-n The computed numerical priority
Time and date will only be given if a timestamp (or deadline/scheduled)
led to the selection of the item.
A CSV list like this is very easy to use in a post-processing script.
For example, here is a Perl program that gets the TODO list from
Emacs/Org and prints all the items, preceded by a checkbox:
#!/usr/bin/perl
# define the Emacs command to run
$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
# run it and capture the output
$agenda = qx{$cmd 2>/dev/null};
# loop over all lines
foreach $line (split(/\n/,$agenda)) {
# get the individual values
($category,$head,$type,$todo,$tags,$date,$time,$extra,
$priority_l,$priority_n) = split(/,/,$line);
# process and print
print "[ ] $head\n";
}