XMonad.Prompt.OrgMode

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.

Usage

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.

Prompts

orgPrompt

Arguments

:: XPConfig

Prompt configuration

-> String

What kind of note to create; will be displayed after a single *

-> FilePath

Path to .org file, e.g. home/me/todos.org

-> X ()

Prompt for interacting with org-mode.

orgPromptRefile :: XPConfig -> String -> FilePath -> X ()

Like orgPrompt (which see for the other arguments), but offer to refile the entered note afterwards.

Note that refiling is done by shelling out to Emacs, hence an emacs binary must be in $PATH. One may customise this by following the instructions in XMonad.Util.Run; more specifically, by changing the emacs field of ProcessConfig.

orgPromptRefileTo

Arguments

:: XPConfig

-> String

Heading to refile the entry under.

-> String

-> FilePath

-> X ()

Like orgPromptRefile, but with a fixed heading for refiling; no prompt will appear to query for a target.

Heading names may omit tags, but generally need to be prefixed by the correct todo keywords; e.g.,

orgPromptRefileTo def "PROJECT Work" "TODO" "~/todos.org"

Will refile the created note "TODO text" to the "PROJECT Work" heading, even with the actual name is "PROJECT Work :work:other_tags:". Just entering Work will not work, as Emacs doesn't recognise PROJECT as an Org keyword by default (i.e. when started in batch-mode).

orgPromptPrimary :: XPConfig -> String -> FilePath -> X ()

Like orgPrompt, but additionally make use of the primary selection. If it is a URL, then use an org-style link [[primary-selection][entered message]] as the heading. Otherwise, use the primary selection as the content of the note.

The prompt will display a little + PS in the window after the type of note.

Types

data ClipboardSupport

Whether we should use a clipboard and which one to use.

Constructors

PrimarySelection

NoClpSupport

data OrgMode

Instances

XPrompt OrgMode

Defined in XMonad.Prompt.OrgMode

Methods

showXPrompt :: OrgMode -> String

nextCompletion :: OrgMode -> String -> [String] -> String

commandToComplete :: OrgMode -> String -> String

completionToCommand :: OrgMode -> String -> String

completionFunction :: OrgMode -> ComplFunction

modeAction :: OrgMode -> String -> String -> X ()