phil-s / org-radiobutton

Radiobutton for org-mode lists.

org-radiobutton

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 a query function org-radiobutton-value which takes an element name (or the list under point) and returns the value of the selected item. You can use a radiobutton list as a simple toggle for a pre-defined list of variable inputs.

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

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

#+RESULTS:
: Will query the staging database

If the item has a description this is not included in the returned value unless the second optional argument is non-nil:

#+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.