org-radiobutton

Note: there is now a built-in way to do this in org mode without extra packages. See discussion and changelog (org-list-checkbox-radio-mode). This effectively makes this package unnecessary.

Radiobuttons are groups of options where exactly one option has to be selected at all times.

Org mode checkbox lists allow selecting from a list of candidates but the user would have to manually ensure the radiobutton property.

This package provides a convenient minor mode that will make sure the property is satisfied for lists which are marked as radiobutton lists.

Read the blog post for more background.

Installation

Install from MELPA. If you install manually make sure dash.el is on your load path.

Usage

To enable the mode call global-org-radiobutton-mode. It is a global minor mode and automatically becomes active in all existing org-mode buffers.

Radiobutton list are excellent as sources for other code blocks in org mode. This package provides an advice for org-babel-read-element to only return the checked value of radiobutton list instead of the entire list. You can therefore simply reference the list as any other org element and babel will resolve the reference to the checked item:

#+attr_org: :radio
#+name: service-to-query
- [ ] localhost
- [X] staging
- [ ] production

#+BEGIN_SRC elisp :var service=service-to-query
(format "Will query the %s database" service)
#+END_SRC

#+RESULTS:
: Will query the staging database

If the item has a description (part after ::) this is not included in the resolved value . This package provides a query function org-radiobutton-value which takes an element name (or the list under point) and returns the value of the selected item. With the second optional argument the description is also returned:

#+attr_org: :radio
#+name: number
- [ ] one :: 1
- [X] two :: 2
- [ ] three :: 3

#+BEGIN_SRC elisp :var number=(org-radiobutton-value "number" t)
(-let (((desc value) (split-string number " :: ")))
  (format "An item with description `%s' and value `%s'" desc value))
#+END_SRC

#+RESULTS:
: An item with description `two' and value `2'

This is quite useful when doing something like Emacs literate devops where we can build one pipeline to operate on multiple environments and toggle between them with a single C-c C-c.

Development

We use cask. To run tests:

cask install
make

Acknowledgement

I was looking for this functionality and found John Kitchin’s implementation (via Irreal) from a couple years ago. I fixed it to work with “modern” org-mode and added a couple additional features.