Emacs on camdez

Chinese Zodiac Time for Emacs

Mon, 12 Feb 2024 21:22:33 -0600

In the spirit of Chinese New Year, I hacked up a small extension for Emacs to render the current time of day using emoji and Chinese characters:

Various configurations for your mode line.

It’s just a silly project that I’ll consider a success if it puts a smile on someone’s face, but it is loosely based on a system used to measure time in the Ming dynasty which divided the day into 12 equal periods (時¹), named after the 12 earthly branches (地支).

Because the animals of the Chinese zodiac map 1-to-1 with the earthly branches, it is equally possible to indicate the time with the zodiac animals!

Chart of correspondence between the earthly branches, zodiac animals, and times of day from Wikipedia. Apologies on this being in Spanish.

Given that a modern user probably wants to know which of our 24 hours they’re in, rather than which two hour period (時), I decided to differentiate the two halves as either 小 (small) or 大 (large).

Hence, in the image above showing the time as 「大🐲 四十二分」, the current time is 8:42am, by our modern reckoning (7:42am would be the little dragon!).

I won’t go into a ton of detail here because I explain it in some detail on the project’s GitHub page.

The most amusing part of the project was, perhaps, deciding exactly which emoji to use! In the end, I implemented two sets of emoji you can choose from:

Set	Emoji
`'cute`	🐭🐮🐯🐰🐲🐍🐴🐏🐵🐔🐶🐷
`'emoji`	🐀🐄🐅🐇🐉🐍🐎🐑🐒🐓🐕🐖

Rather disappointing that we don’t quite have a complete set of animal faces. At least not in Apple’s emoji.

If you’re wondering why I chose the COW (🐄) emoji in the second set rather than the OX (🐂), it’s because it looked too similar to the neighboring TIGER (🐅), making it easy to confuse the time.

If you don’t like my choices, the library also makes it extremely easy to bring your own set of emoji, so you can make your own decisions between:

RAT (🐀), MOUSE (🐁), and MOUSE FACE (🐭)
SHEEP (🐑), GOAT (🐐), and RAM (🐏)
HORSE (🐎) and HORSE FACE (🐴)
CHICKEN (🐔) and ROOSTER (🐓)
Or maybe even pretend FROG (🐸) is a snake face
Or spice up your horse with UNICORN (🦄)

Clearly the sky’s the limit.

For Chinese learners or traditionalists, it can also display the time with:

Traditional characters: 「大龍四十二分」²
Simplified characters: 「大龙四十二分」
Or earthly branches: 「辰正四十二分」

(n.b. the earthly branches are displayed using the proper, traditional system of 初 and 正 suffixes, not my invented prefixes for animals.)

It’s a lot of fun telling time with cute animals, and might even help you learn a few things if you’re a beginner in Chinese, so check it out on GitHub!

龍年快樂！恭喜發財！ 🐉🧧

Students of the Chinese language may find it interesting to know that these two hour periods are the reason we call (single) hours 小時 in modern Chinese (I know I did!). ↩︎
It’s not 100% clear to me if these characters will render the same regardless of locale, so I apologize if they do not appear as I have described—I’m still trying to get my head around CJK unification in Unicode. ↩︎

Fix clj-refactor Libspec Stealing

Tue, 06 Feb 2024 22:59:28 -0600

(This post is regarding a very particular issue at the intersection of Emacs, Clojure, and CIDER, so most readers can probably skip it, but I figured the solution deserved to be somewhere on the internet.)

CIDER has this awesome feature via clj-refactor where it can automatically add missing libspecs to your ns form as soon as you type an aliased var name using an :as alias you have previously used for that namespace:

Screen recording showing how CIDER and clj-refactor can add missing libspecs.

You can define a preferred set of (:as) aliases via cljr-magic-require-namespaces in your Emacs config, and, whether you’ve done that or not, CIDER tries hard to be smart, offering you choices if you’ve previously used the same alias for different namespaces in different places in your project (e.g. s/ for clojure.spec some places and the same for clojure.string in other places).

Moreover, CIDER evaluates the namespace form, bringing in the new requires, allowing you to just keep typing and coding, without breaking your flow.

This is all fantastic, but I ran across one particular scenario where this kept biting me: my user namespace.

In my dev/user.clj file, I had a number of commands for managing the state of my program during development (viz. reloaded.repl and friends) that I used constantly, including while testing out various functions I’d just written in the current namespace (e.g. (new-db-query (user/db))). But I also happen to have another (rarely-used) namespace in my app which was, somewhere, aliased as user. Something like app.ui.views.user.

Since references to the (top-level) user namespace never occur in the (production-shared) broader codebase, every time I typed user/, CIDER immediately added a require for the namespace I didn’t want (the only usage of the alias in the codebase) and loaded it. Meaning I not only had to remove it, but also undefine the alias (C-c C-u)—and hopefully not accidentally trigger the same thing yet again though muscle memory….

I tried everything I could think of to fix this, including just specifying via cljr-magic-require-namespaces that user should expand to user, but nothing worked, so I suspect a proper solution is going to require an upstream patch.

In the meantime, a quick and dirty solution is just to use advice in Emacs:

