A prompt for interacting with org-mode. This can be seen as an org-specific version of XMonad.Prompt.AppendFile, allowing for more interesting interactions with that particular file type.

It can be used to quickly save TODOs, NOTEs, and the like with the additional capability to schedule/deadline a task, add a priority, refile to some existing heading, and use the system's clipboard (really: the primary selection) as the contents of the note.

A blog post highlighting some features of this module can be found here.

You can use this module by importing it, along with XMonad.Prompt, in your xmonad.hs

import XMonad.Prompt
import XMonad.Prompt.OrgMode (orgPrompt)

and adding an appropriate keybinding. For example, using syntax from XMonad.Util.EZConfig:

, ("M-C-o", orgPrompt def "TODO" "/home/me/org/todos.org")

This would create notes of the form * TODO my-message in the specified file.

You can also enter a relative path; in that case the file path will be prepended with $HOME or an equivalent directory. I.e. instead of the above you can write

, ("M-C-o", orgPrompt def "TODO" "org/todos.org")
               -- also possible: "~/org/todos.org"

There is also some scheduling and deadline functionality present. This may be initiated by entering +s or +d—separated by at least one whitespace character on either side—into the prompt, respectively. Then, one may enter a date and (optionally) a time of day. Any of the following are valid dates, where brackets indicate optionality:

• tod[ay]
• tom[orrow]
• any weekday
• any date of the form DD [MM] [YYYY]

In the last case, the missing month and year will be filled out with the current month and year.

For weekdays, we also disambiguate as early as possible; a simple w will suffice to mean Wednesday, but s will not be enough to say Sunday. You can, however, also write the full word without any troubles. Weekdays always schedule into the future; e.g., if today is Monday and you schedule something for Monday, you will actually schedule it for the next Monday (the one in seven days).

The time is specified in the HH:MM or HHMM format. The minutes may be omitted, in which case we assume a full hour is specified. It is also possible to enter a time span using the syntax HH:MM-HH:MM or HH:MM+HH. In the former case, minutes may be omitted.

A few examples are probably in order. Suppose we have bound the key above, pressed it, and are now confronted with a prompt:

• hello +s today would create a TODO note with the header hello and would schedule that for today's date.
• hello +s today 12 schedules the note for today at 12:00.
• hello +s today 12:30 schedules it for today at 12:30.
• hello +d today 12:30 works just like above, but creates a deadline.
• hello +d today 12:30-14:30 works like the above, but gives the event a duration of two hours. An alternative way to specify this would be hello +d today 12:30+2.
• hello +s thu would schedule the note for next thursday.
• hello +s 11 would schedule it for the 11th of this month and this year.
• hello +s 11 jan 2013 would schedule the note for the 11th of January 2013.

Note that, due to ambiguity concerns, years below 25 result in undefined parsing behaviour. Otherwise, what should message +s 11 jan 13 resolve to—the 11th of january at 13:00 or the 11th of january in the year 13?

There is basic support for alphabetic org-mode priorities. Simply append either #A, #B, or #C (capitalisation is optional) to the end of the note. For example, one could write "hello +s 11 jan 2013 #A" or "hello #C". Note that there has to be at least one whitespace character between the end of the note and the chosen priority.

There's also the possibility to take what's currently in the primary selection and paste that as the content of the created note. This is especially useful when you want to quickly save a URL for later and return to whatever you were doing before. See the orgPromptPrimary prompt for that.

Finally, orgPromptRefile and orgPromptRefileTo provide support to automatically refile the generated item under a heading of choice. For example, binding

orgPromptRefile def "TODO" "todos.org"

to a key will first pop up an ordinary prompt that works exactly like orgPrompt, and then query the user for an already existing heading (with completions) as provided by the ~/todos.org file. If that prompt is cancelled, the heading will appear in the org file as normal (i.e., at the end of the file); otherwise, it gets refiled under the selected heading.