xmonad-contrib-0.18.1: Community-maintained extensions for xmonad

Copyright | (c) 2021 Tony Zorman
License | BSD3-style (see LICENSE)
Maintainer | Tony Zorman <soliditsallgood@mailbox.org>
Stability | experimental
Portability | unknown
Safe Haskell | None
Language | Haskell2010

XMonad.Prompt.OrgMode

Contents

- Usage
- Prompts
- Types

Description

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.

Synopsis

- orgPrompt :: XPConfig -> String -> FilePath -> X ()
- orgPromptRefile :: XPConfig -> String -> FilePath -> X ()
- orgPromptRefileTo :: XPConfig -> String -> String -> FilePath -> X ()
- orgPromptPrimary :: XPConfig -> String -> FilePath -> X ()
- data ClipboardSupport
  - = PrimarySelection
  - | NoClpSupport
- data OrgMode

# 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

Instances details

XPrompt OrgMode # |
Instance details 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 () #