(use-package clj-refactor
 :defer t
 :config

 ;; Don't auto add `require' form for `user' namespace.
 (defun cljr--unresolved-alias-ref--unless-user (alias-ref)
 (unless (string= "user" alias-ref)
 alias-ref))

 (advice-add 'cljr--unresolved-alias-ref :before-while
 #'cljr--unresolved-alias-ref--unless-user))

If the advice function here (cljr--unresolved-alias-ref--unless-user) returns nil, it essentially tells clj-refactor that an alias is already handled and it doesn’t need to worry about adding an import for it.

Emacs: Running Shell Commands on the Current File

Fri, 29 Jul 2022 07:48:44 -0500

I’ve long thought it was a little funny that Emacs doesn’t provide an easy way to run a shell command on the current file. It turns out it does, but it’s not as obvious as you might expect.

Emacs provides lots of great commands for conveniently running shell commands:

M-! (shell-command): executes the given shell command, displays output in a new buffer or the echo area (depending on output length). Optionally inserts the output into the current buffer when given a prefix argument.
M-& (async-shell-command): as above, but executed asynchronously.
M-| (shell-command-on-region): pass the current region as input to a shell command and display output. Optionally replaces the region when given a prefix argument.

Of course we can also run a shell within Emacs, via shell (the basic option), eshell (a shell implemented in Emacs Lisp, with access to Emacs Lisp functions), and term (a more fully-featured terminal emulator).

We also have compile, which will run a shell command (often make), streaming in the output and overlaying functionality to easily jump to files referenced in the output (compilation warnings, grep results, etc.).

But what has always been notably missing for me, is a quick way to run a shell command on the current file. Not buffer / file contents, not region, but file.

From dired-mode, we can easily do this with !, but invoking Dired just to run a shell command is more disruptive to my workflow than it needs to be when I just want to run open <current-file> or similar.

It turns out there is a built-in two-keystroke solution via the “future history” mechanism I wrote about on the CollBox Engineering blog:

If you use M-! (shell-command) and then press M-n (next-history-element), the current file name will be inserted into the minibuffer with point before it. Then you just need to type the command you want to run and hit return.

It’s a good reminder that with 46 years of history behind it, if something obvious appears to be missing from Emacs, there’s probably a good reason why.

Regex Optimization in Clojure

Sat, 14 Aug 2021 15:28:31 -0700

Earlier this week, after responding to a post on ClojureVerse, I got curious about re-implementing the basics of Emacs’s regexp-opt function in Clojure. I thought it would be a fun little coding exercise so I decided to take a stab at it during a few spare minutes in my day and was very pleased with the concision and clarity of the result.

Emacs’s regexp-opt takes a list of strings and produces an optimized regular expression matching all of the passed strings. A non-optimized solution to this problem would be to simply combine all of the possibilities into a regex alternation:

(def sample-opts ["AB" "ABOUT" "APPLE" "BOTTLE"])

(defn- re-alt-str
 "Build a string representing regex alternation."
 [opts]
 (if (next opts)
 (str "(?:" (str/join "|" opts) ")")
 (first opts)))

(defn naive-re-opt [opts]
 (re-pattern (re-alt-str opts)))

(naive-re-opt sample-opts)
;; => #"(?:AB|ABOUT|APPLE|BOTTLE)"

(re-find (naive-re-opt sample-opts)
 "PLEASE GIVE ME AN APPLE")
;; => "APPLE"

This approach works perfectly fine, but isn’t optimal because in searching for a string like “APPLE”, the regex engine initially finds a match against the A in “AB”, then realizes the B doesn’t match before moving on to “ABOUT” and doing the same partial match dance again before trying “APPLE”¹.

Instead, we can compute an optimized regular expression where the A is only matched once and only then do we continue on to explore the possible suffixes following A (viz. “B”, “BOUT”, “PPLE”). We also want to repeat this logic through the rest of the pattern text, only matching the B once.

How can we use Clojure to tackle this problem?

The algorithm is actually quite simple:

First we build a graph (tree) where each edge represents successive letters in the strings of opts:

Note: terminators need to be explicitly modeled in the graph so that “AB” is considered a match and not just a prefix on the way to matching “ABOUT”.

Then we simply collapse the tails into literal strings, and the branches into alternations:


(defn better-re-opt [opts]
 (->> opts
 ;; Build graph
 (reduce (fn [graph s]
 (assoc-in graph (conj (vec s) nil) nil))
 {})
 ;; Reduce graph to string
 (walk/postwalk (fn [x]
 (if (map? x)
 (re-alt-str (map #(apply str %) x))
 x)))
 re-pattern))

(better-re-opt sample-opts)
;; => #"(?:A(?:B(?:|OUT)|PPLE)|BOTTLE)"

(Excuse the dense indentation, I’m trying to squeeze this into 70 columns to avoid horizontal scrolling.)

That’s it! About ten lines of code to solve this whole problem, and maybe 20 minutes of work for me from idea to finished feature.

My favorite thing about this implementation is how easy Clojure makes it to build the graph. I initially went into this thinking of manually consing up the graph before realizing assoc-in could do all of the work for me. Essentially we’re just doing something like this:

(-> {}
 (assoc-in [\A \B nil] nil)
 (assoc-in [\A \B \O \U \T nil] nil)
 (assoc-in [\A \P \P \L \E nil] nil)
 (assoc-in [\B \O \T \T \L \E nil] nil))
;; =>
{\A {\B {nil nil,
 \O {\U {\T {nil nil}}}},
 \P {\P {\L {\E {nil nil}}}}},
 \B {\O {\T {\T {\L {\E {nil nil}}}}}}}

Notice the similarity to the graph we drew above?

Those nil terminators may look funky, but I chose that approach intentionally because (str nil) ;=> "", which makes the code to reduce the graph to a string very compact.

To do that reduction, we perform a post-order traversal of the nodes of the graph (convenient as all get-out with clojure.walk/postwalk), returning non-map values unchanged and only operating when we’re looking at a map. For maps with a single key-value pair, we use str to concatenate the key (the head character) and the value (the reduced tail string). Referring to this operation as f:

(f {nil nil}) ; <=> (str nil nil) => ""
(f {\A "BC"}) ; <=> (str \A "BC") => "ABC"

When we have multiple key-value pairs, we reduce each pair in the same fashion and then combine them into a regex alternation just like in the naive version.

The reduction (here, for a smaller graph), proceeds something like this:

{\A {\B {\C {nil nil},
 \U {\T {nil nil}}}}}

{\A {\B {\C {nil nil},
 \U {\T ""}}}}

{\A {\B {\C {nil nil},
 \U "T"}}}

{\A {\B {\C "",
 \U "T"}}}

{\A {\B "(?:C|UT)"}}

{\A "B(?:C|UT)"}

"AB(?:C|UT)"

This is the kind of scenario where all the features of Clojure come together so elegantly to make a succinct, beautiful solution.

Full code listing for ease of copy / paste:

(ns camdez.re-opt
 (:require [clojure.walk :as walk]
 [clojure.string :as str]))

(defn- re-alt-str
 "Build a string representing regex alternation."
 [opts]
 (if (next opts)
 (str "(?:" (str/join "|" opts) ")")
 (first opts)))

(defn re-opt
 "Build an optimized regular expression to match any of the literal
 strings in `opts` by unifying common prefixes."
 [opts]
 (->> opts
 (reduce (fn [graph s]
 (assoc-in graph (conj (vec s) nil) nil))
 {})
 (walk/postwalk (fn [x]
 (if (map? x)
 (re-alt-str (map #(apply str %) x))
 x)))
 re-pattern))

In practice, our regex engine may be smart enough to avoid these operations through internal optimization, but that’s why this is just a coding exercise. ↩︎

Interactively Evaluating Clojure Code in Comments in Emacs

Fri, 03 Jul 2020 18:40:55 -0500

There’s a loose convention in Clojure of leaving top-level (comment ...)-style comments in source files to give examples of how a particular piece of code works or to provide a convenient means of invoking functionality contained in the file. You can even see this in the source files to Clojure proper.

Even though leaving commented out code can seem a bit messy, it has also saved me a ton of time relearning how to invoke something, so I have somewhat mixed feelings about the practice. But, regardless of the merits of using this in production code, it’s unarguably useful in development, and I use it extensively as I work to test out function invocations with different arguments, and to store little bits of test data.

Frustratingly, this form does not play nicely with CIDER’s C-M-x (cider-eval-defun-at-point) and C-c M-; (cider-eval-defun-to-comment) commands, which expect the target form to be at the top-level of the file. The containing (comment ...) form means that technically isn’t so, leading me to perpetually evaluate the wrong form…

(comment
 (+ 1 1) <point>
 ) ; => nil

…and be told for the millionth time that comments evaluate to nil.

I finally discovered that there is an easy way to change this behavior, with just a single settings tweak:

(setq clojure-toplevel-inside-comment-form t)

Now things will work as you (might) expect…

(comment
 (+ 1 1) <point> ; => 2
 )

… which is certainly more useful, and destined to become a permanent part of my Emacs config.

Automatically Installing Your Emacs Packages

Sun, 07 Dec 2014 23:27:54 -0600

The interactive list-packages command in modern Emacsen is handy for finding and trying out new packages, but once we’ve found packages we want to use, how can we have them automatically installed on all machines where we use Emacs? There’s a decent Stack Overflow question on the topic, but I want to dig into the various answers a bit and provide a slightly cleaner (IMHO) code snippet.

First let’s define that list of packages we want installed by adding a defvar form to our .emacs:

(defvar my/packages
 '(abc-mode
 ;; ⋮
 zygospore))

Now, the obvious part of this problem is using package-installed-p to check if each named package is installed and then installing the missing ones. The less obvious part is that we may need to call package-refresh-contents to get the package repository data (especially on the first load) or else we’ll get errors. High-level, there are four ways I know of to approach this problem:

Always call package-refresh-contents.
Check if package-archive-contents is non-nil.
Test if package-user-dir exists.
Refresh if any packages are missing.

Number one works buts is extremely inefficient–I don’t want to wait for a package repo fetch every time I start Emacs.

Two and three have a fatal flaw: just because we have some package data doesn’t mean that we have the latest data. So it’s entirely possible that we don’t know about a recent package that the user wants to install–errors again.

The fourth method is the way to go. Surprising no one¹, @bbatsov shows up with the right answer. But I do think this code could be a hair cleaner, so here’s my take:

(require 'cl-lib)

(defun my/install-packages ()
 "Ensure the packages I use are installed. See `my/packages'."
 (interactive)
 (let ((missing-packages (cl-remove-if #'package-installed-p my/packages)))
 (when missing-packages
 (message "Installing %d missing package(s)" (length missing-packages))
 (package-refresh-contents)
 (mapc #'package-install missing-packages))))

(my/install-packages)

Closing notes:

The function² exists so that you can invoke it manually (M-x my/install-packages RET) if you’ve changed my/packages at runtime.
Keep in mind that re-evaluating my/packages after changing it will not do anything because that’s how defvar works. Temporarily change defvar to setq and you’ll be good to go.
cl-lib is required for cl-remove-if. How Elisp has made it this far without a filter function, I don’t know.
I’m not entirely sure if nil punning is idiomatic elisp or if there’s a more appropriate way to check for empty lists. Anyone know?

Bozhidar Batsov is killing it in the Emacs community right now and you should probably be following him. ↩︎
Rather than including what is currently the function body at the top level of the .emacs file. ↩︎

Switching to MELPA Stable: Why, How, What I Learned

Tue, 02 Dec 2014 09:23:59 -0600

Background

Writing my first Emacs package a couple months ago left me more cognizant of how Emacs’ packaging system is put together and raised questions about how I use its capabilities. I had been installing all of my packages from MELPA, but now, as a fancy-schmancy package author I’d become intensely aware that MELPA builds its packages based on the latest commit in a project’s repository¹. Suddenly I’d become paranoid about exactly what I pushed to the master branch of my project and worried about leaving things in a broken state.

Generally speaking, I keep the master branch on my projects in a functional state, and–yes–I could adopt a development methodology whereby work is always done on a development or feature branch and QA’d before being merged into master. But even if I have the inclination and discipline to manage my projects this way, all of my other Emacs packages are getting built from whatever happened to be pushed to master in their own project when the MELPA bot decided to make the rounds. I’ve run my fair share of beta software, but I don’t need every commit as it happens (cutting vs. bleeding edge).

As it turns out, there’s a new kid on the block–MELPA Stable–and she’s come to solve this exact problem.

MELPA Stable contains only stable versions of packages². This means we’re getting new versions of packages when their maintainers feel that the version is ready to ship, rather than any time they make a change to their code.

Stable is also quite cleverly implemented, requiring only a single git tag in semver format to define a release. This not only makes life easy for package maintainers, but promoting semver is good for everyone (even end users!), because a consistent scheme for denoting version compatibility means that developers can write more reliable software.

How to Switch to MELPA Stable

If you’re interested in taking the plunge–and don’t worry, it’s easy to switch back–the first thing to know is that not every package on MELPA is available via MELPA Stable³. If the package creator has not yet defined a stable release, the package will not appear on Stable. Before switching, you’ll probably want to think through the packages you consider critical to your Emacs workflow and type their names into the filter box on the MELPA Stable site to discover if they are available. It is possible to pull packages from two repositories but it’s not trivial and I won’t be covering it here.

Still with me? Let’s get started! The first step, naturally, is to open your .emacs (or .emacs.d/init.el) and change your package-archives form to look like this:

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

Now we’re set to fetch packages from MELPA Stable, but there are a few more steps to make sure your current set-up keeps on trucking:

If you don’t already have one, I’d recommend creating a list in your .emacs file of packages that you use / always want installed. We can kick-start this process by first adding the following to the file:

(defvar my/packages
 ')

With point after the ' character, type C-0 M-: package-activated-list RET to insert a list of the currently activated packages:

(defvar my/packages
 '(artbollocks-mode ace-jump-mode auto-complete checkbox)) ; your list will vary

You may see a few items in your list that you’re not familiar with–feel free to remove anything that you don’t recognize as something you use. These packages are likely to be dependencies of other packages that you use, and they will be automatically included as needed later on. Such packages might include things like queue, dash, pcache, popup, pkg-info, etc.

One “gotcha” of the upgrade process is that the faux version numbers MELPA generates (e.g. 20141116.1658) give the appearance of being higher versions than the proper version numbers from MELPA Stable (e.g. 0.2.0), thus if you have existing packages installed, the package system will never prefer the Stable version, believing that it’s outdated. To solve this you’ll want to delete all of your existing packages. This is easy:

$ rm -rf ~/.emacs.d/elpa

Next we will use our new my/packages list to tell Emacs to install all of these packages when it starts (here I’m using the exact code I outlined in a previous blog post), so add this to your Emacs config after the my/packages definition:

(require 'cl-lib)

(defun my/install-packages ()
 "Ensure the packages I use are installed. See `my/packages'."
 (interactive)
 (let ((missing-packages (cl-remove-if #'package-installed-p my/packages)))
 (when missing-packages
 (message "Installing %d missing package(s)" (length missing-packages))
 (package-refresh-contents)
 (mapc #'package-install missing-packages))))

(my/install-packages)

With a little luck, you’re all set! Restart Emacs. It may take a minute for it to install all of your packages, but if it all appears to finish without error, you’re good to go!

If you encounter errors, continue with the next section.

Robustifying your Config

If you encounter errors after restarting Emacs, it’s likely that your configuration assumed the presence of some package that wasn’t re-installed⁴. Usually you can locate the general source of the error from the error message. For example:

Warning (initialization): An error occurred while loading `/Users/camdez/.emacs.d/init.el':
Symbol's function definition is void: keyfreq-mode
To ensure normal operation, you should investigate and remove the
cause of the error in your initialization file. Start Emacs with
the `--debug-init' option to view a complete error backtrace.

In this case we can tell that we referenced keyfreq-mode before the package which defines it had been loaded. To get out of this situation we have three options:

Remove the offending configuration lines. We can simply find the reference to keyfreq-mode and remove it (or comment it out), but we probably added that for a reason so this should be our last resort.
Install the missing package. Ultimately this is what we want to do. We can typically infer the name of the package by guessing or by searching on stable.melpa.org. For example, keyfreq-mode is defined by the package keyfreq. Once we know the package name we can add it to our my/packages list and restart Emacs.
Make our config robust against the missing package. Even if we ultimately go with option #2, it’s a great idea to make our configuration load whether or not any particular package exists. This means that we can get our (bare-bones) config up and running in any environment, regardless of package availability, including a complete network outage. A complete discussion of this is beyond the scope of this article, but a good starting approach is to wrap the relevant configuration lines in a conditional call which loads the desired package and only executes the configuration line if it succeeds. To do this properly we’ll need to know the symbol used on the (provide '...) line in the package’s source code. Once we have that we can do something like the following:

(when (require 'keyfreq nil 'no-error)
 (keyfreq-mode 1) ; configuration of keyfreq
 (keyfreq-autosave-mode 1)) ; more configuration of keyfreq

Once we’ve taken care of one piece of the configuration like this, we can restart Emacs and see if we have more success. If we have another error, we repeat the process. Admittedly this is a bit of a hassle, but along the way we improve our Emacs config such that it will continue work in a variety of different environments (missing packages, different versions, etc.).

One final note: if you manage to damage your config file to such a degree that you can no longer use Emacs to edit the file, you can always invoke Emacs with an argument instructing it not to load your config file:

$ emacs -q ~/.emacs

This will leave you without any of your customizations, but it will allow you to edit your config file back to a functional state.

My Experience

When I switched to MELPA Stable last November, I found that most of the packages I use were already available. The notable exceptions were guide-key, yaml-mode, and idomenu. I opened an issue for guide-key, added a +1 on the relevant yaml-mode issue, and emailed the author of idomenu, asking to get the packages uploaded to GitHub and tagged with releases for MELPA Stable. These package maintainers have been unanimously awesome, and all of the packages have since been added to Stable.

If you find yourself requesting that package authors / maintainers prepare their package for MELPA Stable, please feel free to use my YASnippet which explains what MELPA Stable is, why it matters, and exactly how to add their package.

Last but not least, between the time I first switched to Stable and now, I’ve personally added / updated four MELPA package recipes for Stable (checkbox, goto-last-change, idomenu, org-table-comment). It’s an easy way to scratch your own itch and make a small contribution to the Emacs community.

That’s it! Enjoy your newfound stability!

Actually the story is a bit more complex because MELPA recipes can pull code from a few different places (e.g. EmacsWiki), but pulling from Git master is probably the most common (and best) story. ↩︎
With real version numbers, not the timestamp-style identifiers regular MELPA is forced to generate! ↩︎
At the time of writing, 40% of MELPA packages are available via MELPA Stable (955 / 2397). ↩︎
A less likely possibility is that your config assumed the presence of a newer version of the package than that which was installed. In this case you don’t have a lot of options—you’ll need to adapt your configuration to the older version of the package if you wish to stick with Melpa Stable. ↩︎

Emacs Hangouts

Wed, 19 Nov 2014 19:00:22 -0600

Two weeks ago I had the pleasure of participating in an Emacs-themed Google Hangout arranged by Sacha Chua, in which several of us Emacs geeks got together and discussed what we’ve been working on, questions we have about particular packages or workflows, etc.:

I don’t think any of use knew exactly what to expect, but we talked a bit about the different autocomplete frameworks (auto-complete-mode and company-mode), org-mode, wrap-region, and I yapped a bit about Emacs testing tools and BDD.

Today I got to fill in for Sacha and host the second of these Hangouts:

Today’s chat dove into magit trickery, org-present, achieving Vim parity via evil-mode, use-package, and switching to Dvorak.

Many thanks to @jjasghar, @amirrajan, @mwfogleman for speaking and sharing their expertise. I’m really enjoying these and I hope interest stays high so we can keep them going.

Finally, sorry for the technical difficulties at the beginning of the recording–I really hope everyone who wanted to join was able to! This was my first time hosting a Hangout-on-Air and it’s a bit quirky. For future reference, the thing that really tripped me up is how little integration there is between the Hangout and the event page for it. The RSVP list has nothing to do with the people who get to participate in the Hangout–all it does is send a reminder to those people to view the event–and there’s no way to invite those people to become participants once it has started. AFAIK the only thing you can do is to copy the URL visible inside of the Hangout (not clearly marked for participation rather than viewing) and post it on the event page and / or the in-Hangout chat.

Anyway, thanks for your patience and if I host another one I’ll know what to do!

μProject: checkbox.el

Mon, 17 Nov 2014 09:31:34 -0600

I’ve been playing with Emacs in the evenings lately and writing a lot of Elisp, and I just finished a little Emacs package for quickly manipulating textual checkboxes ([ ] / [x], etc.) in buffers, like a simple version of org-mode’s task manipulation, but available everywhere. It’s called checkbox.el.

For example, 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>

checkbox.el understands how to work with comments in programming modes, tries to be smart about when and where it moves point (DWIM!), allows for a fully custom set of “checkboxes” (e.g. TODO, DONE, HOLD), can remove checkboxes entirely with a universal argument (C-u), or directly select a particular checkbox state (rather than cycling through them) when given a numeric prefix.

It also has a fairly extensive test suite leveraging ert, ecukes, and continuous integration via Travis CI. Check out checkbox.el on GitHub or install it via MELPA or Marmalade!

Emacs: Rapid Buffer Navigation with Imenu

Thu, 28 Nov 2013 15:32:00 -0700

Kris Jenkins wrote a great post last month about rapidly navigating Clojure files in Emacs using Helm–definitely check it out. Helm is near the top of my list of Emacs extensions I need to explore, but in the meantime I thought I’d point out that’s there actually a great solution for this use case in a stock Emacs installation–imenu-mode.

Imenu is a really slick library by Ake Stenhoff and Lars Lindberg which scans the open buffer and creates a menu of locations–usually representing top-level items like functions–that you can rapidly jump to. The mode gets just about everything right: it’s widely supported, easily extensible, uses markers to track buffer locations (so they stay correct even as you edit the file), supports auto-updating, and is available via either the GUI (for you mousey types) or the keyboard. It’s really a stellar example of the flexibility and extensibility of Emacs.

Basic usage involves running the imenu command (M-x imenu RET) and entering the name of the item you want to jump to. Hit TAB to see a list of all possible jump targets. (If you’re an ido user, check out this gist from the always-wonderful Magnar Sveen to get your integration on.)

But honestly, a lot of the magic is in the GUI menu–even for those of us who usually neglect the mouse.

You’ll need to run the imenu-add-menubar-index command to get things up and running but once you do you’ll see a new menu named Index in your menu bar:

Clicking an item in the menu will jump you directly to it.

If you want the menu to be available automatically for certain modes, all you have to do is add the trigger function to the respective mode hooks, like so:

(add-hook 'clojure-mode-hook 'imenu-add-menubar-index)
(add-hook 'emacs-lisp-mode-hook 'imenu-add-menubar-index)

One additional tweak that you’ll probably want to add to your .emacs file is to automatically rescan the buffer contents so that new jump targets appear in the menu as they are added:

(setq imenu-auto-rescan t)

Most Emacs modes (clojure-mode included) already implement Imenu support, but it’s actually pretty easy to extend Imenu’s functionality to any kind of content we want to index. In fact, one of my favorite uses is not even for programming–it’s my extension to Markdown mode, allowing me to jump to document section headers.

The most full-featured way to implement Imenu for a mode is to implement imenu-create-index-function, providing a custom function which creates a data structure in the format Imenu is expecting (see imenu.el for details), but the easiest way is simply to provide a regular expression for the items we want to match and let Imenu do the rest.

Here’s what that looks like for markdown-mode:

(defvar camdez/markdown-imenu-generic-expression
 '((nil "^#\\s-+\\(.+\\)$" 1)))

(defun camdez/markdown-imenu-configure ()
 (interactive)
 (setq imenu-generic-expression camdez/markdown-imenu-generic-expression))

(add-hook 'markdown-mode-hook 'camdez/markdown-imenu-configure)

This pattern will work for most any usage. We define a generic expression (more on this in a sec), and when the given mode is activated, we put that expression in imenu-generic-expression, a predefined location where Imenu expects to find such a thing (unless you’ve provided a full imenu-create-index-function implementation).

The simplest version of this “generic expression”, shown here, is (MENU-TITLE REGEXP INDEX); MENU-TITLE defines where to nest the new menu item (or nil, as we do here, to put it at the top level), REGEXP is the regular expression matching the content we want to index, and INDEX specifies which piece of the match we want to insert in the menu. We could pass 0 to include the whole expression in the menu, but in this case I’ve decide to match strings with look like # Foo, but only put the Foo part into the menu (note the subpattern offset by \\( and \\)). Also notice that imenu-generic-expression is a list of lists so that you can provide multiple patterns to match, each with their own rules on where to nest and what to display.

That’s really all there is to it. Let me know if you have any really novel uses for Imenu, I’d love to hear about them!

Emacs: Jump to Info from Command Documentation

Wed, 27 Nov 2013 15:06:00 -0700

One of the coolest things about Emacs is that it’s self-documenting. What this means is that for any piece of functionality in Emacs, we can ask the editor about that thing. We can ask it to tell us about any function (C-h f), variable (C-h v), key binding (C-h k) or even the mode(s) we’re currently in (C-h m). Most of the time this documentation is comprehensive and heavily cross-referenced. If you’re not using these commands, you absolutely should start today.

Emacs also comes bundled with a detailed user manual (C-h r – think, read the manual), which is important when you don’t know exactly what you’re looking for, or if you want to see a command in the context of related functionality. Maybe you know about kill-word and kill-sentence but they aren’t exactly what you’re looking for – the manual is the first place to check to learn about (say) kill-sentence or kill-sexp.

Somewhat less well-known is the handy Info-goto-emacs-command-node command (on C-h F) which will take you directly to the Emacs manual page that talks about a given command. But unless we’re coding in Elisp, most of the time we work in terms of keystrokes and not command names. Wouldn’t it be more useful if we could look at the documentation for given key sequence and then, if we wanted more information, easily jump to the corresponding manual page? Let’s code that up:

(defun camdez/Info-goto-from-command-help ()
 "Go to the Info node in the Emacs manual for the command
currently being viewed in `help-mode'."
 (interactive)
 (let ((help-function (car help-xref-stack-item))
 (help-symbol (cadr help-xref-stack-item)))
 (if (and (eq help-function 'describe-function)
 (commandp help-symbol))
 (Info-goto-emacs-command-node help-symbol)
 (error "Info is only available for commands"))))

(Note that we have to do a couple tests on help-xref-stack-item because we can only jump into the manual for commands, and not for arbitrary functions or variables.)

Now let’s bind that to the (previously unused) i key in help-mode:

(eval-after-load 'help-mode
 '(define-key help-mode-map "i" 'camdez/Info-goto-from-command-help))

And we’re done! After putting that in your .emacs file and restarting Emacs (or reloading the config), try it out with something like C-h k C-k (“what does the C-k keystroke do?”) and then press i in the *Help* buffer.

Emacs: Show Buffer File Name

Thu, 14 Nov 2013 22:53:00 -0700

I share my Emacs configuration on GitHub, but the truth is that most of the fun stuff happens in my experimental.el file (mentioned previously), which I don’t share. It’s growing rather large and some of the contents are fairly mature so I’m going to going to work on moving more things into my stable config and I may as well share them along the way.

One little utility I’ve grown quite fond of is my show-buffer-file-name utility:

(defun camdez/show-buffer-file-name ()
 "Show the full path to the current file in the minibuffer."
 (interactive)
 (let ((file-name (buffer-file-name)))
 (if file-name
 (progn
 (message file-name)
 (kill-new file-name))
 (error "Buffer not visiting a file"))))

…which I keep on C-x C-p, overriding the fairly useless mark-page command:

(global-set-key (kbd "C-x C-p") 'camdez/show-buffer-file-name)

It’s fairly self-explanatory but notice that it not only shows you the path to the current file but also leaves it on the kill-ring. I find this to be pretty useful when switching to the shell to operate on a file (though obviously there are lots of ways to do such things within Emacs), and for pasting filenames into GitHub discussions, emails, or the company chat room.

Emacs: Tab Width Woes

Mon, 06 Aug 2012 20:03:00 -0700

Emacs uses the value of the tab-width variable to decide how wide tab characters should be displayed. Setting tab-width is usually one of the first customizations Emacs newbies make:

(setq-default tab-width 2)

Displaying tab characters at whatever width you prefer works well for most applications but eventually fails when files mix tab and space characters and (invariably) make assumptions about what the width of those characters will be.

One particularly conspicuous offender is the Emacs (Lisp) source code. I feel like I’ve recently reached a new level of skill with Emacs–a point where I’m finally effective enough with it that I write Emacs Lisp to improve my workflow as a regular part of my daily workflow. One consequence of this is that I spend a lot of time reading Emacs source code, looking for either implementation clues or undocumented gems. It’s a hell of a lot of fun but unfortunately it means that I spend a lot of time alternating between my preferred tab-width of 2 and 8, the size the Emacs source thinks a tab should be.

My initial solution was to throw together a quick function to toggle between these two values, which I bound to C-c TAB:

(defun camdez/toggle-tab-width ()
 "Toggles `tab-width' between 8 and 2."
 (interactive)
 (setq tab-width
 (if (= tab-width 2)
 8
 2))
 (message "Tab width set to %d" tab-width))

It could definitely use a lot of improvement but that’s the kind of thing that I now tend to hammer out quickly and improve later if the concept survives the prototyping phase. I keep this type of hacks in a file called experimental.el which I load from my Emacs initialization file. I also keep this file in the x register so that I can immediately jump to it with C-x r j x:

(load-library "experimental")
(set-register ?x (cons 'file "~/.emacs.d/experimental.el"))

But I was never thrilled about the idea of having to manually toggle that value, even if it was a couple keystrokes away. I started scheming about ways to analyze source files to determine what tab-width they implied (certainly possible–not a lot of fun) when I realized that the Emacs source was really the only place where I was having this problem.

My next thought, then, was to create a hook that would fire whenever a file was opened, examine the file path, and set the tab-width to 8 if it was part of the Emacs distribution. But hardcoding a file path? That’s a bit distasteful.

I realized today that there’s a wonderfully effective, simple solution called “Directory Variables”. All you have to do is put a file called dir-locals.el in a directory and whenever Emacs visits a file in that directory (or one of it’s subdirectories), those local variables will be loaded and applied. In fact, there’s even a command that will build the file contents for us. Here’s how we can set it up for the Emacs source:

Open a file in the Emacs lisp directory. The easiest way to this is pull up the documentation for a function in the standard distribution (say, occur) with C-h f occur RET, tab to the file name it says it’s defined in, and hit RET to jump to that function’s definition.
Next, run M-x add-dir-local-variable RET.
Hit RET to accept the default of only applying this variable to emacs-lisp-mode.
Enter tab-width as the variable to set.
Enter 8 as the value of the variable.
You’ll now be looking at a new file with contents like this:

;;; Directory Local Variables
;;; See Info node `(emacs) Directory Variables' for more information.

((emacs-lisp-mode
 (tab-width . 8)))

Save the file with C-x C-s and you’re good to go. Now whenever you open a file in the Emacs source code it’ll have the tab-width properly set to 8.

Emacs: Save, Not Search!

Mon, 26 Mar 2012 13:39:00 -0700

I’m a compulsive saver. No, not with money–files. It probably comes from using Photoshop in the 90s, but regardless, I probably save hundreds of times a day.

Sometimes in Emacs I fat-finger C-x C-s (save-buffer) and end up landing in search mode instead (C-s–isearch-forward). Then I have to C-g or ESC ESC ESC my way out before actually saving.

I recently learned (again, from having clumsy fingers) that isearch-mode actually understands C-x C-s, so you can just hit it to save the file and exit search mode in one go. In fact, it actually seems to be pretty clever about only eating keystrokes it understands and otherwise exiting isearch-mode and passing them along. Check out the docs for isearch-other-meta-char for details.

Emacs: transpose-lines

Tue, 21 Feb 2012 16:58:00 -0700

The command transpose-lines, bound to C-x C-t by default, is a standard Emacs workhorse. It exchanges the line point is on with the previous line. Because it also moves point down a line we can invoke it repeatedly to “drag” a line down:

one two two two two
two< one three three three
three --> three< --> one --> four --> four
four four four< one five
five five five five< one
 <

This is particularly handy for reordering lists. We can also give it a numeric argument or a negative argument and these do what you’d expect (C-h f transpose-lines RET for details), transposing over distances or in reverse direction.

But what I did not know is that if invoked with a M-0 prefix, it will exchange the line point is in with the line mark is in, essentially allowing us to insert a line at an arbitrary location we had previously marked.

I have to say, this definitely beats my typical C-a C-k C-k (movement) C-y workflow, assuming I know the destination ahead of time.

Update: turns out I got a little excited and didn’t think through the details of what I was saying. The semantics of those two scenarios are different–M-0 C-x C-t swaps the two lines whereas the other simply inserts the killed line, but doesn’t move the line at point to where mark was. Mea culpa.

Here’s a quick-and-dirty function for your .emacs to get the behavior I claimed:

(defun move-line-to-point ()
 "Insert the line mark is in before the current line."
 (interactive "*")
 (save-excursion
 (exchange-point-and-mark)
 (beginning-of-line)
 (kill-whole-line)
 (exchange-point-and-mark)
 (beginning-of-line)
 (yank)))

Emacs Windowing Improvements

Wed, 28 Feb 2007 00:00:00 -0700

One element of Emacs’s behavior that annoyed me for quite a while is Emacs’s handling of windows (or rather, the natural consequence of having multiple windows which arrive at various times). Often I end up with a random window that I really don’t want to be there. Usually the window is occupied by a temporary buffer (or something like *info*) which has outstayed its welcome.

In most cases point is not in the window, so I have to switch to the other window and then kill the buffer with C-x o C-x k RET. But then I still have the window sitting around occupying space in front of the code I was actually trying to look at. So next I eliminate the window with C-x 0.

You see why this is annoying. I’m using seven keystrokes (C-x o C-x k RET C-x 0) just to clean up the mess from a temporary buffer. Of course this is Emacs, so a solution is only an elisp hack away. So I defined two new functions which relieve my woes:

(defun delete-window-replacement (&optional; p)
 "Kill current window. If called with PREFIX, kill the buffer too."
 (interactive "P")
 (if p
 (kill-buffer nil))
 (delete-window))

(defun delete-other-windows-replacement (&optional; p)
 "Make the selected window fill its frame. If called with PREFIX,
kill all other visible buffers."
 (interactive "P")
 (if p
 (dolist (window (window-list))
 (unless (equal (window-buffer window) (current-buffer))
 (kill-buffer (window-buffer window)))))
 (delete-other-windows))

I bind these in place of the original delete-window (C-x 0) and delete-other-windows (C-x 1):

(global-set-key "C-x0" 'delete-window-replacement)
(global-set-key "C-x1" 'delete-other-windows-replacement)

My functions work exactly as the built-ins they replace unless they are given a prefix argument (in fact they call the original functions). So now, if point is in a window I don’t want, which contains a buffer I don’t want, all I have to do is C-u C-x 0 and I’m back to my original work. Or, if my cursor is sitting in my original code, and the other buffer is the problem, I type C-u C-x 1. It’s natural enough that I’d like to see it in the default Emacs distribution.

Adding Emacs / PyBlosxom Support for a Custom Format

Wed, 04 Jan 2006 00:00:00 -0700

In PyBlosxom, blog entries are stored in regular files rather than in a database. This means that I can write my entries in Emacs (hurrah). PyBlosxom can handle posts in any format it has a parser for.

The simplest parser removes the metadata from the beginning of the file and passes the remainder of the file directly to the output webpage. Ergo, in the most simple format, the entries should be written in html (with a basic text header). More complicated parsers could be used for formats like xml or wiki markup. PyBlosxom uses a file’s file extension to determine what format the entry file is in.

For some unusual reason PyBlosxom associates the simple pass-through parser with .txt files (wouldn’t it make more sense to use .html?). In any case, I decided that I wanted to add my own file extension, .blog, so that I could easily distinguish my blog posts from other text files and html files on my system and so that my editor could treat the files specially.

The first step was to make PyBlosxom recognize the files as entries which it knows how to parse (anything PyBlosxom doesn’t have a parser for will simply be ignored).

On line 79 in pyblosxom.py, is a block of code which I modified as follows:

# entryparser callback is run here first to allow other plugins
# register what file extensions can be used
data['extensions'] = tools.run_callback("entryparser",
 {'txt': blosxom_entry_parser, 'blog': blosxom_entry_parser},
 mappingfunc=lambda x,y:y,
 defaultfunc=lambda x:x)

This is sufficient to make PyBlosxom treat .blog files just like .txt files.

The next step was to make the files easier for me to write. First off, Emacs should open the files in html-mode. Adding the following bit of code to my .emacs file accomplishes this task:

(add-to-list 'auto-mode-alist '("\\.blog\\'" . html-mode))

The next step requires a tiny bit of background information on the format of PyBlosxom entries. The basic format of a PyBlosxom entry looks like this:

Title Of Entry
#metadata-1 value-1
#metadata-2 value-2
(...)
#metadata-N value-N

Post line 1.
Post line 2.
(...)
Post line N.

Note: the blank line is not required, but it makes the file more (human-) readable.

I always use the same two metadata lines: #postdate (from my metadate.py), and tags (from Joe Topjian’s tags.py). Because of this there are a few lines which are similar across all of my blog posts. Why not have my editor enter these automagically, including entering the current #postdate (in the format YYYY-MM-DD HH:MM)? How convenient that Emacs provides a mechanism just for this purpose: skeletons.

I wrote the following code and added it to my .emacs file:

(define-skeleton blog-entry-skeleton
 "Inserts a PyBlosxom-style blog entry skeleton into the current buffer.
This only makes sense for empty buffers."
 "Title: "
 str | "Untitled Entry" \n
 "#postdate " (insert-date-and-time) \n
 "#tags " ("Enter a tag: " str ",") '(delete-backward-char 1) \n \n
 "<p>" _ "</p>")

When executed, this skeleton prompts the user for a title (if the user simply presses RET it defaults to Untitled Entry), repeatedly prompts the user for tags (keywords) (until the user simply presses RET), enters the current #postdate automatically, and the leaves the cursor inside a new <p>

The final touch is to make the skeleton automatically execute when a new .blog file is created:

(eval-after-load "autoinsert"
 '(add-to-list 'auto-insert-alist '("\\.blog\\'" . blog-entry-skeleton)))

It’s like magic!