README.md

checkbox.el

A tiny library for working with textual checkboxes in Emacs buffers. Use it to keep grocery lists in text files, feature requests in source files, or task lists on GitHub PRs.

Installation

The recommended method of installation is via package.el. If you haven't previously added MELPA (or Marmalade) as a package source, add the following to your .emacs and either evaluate it or restart Emacs:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)
(package-initialize)

With that in place you can simply run M-x package-install RET checkbox RET to download and install the package.

I'd recommend globally binding checkbox-toggle to a convenient keystroke. For example:

(global-set-key (kbd "C-c C-t") 'checkbox-toggle)

Usage

If you have a simple to-do list in a Markdown file like this:

- [ ] Buy gin<point>
- [ ] Buy tonic

And you invoke checkbox-toggle, you'll get the following:

- [x] Buy gin<point>
- [ ] Buy tonic

Invoke it again and you're back to the original unchecked version.

- [ ] Buy gin<point>
- [ ] Buy tonic

Next, if we add a line without a checkbox...

- [ ] Buy gin
- [ ] Buy tonic
- Buy limes<point>

We can invoke the command again to insert a new checkbox.

- [ ] Buy gin
- [ ] Buy tonic
- [ ] Buy limes<point>

If we want to remove a checkbox entirely we can do so by passing a prefix argument (C-u) to checkbox-toggle.

Finally, checkbox.el treats programming modes specially, wrapping inserted checkboxes in comments so we can quickly go from this:

(save-excursion
  (beginning-of-line)<point>
  (let ((beg (point)))

To this:

(save-excursion
  (beginning-of-line)                ; [ ] <point>
  (let ((beg (point)))

If you prefer to use an alternate set of checkboxes, you can do so by changing the value of checkbox-states, a buffer-local variable. Less advanced users may prefer to do this through the customize facility:

M-x customize-group RET checkbox RET

Advanced users may prefer to do so via their .emacs file:

(require 'checkbox)
(setq-default checkbox-states '("TODO" "DONE" "WAITING"))

Additionally, a convenient way to give a file a unique set of checkbox states is via File Variables (also see the handy add-file-local-variable function), allowing us to specify the state set we want to use via a small comment near the end of the file. For example, in a Markdown file:

<!-- Local Variables: -->
<!-- checkbox-states: ("TODO" "DONE" "WAITING") -->
<!-- End: -->

Passing a prefix argument to checkbox-toggle allows us to directly choose a checkbox to insert via its position in checkbox-states, which is useful when we have more than two states. For example, assuming the custom state set above and a buffer with the following contents:

- Review report<point>

C-u 2 C-c C-t will yield:

- WAITING Review report<point>

Note that the first state is 0.

Alternatives

For a more featureful alternative, check out the amazing org-mode. I love and use org-mode, but org-mode generally expects to be running as a major mode whereas checkbox.el will happily handle your checkbox needs inside of any mode.

Testing

To run the full test suite (unit + integration) simply run:

$ make

License

Copyright (C) 2014 Cameron Desautels

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Author: Cameron Desautels <[email protected]>
Source: https://github.com/camdez/checkbox.el