(or emacs

Happy New Year 2022!

2021-12-31T00:00:00+01:00

Intro

In 2020, I managed to squeeze out just one post. Well, 2021 ran out just as fast as 2020. So here we are:

   2020-12-31-happy-new-year.md
  +2021-12-31-happy-new-year.md

This year, I'll review a really cool package I've found. It's not new, I just didn't manage to stumble upon it over the years. So it's new to me, and might be a useful pointer to others as well.

Emmet-mode

Emmet-mode is a wonderful Emacs package which greatly improves HTML code generation. It's based on Emmet, so you can read up on the syntax here. I've discovered it quite recently after reading Arjen Wiersma's 22-years-of-emacs.

The gist is that ul#nav>li.item$*4>a{Item $} will expand to:

<ul id="nav">
    <li class="item1"><a href="">Item 1</a></li>
    <li class="item2"><a href="">Item 2</a></li>
    <li class="item3"><a href="">Item 3</a></li>
    <li class="item4"><a href="">Item 4</a></li>
</ul>

The above reminded me of tiny.el, the concept of using *4 to create four items, and $ for automatic numbering is very similar.

Emmet goes above and beyond the 3 yasnippets I had in my config for inserting HTML tags. Note also the handy html:5 snippet, which expands to:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8"/>
    <title>Document</title>
  </head>
  <body></body>
</html>

And as a cherry on top, when used in clojure-mode, these snippets will produce hiccup.

Getting emmet-mode for free

As I wrote earlier (feels like ages ago), I like to get functionality for free, i.e. without having to sacrifice any old key bindings or learning new key bindings. So I've integrated the code of emmet-expand-line with C-o (ora-open-line).
Here is the relevant cond branch:

((and
  (require 'emmet-mode)
  (setq expr (emmet-expr-on-line))
  (setq markup (emmet-transform (first expr))))
 (delete-region (second expr) (third expr))
 (emmet-insert-and-flash markup)
 (emmet-reposition-cursor expr))

We check if emmet-mode has detected a valid snippet at point. In that case, expand it. This allows us to chain multiple snippet engines (like yasnippet, auto-yasnippet, tiny, emmet-mode), and even provide a hydra as a fallback for even more easy to reach commands on C-o!

Personal

Our son, Lev, was born on May 7, 2021. He is our love, happiness, our shining light in 2021. And also the reason why I didn't have too much free time to do Emacs stuff. Big thanks to Basil L. Contovounesios for helping me maintain Ivy! I'm hoping to be much more active on Github in 2022.

In other personal news, I'm currently looking for a new job as a Software Engineer. If you'd like me to work with you, please get in touch via LinkedIn or Twitter. Also, a big thanks to everyone donating to support my open-source work. It means a lot.

Outro

I wish everyone reading this good health in 2022! And happy hacking!

Happy New Year!

2020-12-31T00:00:00+01:00

Intro

As 2020 is almost running out, I have noticed that I didn't manage to post anything this year. So here's a haphazard attempt to fix that.

Org-roam

I'd like to share a wonderful Emacs package I've started using this year: org-roam. Even though in my Org notes I see that I encountered this package in February 2020, I've actually started using it on December 10, trying to figure out what Zettelkasten are and how to deal with them.

Overall, 22 days isn't a whole lot of experience, and I'm looking forward to see how useful Zettelkasten and org-roam will be to me in a year. But I already have written down 341 notes, which amounts to around 15 notes per day.

In my previous/current system, plain-org-wiki, I organize my knowledge into 209 tag categories. For instance, one of them, Linux, has 290 entries. Another, VPN, has 15 entries. I'll show an example of how org-roam improved my workflow by showing a note I've added:

#+title: Use a custom DNS when resolving a specific host on Linux

On Linux, I have a DNS server that can resolve certain VPN-only websites. But the problem is that it's only available if I'm connected to my work VPN. So I can't configure it in a common way, since the common way would simply use that DNS always, whether or not it's up. The =dnsmasq= package solves all these issues.

The code: local, and permalink

Above is one zettel - a note named "Use a custom DNS when resolving a specific host on Linux" that's liked to two other notes: "Linux", and "DNS". Both of those notes are basically empty files that are used for tagging purposes. I use M-x org-roam-buffer-activate to see what other notes are linked to them.

Suppose, instead of using org-roam, I wanted to add the above piece of knowledge to my old system of tagged data. Does this information belong in Linux.org or in VPN.org? Moreover, do I really want to add one more entry to Linux.org? It's getting really crowded with 290 entries already there. So with the old system, it's the anxiety on where to put the note combined with the pressure of keeping it short. Both things are solved by using Zettelkasten!

Org-roam config

Here's my config for org-roam so far.

All of the functionality that I use is in the hydra below:

(defhydra hydra-org-roam (:exit t :idle 0.8)
  "Launcher for `org-roam'."
  ("i" org-roam-insert "insert")
  ("f" ora-org-roam-find-file "find-file")
  ("v" org-roam-buffer-activate "backlinks")
  ("t" ora-roam-todo "todo"))

The only difference between ora-org-roam-find-file and org-roam-find-file is that my variant supports ivy actions.

And ora-roam-todo is a small wrapper around this code, which gives me an overview of loose ends in my notes that I'd like to follow up on:

(progn
  (setq unread-command-events
        (listify-key-sequence (kbd "C-c C-o M->")))
  (counsel-rg "^\\* TODO" org-roam-directory "--sort modified"))

What the above does technically: runs counsel-rg on my org-roam-directory looking for * TODO, while sorting on the file modification date, instead of the default sorting by path. Here, C-c C-o is the binding of ivy-occur, and M-> is end-of-buffer. And the whole code overall produces an ivy-occur buffer without having to go into minibuffer and press C-c C-o manually. The unread-command-events trick is a nice way to automate this.

Outro

I'd like to thank the creators of org-roam. Well done!

Happy New Year! I wish everyone good health, justice, equality, and happiness!

Ivy 0.13.0 is out

2019-10-16T00:00:00+02:00

Intro

Ivy is a completion method that's similar to Ido, but with emphasis on simplicity and customizability.

Overview

The current release constitutes of 183 commits and 3 months of progress since 0.12.0. Many issues ranging from #2153 to #2278 were fixed. The number of people who contributed code as grown to form 148 to 160. Thanks, everyone!

Details on changes

Changelog.org has been a part of the repository since 0.6.0, you can get the details of the current and past changes:

in org-mode
in HTML

Highlights

Many improvements are incremental and don't require any extra code to enable. I'll go over a few selected features that require a bit of information to make a good use of them.

New bindings

counsel-find-file
- ~~ to move to the local home directory from remote or /sudo::.
- / RET ~ achieves the same thing, but is longer.
- M-o R calls find-file-read-only.
counsel-git-grep
- C-x C-d to switch the current directory.
swiper-isearch
- M-o w to copy the current line and go back to where you started.

New features

`counsel-package`

The idea of counsel-package is to install and remove packages with a single binding:

(global-set-key (kbd "C-c P") 'counsel-package)

But if the package contents weren't up to date, a separate M-x package-refresh-contents had to be triggered, which was an annoying overhead. Now counsel-package will look at the time stamps of the appropriate archive-contents files, and call package-refresh-contents if the timestamp is outdated by more than 4 hours.

`counsel-M-x`

Some commands are intended to be called only via their key binding. Make them disappear from counsel-M-x like this:

(put 'counsel-find-symbol 'no-counsel-M-x t)

`counsel-rg`

The default setting of ivy-case-fold-search-default is 'auto, which means:

the input "emacs" matches "emacs", "EMACS", and "Emacs"
the input "Emacs" matches only "Emacs"

This now also applies to counsel-rg: Ivy will pass the -i flag to ripgrep appropriately, based on ivy-case-fold-search-default. You should remove the -S flag from counsel-rg-base-command if you customized it.

`ivy-update-candidates`

This is a new API for asynchronous calls. To use it, pass to ivy-read: :dynamic-collection t, and a collection function that takes a user input string, starts some asynchronous process based on that input, and returns 0. The 0 return result tells Ivy that no candidates were returned; instead, ivy-update-candidates is used in the async callback.

See counsel-google for a reference implementation.

`ivy-use-virtual-buffers`

You can now choose between: recent files, or bookmarks, or both, or none. Don't forget that counsel-set-variable makes it very easy to set customization options.

New Commands

I have put these separately so they don't get lost in the crowd. Be sure to try them out.

counsel-buffer-or-recentf - list buffers visiting files (highlighted) then the recentf file list.
counsel-fonts - show a list of all supported font families for a particular frame.
counsel-google - asynchronously query the Google predictive search API.
counsel-major - switch major-mode.
counsel-slime-repl-history - browse SLIME REPL history.

Outro

Again, thanks to all the contributors. Happy hacking!

PS. Thanks to everyone who supports me on Liberapay and Patreon!

I am now also on Github sponsors, which is an interesting new effort by Github. The cool thing is that's more integrated with Github, there are less transaction fees, and Github matches every donation for up to $5000 for a whole year. Please consider joining there, since every $1 per month that you donate is doubled by Github.

Ivy 0.12.0 is out

2019-07-20T00:00:00+02:00

Intro

Ivy is a completion method that's similar to Ido, but with emphasis on simplicity and customizability.

Overview

The current release constitutes of 398 commits and 6 months of progress since 0.11.0. Many issues ranging from #1904 to #2151 were fixed. The number of people who contributed code as grown to 148. Thanks, everyone!

Details on changes

Changelog.org has been a part of the repository since 0.6.0, you can get the details of the current and past changes:

in org-mode
in HTML

Highlights

Many improvements are incremental and don't require any extra code to enable. I'll go over a few selected features that require a bit of information to make a good use of them.

New bindings

counsel-descbinds
- M-o x execute action.
counsel-file-jump
- M-o d dired.
counsel-find-file
- M-o c copy file.
- ` bookmarks: efficiently jump between recent directories.
- $ directories stored in environment variables.
- C-DEL go up directory. Customize: counsel-up-directory-level.
- RET open file. Customize: counsel-find-file-extern-extensions.
- // when on remote, cd to remote root.
- / C-j select local root.
- ~ when on remote, cd to remote home.
- / C-j ~ cd to local home from remote.
counsel-git-log
- M-o v open the current commit in magit.
counsel-rg
- C-x C-d change the current directory for grep.
ivy-avy
- C-v to scroll down.
- M-v to scroll up.
ivy-read C-o
- m mark and move down.
- u unmark and move down.
- DEL move up and unmark.
- t toggle marks.
- d perform the action on all marked elements.
ivy-switch-buffer
- C-k kill buffer.
- M-o x open buffer file externally.
ivy-reverse-i-search
- C-k remove item from the history.

New Commands extensions

These commands are new variants and adaptations of existing commands.

Thing at point variants:

swiper-all-thing-at-point.
swiper-isearch-thing-at-point.
swiper-thing-at-point.

Search variants that go backwards:

swiper-backward.
counsel-grep-or-swiper-backward.
swiper-isearch-backward.

A variant of ivy-switch-buffer with live preview:

counsel-switch-buffer.
counsel-switch-buffer-other-window.

And finally:

counsel-dired - like counsel-find-file, but open dired.
swiper-isearch-toggle - toggle between swiper and isearch.

New Commands

I have put these separately so they don't get lost in the crowd. Be sure to try them out.

counsel-compile - completion for compile.
counsel-register - completion for registers.
counsel-minor - completion for minor modes.
swiper-isearch - a faster swiper that's not line-based.

Outro

Again, thanks to all the contributors. Happy hacking!

Ivy reverse-i-search

2019-07-09T00:00:00+02:00

Introduction

I'm sure many are aware of the C-r functionality in bash (a whole lot of Emacs bindings are valid in bash and do the same thing). I also like the quirky Emacs-style prompt, that uses a backquote to open and a straight quote to close a your quoted input:

So when you want to cd to somewhere where you were before you do C-r cd. And then the C-r "roulette" begins: you keep pressing C-r over and over, in the hopes to find what you were looking for.

Getting better history completion with Ivy

Ivy improves the "roulette" situation in two ways:

You get an overview of the matching candidates and their count,
You can quickly narrow down the candidates with fuzzy matching.

Here's the basic setup to enable C-r completion using ivy:

(define-key minibuffer-local-map
    (kbd "C-r") 'counsel-minibuffer-history)
(define-key shell-mode-map
    (kbd "C-r") 'counsel-shell-history)

The first key binding is also part of counsel-mode, while the second needs to be set up separately, after shell-mode was loaded.

And here's how counsel-shell-history looks like:

The cool thing is that ivy-reverse-i-search applies to any Ivy command, not just for shell command completion. I find it especially useful for:

counsel-find-file
eval-expression

Recent improvement: delete history items

While searching with regexes is great, it's not so great when the old stuff that we won't ever need gets in the way. So now you can delete it with C-k. Since C-k also has to serve as ivy-kill-line, the history deleting behavior will only come into effect when the point is at the end of the line (so that ivy-kill-line does not make sense anyway).

This way, your typos don't stay around to haunt you.

Outro

I hope you'll find ivy-reverse-i-search a useful boost to your completion needs. Happy hacking!

Ivy usability improvements when dealing with directories

2019-06-27T00:00:00+02:00

Introduction

When Ivy just started out as a completion framework, the functionality was supposed to be simple: select one string from a list of strings. The UI is simple enough:

Show the list of strings that match the entered text,
Use C-n and C-p to navigate them,
Use C-m or C-j to submit.

Emacs has three key bindings that mean "Enter": RET, C-m, and C-j. But in terminal mode, emacs -nw, RET and C-m are the same binding: Emacs can't distinguish them. So we have at most two bindings. Fortunately, the world of completion is simple at the moment, and we only need one binding.

File name completion

Enter file name completion. When you're completing file names, you are selecting not one string, but many strings in succession while moving from one directory to the next. So we need at least two key bindings:

Use C-m (ivy-done) to select the current candidate and exit completion.
Use C-j (ivy-alt-done) to change the current directory to the current candidate without exiting completion.

What to do when C-j is used on a file and not on a directory? Might as well open the file: same action as C-m. OK, we had two key bindings, and we have used them. Hopefully nothing else comes up.

Enter creating a new file, i.e. selecting something that's not on the list of strings. Suppose I call find-file, enter "do", and the only match is a directory named "doc":

Pressing C-m will end completion with the "doc" directory selected.
Pressing C-j will continue completion inside the "doc" directory.

So creating a file named "do" is the third action. Our two "Enter" keybindings are already taken by the first two different useful actions. So we need a third key binding. The one I chose is C-M-j (ivy-immediate-done). It means: I don't care that the current input is not on the list of candidate strings, submit it anyway.

Directory creation

Enter directory creation: dired-create-directory and make-directory. These built-in Emacs commands request file name completion, but what they tell Ivy is no different from what find-file tells: "I want to select a file". However, for these commands, the C-M-j action is the one that makes most sense. Here it would be nice for Ivy to take the back seat and just act like an interactive ls, since the user will enter a completely new string that's not on the list of candidates.

For a long time, you still had to use C-M-j with those commands, to much frustration of new but also existing users, including myself. But a few days ago, I looked at the prompt that dired-create-directory uses: "Create directory: ". That prompt is passed to Ivy. Using the prompt to detect the intention of the command is a bit of a hack, but I think in this case it's justifiable. So now Ivy will recognize that the intention commands that request file name completion and pass the "Create directory: " prompt is to create a directory, and all key bindings will do just that: C-m, C-j, and C-M-j will behave the same in this case.

An alternative key binding scheme

Note that C-m and C-j behave differently only for directories. But thanks to the fact that "." is always the first candidate, C-m for directories is equivalent to C-j C-j. So we can get away with just using ivy-alt-done, and bind C-m to ivy-immediate-done. Or swap the two meanings:

(define-key ivy-minibuffer-map (kbd "C-j") 'ivy-immediate-done)
(define-key ivy-minibuffer-map (kbd "C-m") 'ivy-alt-done)

The price to pay here is the extra context switch when we simply want to select a directory. We could the bind ivy-done to C-M-j and avoid the context switch, but then we're back to three bindings once more. Still, I thought that swapping the bindings is an interesting idea worth sharing.

Canceling `dired-dwim-target`

Setting dired-dwim-target is a nice productivity boost. It allows to use Emacs in a similar way to a two-pane file explorer, like mc(1). But it was really annoying when I was in dir-1 with the intention to copy a file to a different name in dir-1 (e.g. create a backup, or copy a template), but the current directory was set to dir-2 because of a random dired window I had open. In that case, I had to call delete-other-windows, perform the copy, and then restore the window configuration with winner-undo.

I did the above many times over many years, until I finally dug into the code of dired.el to see how dired-dwim-target worked. Turns out it was storing dir-1 in the minibuffer-defaults variable. So now Ivy will use that variable when I press M-n. All in all, it was a five minute fix. But rather than regret that I didn't do it years ago, I'm glad I did it now. It only remains to build some muscle memory to press M-n in that situation.

I'm guesstimating that dired-dwim-target works to my advantage 90% of the time when I press C in dired. For the other 10% of the times, I can now press M-n.

Outro

I hope you find the new functionality useful. I'm always open to new ideas and pull requests. Happy hacking!

hydra 0.15.0 is out

2019-05-18T00:00:00+02:00

This release consists of 45 commits done over the course of the last 2 years. With this version, I have introduced a Changelog.org, similar to what ivy and avy have.

Highlights

Display hints using posframe

A new defcustom hydra-hint-display-type was introduced that can be either lv (the default), message, or posframe.

Posframe is a package that leverages a new feature in Emacs 26.1: the ability to display child frames. The advantage of using child frames is that you can easily position them anywhere within your frame area. For example, the default setting is to put it in the center of the current window, which is closer to where your eyes are focused than the minibuffer. Child frames don't interfere with the content of the buffers which they overlap. Finally, you can select a different font for the child frame.

Less boilerplate in defhydra

You no longer have to add :hint nil, and you can skip the docstring as well:

(defhydra hydra-clock (:exit t)
  ("q" nil "quit" :column "Clock")
  ("c" org-clock-cancel "cancel" :column "Do" :exit nil)
  ("d" org-clock-display "display")
  ("e" org-clock-modify-effort-estimate "effort")
  ("i" org-clock-in "in")
  ("j" org-clock-goto "jump")
  ("o" org-clock-out "out")
  ("r" org-clock-report "report"))

Add heads to an existing hydra

You can now add heads to an existing hydra like this:

(defhydra hydra-extendable ()
  "extendable"
  ("j" next-line "down"))

(defhydra+ hydra-extendable ()
  ("k" previous-line "up"))

The new macro defhydra+ takes the same arguments as defhydra, so it's quite easy to split up or join your hydras.

The use case of defhydra+ is when you have many packages that want to add heads to an existing hydra. Some of them may be optional or loaded lazily.

You can now have a base defhydra, and then use defhydra+ to add heads to it when a new package is loaded. Example:

(defhydra hydra-toggle ()
  ("q" nil "quit" :column "Exit")
  ("w" whitespace-mode
       (format "whitespace-mode: %S" whitespace-mode)
       :column "Toggles"))

(use-package org
    :config
  (defhydra+ hydra-toggle ()
    ("l" org-toggle-link-display
         (format "org link display: %S" org-descriptive-links))))

Outro

Big thanks to all contributors, and I hope you enjoy the new release. Happy hacking!

PS. Thanks to everyone who supports me on Liberapay and Patreon!

avy 0.5.0 is out

2019-05-11T00:00:00+02:00

This release consists of 109 commits done over the course of the last 3 years by me and many contributors. Similarly to the 0.4.0 release, the release notes are in Changelog.org. I recommend reading them inside Emacs.

Highlights

A lot of new code is just straight upgrades, you don't need to do anything extra to use them. Below, I'll describe the other part of the new code, which is new commands and custom vars.

New API functions

New functions have been added as drop-in replacements of double-dash (private) Avy functions that were used in other packages and configs. Please replace the references to the obsolete functions.

avy-jump is a drop-in replacement of avy--generic-jump,
avy-process is a drop-in replacement of avy--process.

New dispatch actions

The concept of dispatch actions was introduced in 0.4.0. Suppose you have bound:

(global-set-key (kbd "M-t") 'avy-goto-word-1)

and a word that starts with a "w" and is select-able with "a". Here's what you can do now:

M-t w a to jump there
M-t w x a - avy-action-kill-move: kill the word and move there,
M-t w X a - avy-action-kill-stay: kill the word without moving the point,
M-t w i a - avy-action-ispell: use ispell/flyspell to correct the word,
M-t w y a - avy-action-yank: yank the word at point,
M-t w t a - avy-action-teleport: kill the word and yank it at point,
M-t w z a - avy-action-zap-to-char: kill from point up to selected point.

You can customize avy-dispatch-alist to modify these actions, and also ensure that there's no overlap with your avy-keys, if you customized them.

New `avy-style` setting: 'words

You can now customize:

(setq avy-style 'words)

And you'll see overlays like "by", "if", "is", "it", "my" for 2-letter sequences, and "can", "car", "cog" for 3-letter sequences. You might find them easier to type than "hla", "lls" and "jhl". But you will have to adjust your avy-dispatch-alist, e.g. to use only upper case characters.

`avy-linum-mode`

This is feature is a mix of linum-mode and ace-window-display-mode. You'll see the overlays when you enable this mode, so that there's less context switch when you call avy-goto-line.

Restarting an `avy` search

Suppose you jumped to a word that starts with "a". Now you want to jump to a different word that also starts with "a". You can use avy-resume for this.

Additionally, you can use avy-next and avy-prev to cycle between the last avy candidates. Here's an example hydra to facilitate it:

(defhydra hydra-avy-cycle ()
  ("j" avy-next "next")
  ("k" avy-prev "prev")
  ("q" nil "quit"))

(global-set-key (kbd "C-M-'") 'hydra-avy-cycle/body)

Outro

Big thanks to all contributors, and I hope you enjoy the new release. Happy hacking!

Change the current time in Org-mode

2019-04-11T00:00:00+02:00

Intro

I'm constantly amazed by other people's Org workflows. Now that the weekly tips are a thing, I see more and more cool Org configs, and I'm inspired to get more organized myself.

My own Org usage is simplistic in some areas, and quite advanced in others. While I wrote a lot of code to manipulate Org files ( worf, org-download, orca, org-fu, counsel), the amount of Org files and TODO items that I have isn't huge:

(counsel-git "org$ !log")
;; 174 items

(counsel-rg "\\* DONE|CANCELLED|TODO")
;; 8103 items

Still, that's enough to get out-of-date files: just today I dug up a file with 20 outstanding TODO items that should have been canceled last November!

How to close 20 TODOs using a timestamp in the past

When I cancel an item, pressing tc (mnemonic for TODO-Cancel), Org mode inserts a time stamp with the current time. However, for this file, I wanted to use October 31st 2018 instead of the current time. Org mode already has options like org-use-last-clock-out-time-as-effective-time, org-use-effective-time, and org-extend-today-until that manipulate the current time for timestamps, but they didn't fit my use case.

So I've advised org-current-effective-time:

(defvar-local worf--current-effective-time nil)

(defun worf--current-effective-time (orig-fn)
  (or worf--current-effective-time
      (funcall orig-fn)))

(advice-add 'org-current-effective-time
            :around #'worf--current-effective-time)

(defun worf-change-time ()
  "Set `current-time' in the current buffer for `org-todo'.
Use `keyboard-quit' to unset it."
  (interactive)
  (setq worf--current-effective-time
        (condition-case nil
            (org-read-date t 'totime)
          (quit nil))))

A few things of note here:

worf--current-effective-time is buffer-local, so that it modifies time only for the current buffer
I re-use the awesome org-read-date for a nice visual feedback when inputting the new time
Instead of having a separate function to undo the current-time override, I capture the quit signal that C-g sends.

Outro

The above code is already part of worf and is bound to cT. I even added it to the manual. I hope you find it useful. Happy organizing!

Swiper-isearch - a more isearch-like swiper

2019-04-07T00:00:00+02:00

Intro

Since its introduction in 2015, swiper, while nice most of the time, had two problems:

Slow startup for large buffers.
Candidates were lines, so if you had two or more matches on the same line, the first one was selected.

Over time, workarounds were added to address these problems.

Problem 1: slow startup

Almost right away, calling font-lock-ensure was limited to only small enough buffers.

In 2016, counsel-grep-or-swiper was introduced. It uses an external process (grep) to search through large files.

In 2017, I found ripgrep, which does a better job than grep for searching one file:

(setq counsel-grep-base-command
      "rg -i -M 120 --no-heading --line-number --color never %s %s")

The advantage here is that the search can be performed on very large files. The trade-off is that we have to type in at least 3 characters before we send it to the external process. Otherwise, when the process returns a lot of results, Emacs will lag while receiving all that output.

Problem 2: candidates are lines

In 2015, swiper-avy was added, which could also be used as a workaround for many candidates on a single line. Press C-' to visually select any candidate on screen using avy.

Enter `swiper-isearch`

Finally, less than a week ago, I wrote swiper-isearch to fix #1931.

Differences from the previous commands:

Every candidate is a point position and not a line. The UX of going from one candidate to the next is finally isearch-like, I enjoy it a lot.
Unlike swiper, no line numbers are added to the candidates. This allows it to be as fast as anzu.
Unlike counsel-grep, no external process is used. So you get feedback even after inputting a single char.

I like it a lot so far, enough to make it my default search:

(global-set-key (kbd "C-s") 'swiper-isearch)

Outro

Try out swiper-isearch, see if it can replace swiper for you; counsel-grep-or-swiper still has its place, I think. Happy hacking!

PS. Thanks to everyone who supports me on Liberapay and Patreon!

PPS. Thanks to everyone who contributes issues and patches!

Progress bars for apt in shell

2019-03-24T00:00:00+01:00

Intro

For a couple years now, I use M-x shell as my main shell. Recently, I have fixed one of the minor annoyances that go along with using shell in Emacs. At least since Ubuntu 18.04, the terminal "progress bar" feature, displayed below is non-optional:

It uses terminal escape codes to display the progress bar, and shell-mode can't handle them well, so they clobber a lot of the output.

Initial work around

Previously, I was using this work around, since apt-get doesn't display the progress bar:

# sudo apt upgrade
sudo apt-get upgrade

Progress bar in the mode line

But typing 4 extra chars is hard. And apt-get will likely get these progress bars at some point as well. So I spent around an hour of my weekend hacking an Elisp solution. Here is the code:

(advice-add
 'ansi-color-apply-on-region
 :before 'ora-ansi-color-apply-on-region)

(defun ora-ansi-color-apply-on-region (begin end)
  "Fix progress bars for e.g. apt(8).
Display progress in the mode line instead."
  (let ((end-marker (copy-marker end))
        mb)
    (save-excursion
      (goto-char (copy-marker begin))
      (while (re-search-forward "\0337" end-marker t)
        (setq mb (match-beginning 0))
        (when (re-search-forward "\0338" end-marker t)
          (ora-apt-progress-message
           (substring-no-properties
            (delete-and-extract-region mb (point))
            2 -2)))))))

(defun ora-apt-progress-message (progress)
  (setq mode-line-process
        (if (string-match
             "Progress: \\[ *\\([0-9]+\\)%\\]" progress)
            (list
             (concat ":%s "
                     (match-string 1 progress)
                     "%%%% "))
          '(":%s")))
  (force-mode-line-update))

The solution will detect e.g. "\0337...Progress: [ 25%]...\0338", remove it from the shell buffer and display "25%" in the mode line instead.

Use the Echo Area instead of the mode line

The above is a good enough solution specifically for apt(8), but not for the generic case. Let's try to emulate how e.g. gnome-terminal handles these escape sequences. It takes sequences like "\0337.*\0338" and displays them in the bottom of the window. Kind of like the Emacs Echo Area. That's easy enough to do:

(defun ora-apt-progress-message (progress)
  (message
   (replace-regexp-in-string
    "%" "%%"
    (ansi-color-apply progress))))

Above, we use ansi-color-apply to get rid of any extra terminal escape codes. I decided to stay with the Echo Area version instead of the mode line version. Here's how it looks like:

You can find all of the above code in my config. Happy hacking!

Using exclusion patterns when grepping

2018-03-05T00:00:00+01:00

Git

I like Git. A lot. After years of use it has really grown on me. It's (mostly) fast, (often) reliable, and (always) distributed. For me, all properties are important, but being able to do git init to start a new project in seconds is the best feature.

When it comes to working with Git day-to-day, a nice GUI can really make a difference. In Emacs world, of course it's Magit. Outside of Emacs (brr), git-cola looks to be the most promising one. If you're aware of something better, please share - I'm keeping a list of suggestions for my non-Emacs using colleagues.

Ivy integration for Git

The main two commands in ivy that I use for Git are:

counsel-git: select a file tracked by Git
counsel-rg: grep for a line in all files tracked by Git, using ripgrep as the backend.

There are many alternatives to counsel-rg that use a different backend: counsel-git-grep, counsel-ag, counsel-ack, counsel-pt. But counsel-rg is the fastest, especially when I have to deal with Git repositories that are 2Gb in size (short explanation: it's a Perforce repo with a bunch of binaries, because why not; and I'm using git-p4 to interact with it).

Using `.ignore` with ripgrep

Adding an .ignore file to the root of your project can really speed up your searches. In my sample project, I went from 10k files to less than 500 files.

Example content:

/TAGS
*.min.js*
/Build/Output/
/ThirdParty/

As you can see, both file patterns and directories are supported. One other nifty thing that I discovered only recently is that you can use ripgrep as the backed for counsel-git in addition to counsel-rg. Which means the same .ignore file is used for both commands. Here's the setting:

(setq counsel-git-cmd "rg --files")

And here's my setting for counsel-rg:

(setq counsel-rg-base-command
      "rg -i -M 120 --no-heading --line-number --color never %s .")

The main difference in comparison to the default counsel-rg-base-command is -M 120 which means: truncate all lines that are longer than 120 characters. This is really helpful when Emacs is accepting input from ripgrep: a megabyte long line of minified JS is not only useless since you can't see it whole, but it will also likely hang Emacs for a while.

Outro

I hope you found these bits of info useful. Happy hacking!

Using digits to select company-mode candidates

2017-12-27T00:00:00+01:00

I'd like to share a customization of company-mode that I've been using for a while. I refined it just recently, I'll explain below how.

Basic setting

(setq company-show-numbers t)

Now, numbers are shown next to the candidates, although they don't do anything yet:

Add some bindings

(let ((map company-active-map))
  (mapc
   (lambda (x)
     (define-key map (format "%d" x) 'ora-company-number))
   (number-sequence 0 9))
  (define-key map " " (lambda ()
                        (interactive)
                        (company-abort)
                        (self-insert-command 1)))
  (define-key map (kbd "<return>") nil))

Besides binding 0..9 to complete their corresponding candidate, it also un-binds RET and binds SPC to close the company popup.

Actual code

(defun ora-company-number ()
  "Forward to `company-complete-number'.

Unless the number is potentially part of the candidate.
In that case, insert the number."
  (interactive)
  (let* ((k (this-command-keys))
         (re (concat "^" company-prefix k)))
    (if (cl-find-if (lambda (s) (string-match re s))
                    company-candidates)
        (self-insert-command 1)
      (company-complete-number (string-to-number k)))))

Initially, I would just bind company-complete-number. The problem with that was that if my candidate list was ("var0" "var1" "var2"), then entering 1 means:

select the first candidate (i.e. "var0"), instead of:
insert "1", resulting in "var1", i.e. the second candidate.

My customization will now check company-candidates—the list of possible completions—for the above mentioned conflict. And if it's detected, the key pressed will be inserted instead of being used to select a candidate.

Outro

Looking at git-log, I've been using company-complete-number for at least 3 years now. It's quite useful, and now also more seamless, since I don't have to type e.g. C-q 2 any more. In any case, thanks to the author and the contributors of company-mode. Merry Christmas and happy hacking in the New Year!

Comparison of transaction fees on Patreon and similar services

2017-12-10T00:00:00+01:00

On December 7, Patreon made an announcement about the change in their transaction fee structure. The results as of December 10 speak for themselves:

December 2017 summary: -$29 in pledges, -6 patrons

All leaving patrons marked "I'm not happy with Patreon's features or services." as the reason for leaving, with quotes ranging from:

The billing changes are not great.

to:

Patreon's new fees are unacceptable

In this article, I will explore the currently available methods for supporting sustainable Free Software development and compare their transaction fees.

My experience

My experience taking donations is very short. I announced my fund raising campaign on Patreon in October 2017.

Here's what I collected so far, vs the actual money spent by the contributors:

2017-11-01: $140.42 / $162.50 = 86.41%
2017-12-01: $163.05 / $187.50 = 86.96%

The numbers here are using the old Patreon rules that are going away this month.

Real numbers

method	formula	charged	donated	fee
old Patreon	???	$1.00	$0.86	14%
new Patreon	7.9% + $0.35	$1.38	$0.95	31%
		$2.41	$1.90	21%
		$5.50	$4.75	14%
OpenCollective	12.9% + $0.30	$1.33	$0.90	32%
		$2.36	$1.80	24%
		$5.45	$4.50	18%
Flattr	16.5%	$1.00	$0.84	17%
		$2.00	$1.67	17%
		$5.00	$4.18	17%
Liberapay	0.585%	$1.00	$0.99	1%

On Patreon

Just like everyone else, I'm not happy with the incoming change to the Patreon fees. But even after the change, it's still a better deal than OpenCollective, which is used quite successfully e.g. by CIDER.

Just to restate the numbers in the table, if all backers give $1 (which is the majority currently, and I actually would generally prefer 5 new $1 backers over 1 new $5 backer), with the old system I get $0.86, while with the new system it's $0.69. That's more than 100% increase in transaction fees.

On OpenCollective

It's more expensive than the new Patreon fees in every category or scenario.

On Flattr

Flattr is in the same bucket as Patreon, except with slightly lower fees currently. Their default plan sounds absolutely ridiculous to me: you install a browser plug-in so that a for-profit corporation can track which websites you visit most often in order to distribute the payments you give them among those websites.

If it were a completely local tool which doesn't upload any data on the internet and instead gives you a monthly report to adjust your donations, it would have been a good enough tool. Maybe with some adjustments for mind-share bubbles, which result in prominent projects getting more rewards than they can handle, while small projects fade away into obscurity without getting a chance. But right now it's completely crazy. Still, if you don't install the plug-in, you can probably still use Flattr and it will work similarly to Patreon.

I made an account, just in case, but I wouldn't recommend going to Flattr unless you're already there, or the first impression it made on me is wrong.

On Paypal

Paypal is OK in a way, since a lot of the time the organizations like Patreon are just middle men on top of Paypal. On the other hand, there's no way to set up recurring donations. And it's harder for me to plan decisions regarding my livelihood if I don't know at least approximately the sum I'll be getting next month.

My account, in case you want to make a lump sum donation: paypal.me/aboabo.

On Bitcoin

Bitcoin is similar to Paypal, except it also:

has a very bad impact on the environment,
is a speculative bubble that supports either earning or losing money without actually providing value to the society.

I prefer to stay away from Bitcoin.

Summary

Liberapay sounds almost too good to be true. At the same time, their fees are very realistic, you could almost say optimal, since there are no fees for transfers between members. So you can spend either €20.64 (via card) or €20.12 (via bank wire) to charge €20 into your account and give me €1 per month at no further cost. If you change your mind after one month, you can withdraw your remaining €19 for free if you use a SEPA (Single Euro Payments Area) bank.

If I set out today to set up a service similar to Liberapay, even with my best intentions and the most optimistic expectations, I don't see how a better offer could be made. I recommend anyone who wants to support me to try it out. And, of course, I will report back with real numbers if anything comes out of it.

Thanks to all my patrons for their former and ongoing support. At one point we were at 30% of the monthly goal (25% atm.). This made me very excited and optimistic about the future. Although I'm doing Free Software for almost 5 years now, it's actually 3 years in academia and 2 years in industry. Right now, I'm feeling a burnout looming over the horizon, and I was really hoping to avoid it by spending less time working at for-profit corporations. Any help, either monetary or advice is appreciated. If you're a part of a Software Engineering or a Research collective that makes you feel inspired instead of exhausted in the evening and you have open positions in EU or on remote, have a look at my LinkedIn - maybe we could become colleagues in the future. I'll accept connections from anyone - if you're reading this blog, we probably have a lot in common; and it's always better together.

Ivy 0.10.0 is out

2017-11-30T00:00:00+01:00

Intro

Ivy is a completion method that's similar to Ido, but with emphasis on simplicity and customizability.

Overview

The current release constitutes of 280 commits and 8 months of progress since 0.9.0. Many issues ranging from #952 to #1336 were fixed. The number of people who contributed code as grown to 91; thanks, everyone!

Details on changes

Changelog.org has been a part of the repository since 0.6.0, you can get the details of the current and past changes:

in org-mode
in HTML

Highlights

Many improvements are incremental and don't require any extra code to enable. I'll go over a few selected features that require a bit of information to make a good use of them.

Selectable prompt

Off by default. You can turn it on like so:

(setq ivy-use-selectable-prompt t)

After this, your current input becomes selectable as a candidate. Press C-p when you're on the first candidate to select your input instead.

This solves the long standing issue of e.g. creating a file or a directory foo when a file foobar already exists. Previously, the only solution was to use C-M-j. It's still available, but now you can also select your input with C-p and press RET.

New global actions for ivy

ivy-set-actions was used to enable the following bindings:

Press M-o w to copy the current candidate to the kill ring.
Press M-o i to insert the current candidate into the buffer.

These bindings are valid for any completion session by default.

Use `C-d` in ivy-occur buffers

Here's an example use-case: search your source code for a variable name with e.g. counsel-rg and call ivy-occur (C-c C-o). Suppose you get 10 results, only 4 of which are interesting. You can now delete the uninteresting ones with C-d. Then maybe check off the others with C-d as well as you complete them one by one. A sort of a TODO list.

Similarly, if you want to go over variables to customize, you can call counsel-describe-variable with input ^counsel-[^-] and then check off the ones you have already examined with C-d.

Defcustoms to play with

Here's the list of new defcustom or defvar that might be interesting to review:

counsel-async-filter-update-time
counsel-async-ignore-re
counsel-describe-function-function
counsel-describe-function-preselect
counsel-find-file-ignore-regexp
counsel-fzf-dir-function
counsel-git-grep-skip-counting-lines
counsel-git-log-split-string-re
counsel-url-expansions
ivy-auto-select-single-candidate
ivy-magic-slash-non-match-action
ivy--preferred-re-builders
ivy-truncate-lines

New Commands

14 new commands were added by me and many contributors. Here's the list:

counsel-ack - completion for ack
counsel-apropos - completion for apropos
counsel-file-register - completion for file registers
counsel-fzf - completion for fzf
counsel-git-change-worktree - completion for git-worktree
counsel-git-checkout - completion for git-checkout
counsel-minibuffer-history - generalization of counsel-expression-history and counsel-shell-command-history
counsel-org-capture - completion for org-capture
counsel-org-file - browse all attachments for the current Org file
counsel-org-goto - completion for Org headings
counsel-org-goto-all - completion for Org headings in all open buffers
counsel-switch-to-shell-buffer - switch to a shell buffer, or create one
ivy-occur-delete-candidate - delete current candidate in ivy-occur-mode
ivy-switch-view - select a window configuration, decoupled from ivy-switch-buffer

My personal favorites are counsel-fzf and counsel-org-file.

Outro

Again, thanks to all the contributors. Happy hacking!

P.S. Please consider joining my 74 patrons to give me the opportunity to work on Free Software a lot more. We are currently at 30% of the goal.

Save Ivy file completions to Dired

2017-11-18T00:00:00+01:00

Intro

I think ivy-occur (C-c C-o) is one of the coolest features in ivy. It allows you to save your current search into a new buffer. This has many uses:

get a full overview of all candidates
many useful modal bindings (q, j, k, f) and mouse support
ability to manipulate candidates as text
save the search for later, with the option to refresh the search with g
go over candidates as a TODO list, using C-d to remove elements

Everything above works for any ivy-read session. But the most powerful features come into play when ivy-occur gets customized for a specific collection.

`ivy-occur` for grep-like functions

(ivy-set-occur 'swiper 'swiper-occur)

Thanks to this default customization, the resulting *ivy-occur swiper* buffer is in ivy-occur-grep-mode which inherits from grep-mode. Additionally, you can use ivy-wgrep-change-to-wgrep-mode C-x C-q to edit the result in-place - pressing C-x C-s will save the changes.

Similar customizations are available for counsel-git-grep, counsel-ag, counsel-rg, and counsel-grep.

`ivy-occur` for `ivy-switch-buffer`

(ivy-set-occur 'ivy-switch-buffer 'ivy-switch-buffer-occur)

This makes C-c C-o open your candidates in the powerful ibuffer, which adds additional info to your buffer list and allows you to manipulate buffers easily.

For instance, to delete all matching buffers you can do C-c C-o tD.

The source code is short enough to be included here:

(defun ivy-switch-buffer-occur ()
  "Occur function for `ivy-switch-buffer' using `ibuffer'."
  (ibuffer nil (buffer-name) (list (cons 'name ivy--old-re))))

The interface is quite simple: ivy-occur is responsible for generating a new buffer, and the occur function e.g. ivy-switch-buffer-occur is to fill that buffer with useful info, based on the current search parameters like ivy-text and ivy--old-re.

`ivy-occur` for `counsel-find-file`-like functions

This is a brand new feature that works for counsel-find-file, counsel-git, and counsel-fzf (which itself is quite new, thanks to @jojojames for contributing it).

Since these functions are used to complete file names, we obviously want ivy-occur to open a Dired buffer.

Example 1

To delete all *.elc files in the current folder do:

C-x C-f elc$ C-c C-o tDy.

Example 2

To copy all Org files in a Git project to some directory do:

M-x counsel-git org$ C-c C-o tC.

Example 3

To get a list of videos to watch do:

M-x counsel-fzf mp4$ C-c C-o.

I can further e.g. mark 3 files with m and use r to send these 3 files to vlc as a list. See this post for my dired setup that makes r work this way.

You can remove some files afterwards with the usual D or dx. And to redisplay the buffer use g.

Outro

I hope you like the new feature. I had a really good few hours figuring out how it should work exactly. Please consider joining my 72 patrons to give me the opportunity to work on Free Software a lot more. Happy hacking!

Orca - new package to improve org-capture from browser

2017-10-28T00:00:00+02:00

Intro

Orca is a new Emacs package, an attempt to refactor my old org-fu into something that's much more re-usable and easier to get started with.

Orca functionality

Problem:

When capturing from Firefox using org-protocol (together with this addon):

either I refile each time I capture, which is slow
or my captures pile up in one place, which is messy

Solution:

Define rules for where links from certain websites should be captured.
Allow to capture directly into the current org-mode buffer, since it's likely related to what I'm working with on.

Part 1: Rules example

Here is my example list of configurations:

Capture URL matching https://www.reddit.com/emacs/ to emacs.org:Reddit,
Capture URL matching https://emacs.stackexchange.com/ to emacs.org:Questions,
If nothing else matches, capture to ent.org:Articles.

Corresponding code:

(setq orca-handler-list
      '((orca-handler-match-url
         "https://www.reddit.com/"
         "~/Dropbox/org/wiki/emacs.org" "Reddit")
        (orca-handler-match-url
         "https://emacs.stackexchange.com/"
         "~/Dropbox/org/wiki/emacs.org" "\\* Questions")
        (orca-handler-file
         "~/Dropbox/org/ent.org" "\\* Articles")))

Part 2: Current buffer example

For example, I'm researching how to implement something with docker. This means that I have docker.org open, along with dozens of tabs in the browser.

I can configure to capture into the current org-mode buffer with a * Tasks heading like this:

(push '(orca-handler-current-buffer "\\* Tasks") orca-handler-list)

Since docker.org has * Tasks, I just click the capture button in Firefox and follow up with an immediate C-c C-c in Emacs. The link is already in the right position, no need for an extra refile step.

Using `customize` with orca

You can set up the capture rules using M-x customize-group RET orca RET.

Here's a screenshot:

As you see, the customization is a list of an arbitrary length, with each element falling into one of three categories, each backed by an Elisp function (orca-handler-current-buffer, orca-handler-file, and orca-handler-match-url). Each function takes a different number of arguments (one, two, and three, respectively) - they are all annotated by the interface.

Here's the code that describes the expected :type to customize:

(defcustom orca-handler-list
  ;; ...
  :type '(repeat
          (choice
           (list
            :tag "Current buffer"
            (const orca-handler-current-buffer)
            (string :tag "Heading"))
           (list
            :tag "URL matching regex"
            (const orca-handler-match-url)
            (string :tag "URL")
            (string :tag "File")
            (string :tag "Heading"))
           (list
            :tag "Default"
            (const orca-handler-file)
            (string :tag "File")
            (string :tag "Heading")))))

You can read more about the customization types in this manual section.

Outro

I hope you enjoy orca. I've submitted it to MELPA. Hopefully, it will be available for an easy install very soon.

Org-mode is a beautiful thing, but my previous attempts to configure it were huge config files of loosely related (i.e. the only thing in common was Org-mode) stuff spanning hundreds of lines. Orca is an improvement in this respect, since it focuses on a very narrow domain. It still tries to be flexible (just like org-capture) - you can plug in your own functions into orca-handler-list. But initially, the flexibility can be constrained into the customize-group interface, to allow for a self-documenting solution that's easy to get started with. Happy hacking!

PS. Thanks to all my patrons for advancing my Patreon campaign! As of this writing, we're almost at the 25% mark with 61 contributors.

Please consider supporting me on Patreon

2017-10-18T00:00:00+02:00

In light of the recent success of the Magit Kickstarter (congratulations to @tarsius, by the way), I got a lot more optimistic about Free Software crowdfunding.

So I opened a Patreon account where you can support my work: https://www.patreon.com/abo_abo. The goal I set there is both optimistic and (hopefully) realistic: I'd like to hack on Free Software 1 day per week indefinitely, reducing my real world job days to 4 per week.

Ideally, I'd like to work on Free Software full time (one can dream), but it doesn't look like that level of donations is attainable right now. But I think I could accomplish a lot working a full day per week:

improve the level of maintenance of my current projects
polish and release a few projects I have in a semi-complete unreleased state
produce more content on my YouTube channel
maybe start working on an Emacs book

Here's a list of popular repositories I've made over the last 5 years in my free time (all Free Software under GPL):

If you are a user of my work, don't feel any pressure to donate. We are all here voluntarily: I publish because I enjoy it, you use the software because you find it useful. But out there is the real world, and, although I like my real world job enough, I can't say that would I do it voluntarily if I had enough money to meet my needs.

If you do what you love, you'll never work a day in your life

I'd like to do what I love, and I wish you all the same. Happy hacking!

Extending completion-at-point for Org-mode

2017-10-04T00:00:00+02:00

Intro

When creating documents, context aware completion is a powerful mechanism that can help you improve the speed, correctness and discoverability.

Emacs provides context aware completion via the complete-symbol command, bound to C-M-i by default. In order for it to do something useful, completion-at-point-functions has to be set up.

Documentation:

Special hook to find the completion table for the thing at point.
Each function on this hook is called in turn without any argument and should
return either nil to mean that it is not applicable at point,
or a list of the form (START END COLLECTION) where
START and END delimit the entity to complete and should include
point, COLLECTION is the completion table to use to complete it.

For each major-mode, a different value of completion-at-point-functions can (and probably should) apply. One of the modes that's set up nicely by default is emacs-lisp-mode: press C-M-i to get completion for Elisp variable and function names. Org-mode, on the other hand, is quite lacking in this regard: nothing useful happens with C-M-i.

Here's my current setting for Org-mode:

(setq completion-at-point-functions
      '(org-completion-symbols
        ora-cap-filesystem
        org-completion-refs))

org-completion-symbols

When I write about code in Org-mode, I quote items like this:

=/home/oleh/=, =HammerFactoryFactory=, etc.

Quoting has several advantages:

It looks nice, since it's in a different face,
flyspell doesn't need to check it, which makes sense since it would fail on most variable and class names,
Prevents Org from confusing directory names for italics mark up.

Completion has one more advantage on top of that: if I refer to a symbol name multiple times within a document, completion helps me to enter it quickly and correctly. Here's the corresponding completion source:

(defun org-completion-symbols ()
  (when (looking-back "=[a-zA-Z]+")
    (let (cands)
      (save-match-data
        (save-excursion
          (goto-char (point-min))
          (while (re-search-forward "=\\([a-zA-Z]+\\)=" nil t)
            (cl-pushnew
             (match-string-no-properties 0) cands :test 'equal))
          cands))
      (when cands
        (list (match-beginning 0) (match-end 0) cands)))))

First of all, it checks if the point is e.g. after =A, i.e. we are in fact entering a new quoted symbol. If that's not the case, return nil and let the other completion sources have a go.
Next, it looks through the current buffer for each =foo= and =bar=, accumulating them into a list.
Finally, it returns the bounds of what we've got so far, plus the found candidates. It's important that the bounds are passed to the completion engine, so that it can delete everything inside the bounds before inserting the whole selected symbol.

org-cap-filesystem

This source is for completing file names:

(defun ora-cap-filesystem ()
  (let (path)
    (when (setq path (ffap-string-at-point))
      (when (string-match "\\`file:\\(.*\\)\\'" path)
        (setq path (match-string 1 path)))
      (let ((compl (all-completions path #'read-file-name-internal)))
        (when compl
          (let* ((str (car compl))
                 (offset
                  (let ((i 0)
                        (len (length str)))
                    (while (and (< i len)
                                (equal (get-text-property i 'face str)
                                       'completions-common-part))
                      (cl-incf i))
                    i)))
            (list (- (point) offset) (point) compl)))))))

I usually enter ~, so that ffap-string-at-point recognizes it as a path. Then complete each part of the path with C-M-i. It's very similar to counsel-find-file. In fact, I could just use counsel-find-file for this, with M-o i to insert the file name instead of opening the selected file.

org-completion-refs

org-completion-refs is very similar to org-completion-symbols: it will collect all instances of e.g. \label{foo}, and offer them for completion when you enter \ref{. If you want to look at the code, it's available in my config.

Outro

I hope I convinced you about the usefulness of completion at point. It's especially cool since it's a universal interface for major-mode-specific completion. So any IDE-like package for any language could provide its own completion using the familiar interface. That could go a long way towards providing a "just works" experience, particularly when dealing with a new language.

Ripgrep

2017-08-04T00:00:00+02:00

counsel-rg

Lately, due to working with a large code base, I've grown more and more fond of counsel-rg. It's an Elisp wrapper around ripgrep - a relatively new recursive grep tool that aims to be faster than the competition (ag, git grep, pt, ack etc).

Besides being really fast, rg also has some really nice command switches. One such switch is especially useful for Emacs:

-M, --max-columns NUM : Don't print lines longer than this limit in bytes. Longer lines are omitted, and only the number of matches in that line is printed.

The -M switch is useful twofold:

Emacs is slow when dealing with long lines (by long I mean thousands of chars per line)
Emacs is slow at accepting a huge amount of output from a process

For each character you add to your input, counsel-rg starts a new shell command to recalculate the matches with the new input. This means that in order to avoid keyboard lag there's only about 0.1 seconds available for both:

Running the shell command.
Accepting output from the shell command.

So I'm quite happy that rg speeds up both steps. Less time spent on these steps provides for much smoother searching.

counsel-grep-or-swiper

I also work with large log files, one file at a time. For a long time, I've used counsel-grep-or-swiper as my main search command:

(global-set-key (kbd "C-s") 'counsel-grep-or-swiper)

But for a 40Mb log file with really long lines counsel-grep-or-swiper started to lag a bit. I tried counsel-rg, and it was actually faster than grep, although it was searching the whole directory. So I thought, why not use rg instead of grep? The switch is actually really easy and required only a simple user customization:

(setq counsel-grep-base-command
 "rg -i -M 120 --no-heading --line-number --color never '%s' %s")

Outro

If you haven't tried ripgrep so far, I suggest you give it a go. Happy hacking!

And if you're a C hacker and have some free time on your hands, why not look at the long lines and the process output issues in Emacs? I'd be very grateful:)

hydra.el talk @ london.el

2017-07-24T00:00:00+02:00

Today I gave a talk on hydra at the London Emacs meet up - london.el. My screen capture is available on youtube, and the slides are here.

Thanks to @dotemacs for organizing the event and inviting me.

Ivy 0.9.0 is out

2017-04-09T00:00:00+02:00

Intro

Ivy is a completion method that's similar to Ido, but with emphasis on simplicity and customizability.

Overview

The current release constitutes of 339 commits and almost a full year of progress since 0.8.0. Many issues ranging from #493 to #946 were fixed. The number of people who contributed code as grown to 63; thanks, everyone!

Details on changes

Changelog.org has been a part of the repository since 0.6.0, you can get the details of the current and past changes:

in org-mode
in HTML

Highlights

Many improvements are incremental and don't require any extra code to enable. I'll go over a few selected features that require a bit of information to make a good use of them.

A better action choice interface

For all ivy completions, pressing M-o allows to execute one of the custom actions for the current command. Now you have an option to use hydra for selecting an action. Use this code to turn on the feature:

(require 'ivy-hydra)

One big advantage of the new interface is that you can peak at the action list with M-o without dismissing the candidate list. Press M-o again to go back to candidate selection without selecting an action.

Here's some code from my config that ensures that I always have some extra actions to choose from:

(defun ora-insert (x)
  (insert
   (if (stringp x)
       x
     (car x))))

(defun ora-kill-new (x)
  (kill-new
   (if (stringp x)
       x
     (car x))))

(ivy-set-actions
 t
 '(("i" ora-insert "insert")
   ("w" ora-kill-new "copy")))

Grepping

The new counsel-rg joins the group of grepping commands in counsel (counsel-ag, counsel-git-grep, counsel-grep, counsel-pt). It wraps around the newly popular and very fast ripgrep shell tool.

A nice improvement to the grepping commands is the ability to specify extra flags when you press C-u (universal-argument) before the command. See this gif for an example of excluding *.el from the files searched by ag.

counsel-find-file

Press M-o b to change the current directory to one of the virtual buffers' directories. You continue to select a file from that directory.
Press M-o r to find the current file as root.

counsel-git-log

You can now customize counsel-git-log-cmd. See #652 for using this to make counsel-git-log work on Windows.

counsel-mode

counsel-info-lookup-symbol now substitutes the built in info-lookup-symbol.
Pressing C-r while in the minibuffer of eval-expression or shell-command now gives you completion of your previous history.

counsel-yank-pop

Use the new counsel-yank-pop-separator variable to make counsel-yank-pop look like this.

ivy

There was breaking change for alist type collections some months ago. Right now the action functions receive an item from the collection, instead of (cdr item) like before. If anything breaks, the easy fix is to add an extra cdr to the action function.

Unique index for alist completion was added. The uniqueness assumption is that the completion system is passed a list of unique strings, of which one (or more) are selected. Unlike plain string completion, alists may require violating the uniqueness assumption: there may be two elements with the same car but different cdr. Example: C function declaration and definition for tag completion. Until now, whenever two equal strings were sent to ivy-read, only the first one could be selected. Now, each alist car gets an integer index assigned to it as a text property 'idx. So it's possible to differentiate two alist items with the same key.

Action functions don't require using with-ivy-window anymore. This allows for a lot of simplification, e.g. use insert instead of (lambda (x) (with-ivy-window (insert x))).

ivy-switch-buffer

You can now customize faces in ivy-switch-buffer by the mode of each buffer. Here's a snippet from my config:

(setq ivy-switch-buffer-faces-alist
      '((emacs-lisp-mode . swiper-match-face-1)
        (dired-mode . ivy-subdir)
        (org-mode . org-level-4)))

Looks neat, I think:

swiper

Customize swiper-include-line-number-in-search if you'd like to match line numbers while using swiper.

New Commands

counsel-bookmark

Offers completion for bookmark-jump. Press M-o d to delete a bookmark and M-o e to edit it.

A custom option counsel-bookmark-avoid-dired, which is off by default, allows to continue completion for bookmarked directories. Turn it on with:

(setq counsel-bookmark-avoid-dired t)

and when you choose a bookmarked directory, the choice will be forwarded to counsel-find-file instead of opening a dired-mode buffer.

counsel-colors-emacs and counsel-colors-web

Completion for colors by name:

the default action inserts the color name.
M-o h inserts the color hex name.
M-o N copies the color name to the kill ring.
M-o H copies the color hex name to the kill ring.

The colors are displayed in the minibuffer, it looks really cool:

You also get 108 shades of grey to choose from, for some reason.

counsel-faces

Completion for faces by name:

counsel-command-history

Shows the history of the Emacs commands executed and lets you select and eval one again. See #826 for a nice screenshot.

counsel-company

Picks up company's candidates and inserts the result into the buffer.

counsel-dired-jump and counsel-file-jump

Jump to a directory or a file in the current directory.

counsel-dpkg and counsel-rpm

Wrap around the popular system package managers.

counsel-package

Install or uninstall Emacs packages with completion.

counsel-mark-ring

Navigate the current buffer's mark ring.

counsel-semantic

Navigate the current buffer's tags.

counsel-outline

Navigate the current buffer's outlines.

counsel-recentf

Completion for recentf.

counsel-find-library

Completion for find-library.

counsel-hydra-heads

Completion for the last hydra's heads.

counsel-org-agenda-headlines

Completion for headlines of files in your org-agenda-files.

Outro

Again, thanks to all the contributors. Happy hacking!

Using Emacs as a C++ IDE

2017-03-28T00:00:00+02:00

Recently, I've had to code some C++ at work. And I saw it as a good opportunity to step up my Emacs' IDE game. I've eschewed clang-based tools until now, but GCC isn't adding AST support any time soon, and CEDET is too slow and too clumsy with macros for the particular project that I had. Here's the line in Eigen that broke the camel's back. Basically it's 30 lines of macros that expand to 30 lines of typedefs. Maybe it's a valid implementation choice, I'd rather avoid the macros altogether, but in any case I couldn't get CEDET to parse that.

The first thing I tried was rtags. My project was CMake-based, so I just put this line in my subdirectory Makefile:

cmake:
    cd ../build && cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ..

The -DCMAKE_EXPORT_COMPILE_COMMANDS=1 causes a compile_commands.json file to be emitted during the actual compilation. This file describes the compile flags for every source file. These flags are essential in helping the parser understand what's going on.

Then, in the build directory I start:

rdm & rc -J .

Finally, rtags-find-symbol-at-point should work now. I still like to use CEDET as backup, it's pretty good at tracking variables defined in the current function:

(defun ciao-goto-symbol ()
  (interactive)
  (deactivate-mark)
  (ring-insert find-tag-marker-ring (point-marker))
  (or (and (require 'rtags nil t)
           (rtags-find-symbol-at-point))
      (and (require 'semantic/ia)
           (condition-case nil
               (semantic-ia-fast-jump (point))
             (error nil)))))
(define-key c++-mode-map (kbd "M-.") 'ciao-goto-symbol)
(define-key c++-mode-map (kbd "M-,") 'pop-tag-mark)

For my other C++ projects which aren't CMake-based, I use the excellent bear tool to emit the compile_commands.json file. It's as easy as:

make clean
bear make

Use Irony for completion

It didn't take long to figure out that rtags isn't great at completion. I almost accepted that's just the way it is. But this morning I decided to make some changes and try irony-mode. And it worked beautifully for completion! What's ironic, is that irony-mode doesn't have goto-symbol, so the time spent to figure out rtags was worth it.

Here's my Irony setup; I only changed the C-M-i binding to the newly written counsel-irony, now available in the counsel package on MELPA:

(add-hook 'c++-mode-hook 'irony-mode)
(add-hook 'c-mode-hook 'irony-mode)

(defun my-irony-mode-hook ()
  (define-key irony-mode-map
      [remap completion-at-point] 'counsel-irony)
  (define-key irony-mode-map
      [remap complete-symbol] 'counsel-irony))
(add-hook 'irony-mode-hook 'my-irony-mode-hook)
(add-hook 'irony-mode-hook 'irony-cdb-autosetup-compile-options)

And here are some screenshots of counsel-irony:

First of all, the completion is displayed inline, similarly to modern IDEs. You can use all of Ivy's regex tricks to complete your candidate:

Note how the power of regex matching allows me to narrow the initial 1622 candidates to only 22 functions that have src1 and src2 as arguments. One of the candidates is cut off for being longer than the window width. You can still match against the invisible text, but you won't see it. It's possible to use C-c C-o (ivy-occur) to store the current candidates into a buffer:

Clicking the mouse on any of the lines in the new buffer will insert the appropriate symbol into the C++ buffer.

Outro

I'd like to thank the authors of rtags and irony-mode for these nice packages. Hopefully, counsel-irony is a nice addition. Happy hacking!

Quickly ediff files from dired

2017-03-18T00:00:00+01:00

ediff.el --- a comprehensive visual interface to diff & patch

I wrote about ediff years ago. Today, I'll just reference a useful ediff snippet from my config that I've added some time ago and refined only recently.

The premise is quite simple: press e in dired-mode to immediately ediff two marked files, no questions asked:

(define-key dired-mode-map "e" 'ora-ediff-files)

And here's the code, with a few bells and whistles:

;; -*- lexical-binding: t -*-
(defun ora-ediff-files ()
  (interactive)
  (let ((files (dired-get-marked-files))
        (wnd (current-window-configuration)))
    (if (<= (length files) 2)
        (let ((file1 (car files))
              (file2 (if (cdr files)
                         (cadr files)
                       (read-file-name
                        "file: "
                        (dired-dwim-target-directory)))))
          (if (file-newer-than-file-p file1 file2)
              (ediff-files file2 file1)
            (ediff-files file1 file2))
          (add-hook 'ediff-after-quit-hook-internal
                    (lambda ()
                      (setq ediff-after-quit-hook-internal nil)
                      (set-window-configuration wnd))))
      (error "no more than 2 files should be marked"))))

Some notes on how the extra code adds convenience:

In case no files are marked, the file at point is used as the first file, and read-file-name is used for the second file. Since I have the magic (setq dired-dwim-target t) in my config, in case a second dired buffer is open, dired-dwim-target-directory will offer it as the starting directory during completion. Very useful to compare two files in two different directories.
Depending on the order of the arguments to ediff-files, the changes will appear either as added or removed; file-newer-than-file-p tries to put the arguments in a logical order by looking at the files' last change times.
ediff-after-quit-hook-internal is used to restore the previous window configuration after I quit ediff with q.

That's about it. Hopefully, it's useful. Happy hacking.

Make it so. file1 -> Makefile -> file2

2017-02-25T00:00:00+01:00

Intro

make-it-so is an old package of mine that I haven't yet highlighted on the blog. This package helps you manage a collection of makefiles that are used to generate new files from existing files using shell commands.

You can think of these makefiles as a directory of shell functions, arranged by the extension of the files that they operate on:

$ cd make-it-so && find recipes -name Makefile
recipes/ipynb/to-md/Makefile
recipes/ogv/crop/Makefile
recipes/ogv/trim/Makefile
recipes/ogv/to-gif/Makefile
recipes/pdf/to-txt/Makefile
recipes/md/to-org/Makefile
recipes/md/to-html/Makefile
recipes/cue/split/Makefile
recipes/dot/to-png/Makefile
recipes/m4a/to-mp3/Makefile
recipes/flac/to-mp3/Makefile
recipes/gif/gifsicle/Makefile
recipes/svg/to-png/Makefile
recipes/chm/to-pdf/Makefile
recipes/txt/encode-utf8/Makefile
recipes/mp4/to-mp3/Makefile
recipes/mp4/trim/Makefile
recipes/mp4/replace-audio/Makefile
recipes/png/to-gif/Makefile

When you call make-it-so on a particular file, you get completion for the recipes that are available for that file extension, along with an option to create a new recipe.

Example 1: convert `pdf` to `txt`

Suppose you want to convert a PDF file test.pdf to a text file test.txt.

In case the recipe is in your collection, you don't have to remember the command or the command switches to do it anymore:

Navigate to test.pdf in dired and press , (bound to make-it-so).
Select the recipe you want using completion: to-txt is already provided.
Your file and the makefile recipe are moved to the staging area:
```
./to-txt_test.pdf/test.pdf
./to-txt_test.pdf/Makefile
```
The makefile is opened in a new buffer with the following bindings:
- f5 (mis-save-and-compile) will run compile, creating test.txt in the current directory.
- C-, (mis-finalize) will finalize the operation, moving test.pdf and test.txt to the parent directory (where test.pdf was before), and deleting the staging directory.
- C-M-, (mis-abort) will move test.pdf back to its initial location and delete all generated files. This command is effectively an undo for make-it-so.

It takes a large chunk of text to describe everything, but the key sequence for doing all this is quite short:

, - make-it-so.
RET - select to-txt.
f5 - create test.txt.
C-, - finalize.

Example 2: make a gif from a series of png images

I'll describe the process of creating a high quality gif like this one, which describes the effect of the C key in lispy:

First, I use kazam to take two png screenshots of my Emacs screen:

$ ls -1 *.png
Screenshot 2017-02-25 16:14:49.png
Screenshot 2017-02-25 16:15:10.png

I plan to use gifsicle to sequence the still images into a gif. But it only takes gif as the input format, so first I have to convert my png files to non-animated gif files.

I open the dired buffer where they are located and mark them with m (dired-mark). Then call make-it-so with , and select to-gif recipe. This recipe has no parameters, so there's nothing else to do but f5 C-,. Two new files are created:

$ ls -1 *.png *.gif
Screenshot_2017-02-25 16:14:49.gif
Screenshot_2017-02-25 16:14:49.png
Screenshot_2017-02-25 16:15:10.gif
Screenshot_2017-02-25 16:15:10.png

Note that the file names (the defaults of kazam) are problematic when used with makefiles, since they contain spaces and colons. The Elisp layer of make-it-so takes care of that. It renames the files back and forth so that the logic in the makefiles remains simple.

Next, I mark the two gif files using *% (dired-mark-files-regexp), press , once more and select the gifsicle recipe. I'm presented a makefile with the following contents:

# ——— parameters —————————————————————————————————

# delay between frames in hundredths of a second
delay = 60

# ——— implementation —————————————————————————————
DIRGIF = $(shell ls *.gif | grep -v anime.gif)

all: anime.gif

anime.gif: Makefile $(DIRGIF)
    rm -f anime.gif
    gifsicle --delay=$(delay) --colors=256 --loop $(DIRGIF) > $@
    echo $@ >> provide

clean:
    rm -f anime.gif provide

install-tools:
    sudo apt-get install gifsicle

.PHONY: all install-tools clean

The most commonly useful parameter, the delay between frames, is nicely documented at the top. I don't have to remember that the switch name is --delay or that the switch style --delay=60 is used. I simply change the number above until I get the result that I want.

Example 3: add a new recipe

As a sample scenario, assume you want to convert *.svg to *.png.

Step 1

An internet search leads to Stack Overflow and this command:

inkscape -z -e test.png -w 1024 -h 1024 test.svg

Navigate to the file(s) in dired and call make-it-so with ,. No default actions are available, so just type "to-png" and hit RET. The "to-" prefix signifies that this is a conversion, adapting the Makefile to this form:

# This is a template for the Makefile.
# Parameters should go in the upper half as:
#     width = 200
# and be referenced in the command as $(width)

# ____________________________________________

DIRSVG = $(shell dir *.svg)

DIRPNG = $(DIRSVG:.svg=.png)

all: clean Makefile $(DIRPNG)

%.png: %.svg
    echo "add command here"
    echo $@ >> provide

clean:
    rm -f *.png provide

# Insert the install command here.
# e.g. sudo apt-get install ffmpeg
install-tools:
    echo "No tools required"

.PHONY: all install-tools clean

If the action name doesn't have a "to-" prefix, the transformation is assumed to be e.g. "svg" -> "out.svg". You can change this of course by editing the Makefile.

Step 2

In case the command needs additional packages in order to work you might want to change echo "No tools required" to the appropriate package install instruction, e.g. sudo apt-get install inkscape.

When you're on a new system, this will serve as a reminder of what you should install in order for the Makefile to work. Simply call:

make install-tools

Step 3

Replace echo "add command here" with:

    inkscape -z -e $@ -w $(width) -h $(height) $^

The parameters width and height will go to the top of the Makefile, where they can be customized.
$@ refers to the output file, test.png in this case.
$^ refers to the input file, test.svg in this case.

That's it. You can see the final Makefile here. Test if the command works with f5 from the Makefile. If you're happy with it, call mis-finalize with C-, from dired. The Makefile will be saved for all future calls to make-it-so.

Outro

To summarize the advantages of make-it-so:

Write the recipe one time, never have to look up how to do the same thing a few months from now.
A chance to write the recipe zero times, if someone in the community has already done it and shared the recipe with you.
The Elisp layer takes care of hairy file names.
Parallel commands on multiple files, i.e. make -j8, are provided for free.

The most important usage tip: until you're sure that the command and the Makefile work properly make backups. In fact, make backups period. Happy hacking!

elf-mode - view the symbol list in a binary

2016-08-28T00:00:00+02:00

Recently, I've been looking at libigl. I didn't manage to fully figure out their CMake build system for tutorials: although each tutorial has a CMakeLists.txt, it's only possible to build them all at once.

So I decided to replace CMakeLists.txt with a good-old Makefile; how hard can it be? Concerning includes, not at all hard: the missing files are found with counsel-locate and added to the include path.

But I had some trouble matching a missing ld dependency to a library file. Fixed it with a bunch of googling and guesswork; I still wonder if there's a better way. But in the process, I've found this useful command:

readelf --syms libGL.so

which produces e.g.:


Symbol table '.dynsym' contains 2732 entries:
   Num:    Value          Size Type    Bind   Vis      Ndx Name
     0: 0000000000000000     0 NOTYPE  LOCAL  DEFAULT  UND
     1: 000000000004faf0     0 SECTION LOCAL  DEFAULT    8
     2: 00000000000e8f20     0 FUNC    GLOBAL DEFAULT   11 glGetIntegerui64i_vNV
     3: 00000000000e13e0     0 FUNC    GLOBAL DEFAULT   11 glGetMultiTexEnvfvEXT
     4: 00000000000d7440     0 FUNC    GLOBAL DEFAULT   11 glProgramUniform2uiv
     5: 00000000000cfdc0     0 FUNC    GLOBAL DEFAULT   11 glMultiTexCoord3sv

This is a pretty good representation of a binary file: in this example, instead of one megabyte of gibberish I see a bit more than 2732 lines describing the functions this file uses and provides.

Viewing the symbol list automatically

I liked the above representation so much that I want to see it by default. In Emacs, it's pretty easy to do with auto-mode-alist:

(add-to-list 'auto-mode-alist '("\\.\\(?:a\\|so\\)\\'" . elf-mode))

The above code instructs Emacs to call elf-mode function whenever the file name ends in *.a or *.so.

And here's the body of elf-mode:

(defvar-local elf-mode nil)

;;;###autoload
(defun elf-mode ()
  (interactive)
  (let ((inhibit-read-only t))
    (if elf-mode
        (progn
          (delete-region (point-min) (point-max))
          (insert-file-contents (buffer-file-name))
          (setq elf-mode nil))
      (setq elf-mode t)
      (delete-region (point-min) (point-max))
      (insert (shell-command-to-string
               (format "readelf --syms %s" (buffer-file-name)))))
    (set-buffer-modified-p nil)
    (read-only-mode 1)))

The idea is very simple: elf-mode is a toggle function that replaces the buffer contents with the shell command output. It carefully uses read-only-mode and set-buffer-modified-p so that the file will not be overwritten by accident with the symbol names.

Using autoload to avoid overhead

As you might imagine, looking at binaries isn't really a common task. Is it worth to be dragging this code around from now on, loading it on each start? The answer is yes, of course. Since the actual cost is negligible until the feature is used.

If you look above, elf-mode has an ;;;###autoload cookie before it. The cookie results in this line in my loaddefs.el:

(autoload 'elf-mode "modes/ora-elf" "" t nil)

My init.el always loads loaddefs.el, but never loads ora-elf.el where the function is defined. That file is only loaded when the function elf-mode is called for the first time. The above autoload statement simply instructs Emacs to load a particular file when elf-mode needs to be called.

When you use the package manager, the autoloads file is generated and loaded for you automatically:

$ tree elpa/ace-link-20160811.112/

elpa/ace-link-20160811.112/
├── ace-link-autoloads.el
├── ace-link.el
├── ace-link.elc
└── ace-link-pkg.el

0 directories, 4 files

Here, the package manager will always load ace-link-autoloads.el, which instructs Emacs to load ace-link.el when one of the ;;;###autoload functions is called and ace-link.el isn't yet loaded.

As an example of how useful delayed loading is: my 6000 line config starts in 1.8 seconds. About 40% of that time is spent on (package-initialize), which I assume is the package manager loading all those *-autoloads.el files that I have in my elpa/.

Outro

Let me know if there's interest to have elf-mode on MELPA. Also, if anyone knows how to set mode automatically based on the first few chars of the file (all binaries seem to start with ^?ELF), I'd like to know that as well. Happy hacking!

Swipe all the files!

2016-07-29T00:00:00+02:00

If you've ever tried the swiper-all from swiper, forget everything about it. The command was super-awkward, since it had to parse all your open files before giving you a chance enter anything, resulting in dozens of seconds before the prompt.

Recently, I've had some time to examine and improve it and the result looks very promising. The new command is now async, which means there's no delay before the prompt comes up. Here's a result I got with no delay while having around 50 buffers open:

The shortcut I'm using:

(global-set-key (kbd "C-c u") 'swiper-all)

For efficiency's sake a small trade off had to be made: the line numbers are no longer displayed. This actually results in an advantage that you can select different candidates on the same line.

There are still a few things I plan to try for the new command, like adding file-less buffers, caching for incremental regexes and maybe even newlines in wild cards, but even now it seems very usable. So give it a try, enjoy and happy hacking!

Bookmark the current window layout with Ivy

2016-06-27T00:00:00+02:00

Today's post is about the newest feature related to the ivy-switch-buffer command. If you use ivy-mode, you're probably already using ivy-switch-buffer since it overwrites the built-in switch-to-buffer.

The cool thing about ivy-switch-buffer is that it's not only buffers that are offered for completion. Other buffer-like entities can be there as well: bookmarks, recently opened files (recentf), and finally, window layouts. Since all of those are relatively the same concept, it's very convenient to have them all in one place available for completion.

Here are the relevant settings:

;; Enable bookmarks and recentf
(setq ivy-use-virtual-buffers t)

;; Example setting for ivy-views
(setq ivy-views
      `(("dutch + notes {}"
         (vert
          (file "dutch.org")
          (buffer "notes")))
        ("ivy.el {}"
         (horz
          (file ,(find-library-name "ivy"))
          (buffer "*scratch*")))))

I did mention ivy-views before in the ivy-0.8.0 release post. But now, instead of setting ivy-views by hand, you can also bind ivy-push-view to a key and store as many window configurations as you like, really fast.

What gets stored:

The window list - all windows open on the current frame.
The window splits relative to each other as a tree. Currently, the size of the split isn't saved, all windows are split equally.
The point positions in each window. If you use just one window, you've got something similar to bookmark-set.

Recommended key bindings

Here's what I use currently:

(global-set-key (kbd "C-c v") 'ivy-push-view)
(global-set-key (kbd "C-c V") 'ivy-pop-view)

Typical workflow

Suppose I have two files open: the file 2016-06-23-ivy-push-view.md and the _posts directory. By pressing C-c v I am prompted for a view name with the default being e.g. {} 2016-06-23-ivy-push-view.md _posts 2.

I can still name the view however I want, but I typically just press RET. The parts of the automatic view name are:

{} - this is a simple string marker to distinguish the views in the buffer view. If I enter only {} into ivy-switch-buffer prompt, the candidates will normally filter to only views, since very rarely will a file or a buffer name match {}.
2016-06-23-ivy-push-view.md _posts is the list of buffers stored in the view. This view has only two buffers, but ivy-push-view can handle as many windows as you can cram into a single frame.
2 means that I already have two views with the same buffers, each new view with the same buffers gets an increased number for the suggested name. And it's not useless to have many views for the same buffers, since the views also store point positions, not just the window list.

Here's the beauty of it for me: when I type _posts into ivy-switch-buffer I can chose to open the _posts directory in a variety of ways:

If the buffer is currently open, I can just switch there.
If the buffer is currently closed, I can re-open it, thanks to recentf.
I can open the buffer as part of a stored view(s) in ivy-views.

Finally, if I decide that I don't need a particular view any more, I can delete it with C-c V (ivy-pop-view). It's possible to delete many views at once by pressing C-M-m (ivy-call), as usual with most ivy completion functions.

Breaking API change

While implementing ivy-set-view I decided that the current way alist collections are handled together with actions is sub-optimal. Here's the new way of working:

(let (res)
  (ivy-with
   '(ivy-read "test: "
     '(("one" . 1) ("three" . 3))
     :action (lambda (x) (setq res x)))
   "t C-m")
  res)
;; =>
;; ("three" . 3)

Previously, the return result would be 3, i.e. the cdr of the selected candidate. Any code using ivy-read with an alist-type collection will break. I fixed all instances in counsel.el, and there actually aren't too many uses in the published third party packages.

A simple fix to the problem is to use cdr in the action function. Additionally, having more information available in the action function will serve to improve the code.

Set an Emacs variable with double completion

2016-06-06T00:00:00+02:00

I'd like to show off a certain Elisp productivity booster that I've had in an unfinished state for a while and finished just today.

A large part of tweaking Elisp is simply setting variables. The new command, counsel-set-variable, allows to set them quite a bit faster.

Completion stage 1:

First of all, you get completion for all variables that you have defined:

Completion stage 2:

Once a symbol is selected, the code checks whether the symbol is a defcustom with type 'boolean or 'radio. Since then it is possible to offer all values that the symbol is allowed to become for completion.

For example, here's a typical 'radio-type definition:

(defcustom avy-style 'at-full
  "The default method of displaying the overlays.
Use `avy-styles-alist' to customize this per-command."
  :type '(choice
          (const :tag "Pre" pre)
          (const :tag "At" at)
          (const :tag "At Full" at-full)
          (const :tag "Post" post)
          (const :tag "De Bruijn" de-bruijn)))

And here's a completion screen offered for this variable:

It is worth noting that the current value of the variable is pre-selected, to give a nice reference point for the new setting.

In case the symbol isn't a boolean or a radio

Then you get a completion session similar to M-x read-expression, but with the initial contents already filled in. For example:

The read-expression part combines well with this setting in my config:

(defun conditionally-enable-lispy ()
  (when (eq this-command 'eval-expression)
    (lispy-mode 1)))

(add-hook
 'minibuffer-setup-hook
 'conditionally-enable-lispy)

Here's a series of commands using lispy-mode that I would typically use for the screenshot above, to set ivy-re-builders-alist to a new value:

C-f (forward-char) to get into special.
-e (lispy-ace-subword) to mark the plus part of the code.
C-d (lispy-delete) to delete the active region.

After the C-f -e C-d chain of bindings, the minibuffer contents become:

(setq ivy-re-builders-alist '((t . ivy--regex-|)))

I press C-M-i (completion-at-point) to get completion for all symbols that start with ivy--regex-. Since I have ivy-mode on, C-M-i starts a recursive completion session. I highly recommend adding these settings to your config:

;; Allow to read from minibuffer while in minibuffer.
(setq enable-recursive-minibuffers t)

;; Show the minibuffer depth (when larger than 1)
(minibuffer-depth-indicate-mode 1)

Finally, I would e.g. select e.g. ivy--regex-fuzzy and RET RET to finalize the eval. The first RET exits from completion-at-point and the second RET exits from counsel-set-variable.

Outro

I think this command, especially the newly added read-expression part, is quite a bit faster than what I did before. That is switching to *scratch* and typing in the setq manually and evaluating with C-j. Here's my binding for the new command:

(global-set-key (kbd "<f2> j") 'counsel-set-variable)

It's not very mnemonic, but it's really fast. Just a suggestion, in case you don't know where to bind it. Happy hacking!

Ivy 0.8.0 is out

2016-04-26T00:00:00+02:00

Intro

Ivy is a completion method that's similar to Ido, but with emphasis on simplicity and customizability.

New package names

Changes on MELPA

Due to multiple requests, in an attempt to simplify things a new package ivy has been released on MELPA. The old package swiper, which used to provide most of the ivy features, now only provides swiper.el and depends on ivy. The third package counsel, which provides most of the goodies using ivy hasn't been changed and is still on MELPA. All three packages have the version 0.8.0 currently.

To reiterate the dependencies:

ivy depends on Emacs version larger than 24.1, preferably at least 24.3 (the most common one bundled currently with Linux distributions).
swiper depends on ivy and provides basically 3 commands: swiper, swiper-multi and swiper-all.
counsel depends on swiper and provides around 50 commands for all kinds of stuff. My favorites are counsel-M-x, counsel-git-grep, counsel-rhythmbox and counsel-grep-or-swiper.

Changes on GNU ELPA

On GNU ELPA, a single package ivy-0.8.0 has replaced the previous stable version swiper-0.7.0. This package provides all the files combined of the three separate MELPA packages.

Release summary

The release consists of 282 commits over 5 months by 15 authors. The detailed Changelog is available here, thanks to the ever useful Org mode export. The raw Org file is in doc/Changelog.org in the main repository.

The detailed documentation is available as an (ivy) Info node and also in HTML form here. If anyone wants to document something that's missing there, I'd appreciate the help: simply edit doc/ivy.org and send me a PR.

Release highlights

Below, I'll highlight some of the new features.

Allow to compose collections

For example, to stack the top 10 elements of recentf on top of counsel-locate, use this code:

(defun small-test ()
  (cl-subseq recentf-list 0 10))

(ivy-set-sources
 'counsel-locate
 '((small-test)
   (original-source)))

Here, (original-source) represents the async candidates of counsel-locate. All extra sources are static - each function is called once to generate a list of strings, which will be filtered later.

See #373 for more info.

Improved documentation

If you're not yet familiar with Ivy, you can get a quick reference card by pressing C-h m during any completion session. It will pop up an Org-mode buffer that describes most of the minibuffer key bindings.

Additionally, C-o (hydra-ivy/body), which serves a quick reference as well, received a small restructuring and a new binding. Press D to go to the definition of this hydra. This is useful to see what each key does, you might even want to customize some of it.

Completion in region

From now on, ivy-mode will also set completion-in-region-function. This means that functions like:

C-M-i complete-symbol in many major modes,
TAB while in the M-: (eval-expression) minibuffer,
TAB in a shell buffer,

will use ivy for completion.

Many improvements to `ivy-occur-mode`

You can "permanently" save any completion session by pressing C-c C-o (ivy-occur). This will generate a new buffer in ivy-occur-mode with all your current candidates inserted there. Clicking or pressing f on any of the candidates in that buffer will result in the appropriate action being called with that candidate.

The *ivy-occur ...* buffers can actually be customized per collection type. Specifically for swiper, counsel-git-grep, counsel-grep and counsel-ag, the customizations are already in place that allow you to:

Edit the buffer with wgrep by pressing C-x C-q (ivy-wgrep-change-to-wgrep-mode).
Refresh the buffer due to the original files being changed by pressing g (ivy-occur-revert-buffer).

The second feature is often useful to me when I want to somehow change a symbol throughout the project. First I make a list of all occurrences via e.g. swiper and ivy-occur. After I went through some of the occurrences, I can press g to refresh the search for the same symbol and see how many I still have left.

Yet another cool feature is to press c (ivy-occur-toggle-calling) to toggle calling the action after each line movement and cycle through candidates by holding either j (ivy-occur-next-line) or k (ivy-occur-previous-line).

`ivy-set-action` can work on all commands

Here's the code I'm using currently in my config:

(defun ivy-insert-action (x)
  (with-ivy-window
    (insert x)))

(ivy-set-actions
 t
 '(("I" ivy-insert-action "insert")))

This allows me to press M-o I to insert the current candidate into the buffer. For instance, if I want to quote an Emacs command, I can M-x (counsel-M-x), select the command I want and press M-o I to insert it instead of calling it.

Virtual views in `ivy-switch-buffer`

Here, "virtual" buffer means something that's close to a buffer but not an actual buffer. If you were using the setting ivy-use-virtual-buffers, you'd have your bookmarks and recentf items available to you as virtual buffers.

The new feature allows to select a whole window configuration with many buffers inside nested horizontal and vertical splits from ivy-switch-buffer.

To use it, set ivy-views, since it's nil by default. For instance, here's what I have in my config:

(setq ivy-views
      '(("dutch + notes {}"
         (vert
          (file "dutch.org")
          (buffer "notes")))
        ("ivy {}"
         (horz
          (file "ivy.el")
          (buffer "*scratch*")))))

For a more elaborate and detailed use, see this post by Manuel Uberti.

Magic slash in file name completion

From now on, if you want to enter a directory, simply select a candidate which is a directory and press /. You can still use the old binding C-j (ivy-alt-done), but / is shorter and easier to get used to if you're switching from Ido.

Note that this does not prevent the use of old functionality like:

// to enter the root directory,
/ssh: RET to connect via TRAMP.

A better way to search with `counsel-grep-or-swiper`

If you've ever been annoyed with the long start-up time of swiper in huge buffers, switch to this setting:

(global-set-key "\C-s" 'counsel-grep-or-swiper)

This command will use swiper for small buffers, and counsel-grep for large buffers.

Something very similar to this command was highlighted in this post by Karl Voit.

Just to give you an idea of how fast counsel-grep is:

It has 0s start-up time, since it's async.
For a two million line file weighing 50MB produced by copying org.el a few times, it takes 0.2s to find the 17,664 occurrences of the word hook. It still takes 7.5s to search for org in that file, simply because there are 500,000 candidates and it takes time for Emacs to simply receive that input.

A list of all new commands

The new commands since 0.7.0 are: counsel-tmm, counsel-imenu, counsel-decbinds, counsel-list-processes, ivy-switch-buffer-other-window, counsel-git-stash, counsel-git-log, counsel-pt, counsel-linux-app, counsel-ace-link, counsel-esh-history, counsel-shell-history, counsel-grep-or-swiper.

If any of those sound interesting, go ahead and try them out.

Outro

Thanks to all the contributors. Happy hacking!

Extended syntax for hydra docstrings

2016-04-04T00:00:00+02:00

I've been getting more and more organized in tracking my tasks and time with Org-mode. Still using the usual suspects, of course: GTD and Pomodoro, I'm just getting more diligent with them than in the previous years.

So today I wanted to prettify the good old org-agenda-view-mode-dispatch, which is bound to v in org-agenda-mode. Currently, it's just a boring static message and read-char combination. Why not do it with a hydra instead?

Here's the current full code, that uses the newly extended doc syntax:

(define-key org-agenda-mode-map
    "v" 'hydra-org-agenda-view/body)

(defun org-agenda-cts ()
  (let ((args (get-text-property
               (min (1- (point-max)) (point))
               'org-last-args)))
    (nth 2 args)))

(defhydra hydra-org-agenda-view (:hint none)
  "
_d_: ?d? day        _g_: time grid=?g? _a_: arch-trees
_w_: ?w? week       _[_: inactive      _A_: arch-files
_t_: ?t? fortnight  _f_: follow=?f?    _r_: report=?r?
_m_: ?m? month      _e_: entry =?e?    _D_: diary=?D?
_y_: ?y? year       _q_: quit          _L__l__c_: ?l?"
  ("SPC" org-agenda-reset-view)
  ("d" org-agenda-day-view
       (if (eq 'day (org-agenda-cts))
           "[x]" "[ ]"))
  ("w" org-agenda-week-view
       (if (eq 'week (org-agenda-cts))
           "[x]" "[ ]"))
  ("t" org-agenda-fortnight-view
       (if (eq 'fortnight (org-agenda-cts))
           "[x]" "[ ]"))
  ("m" org-agenda-month-view
       (if (eq 'month (org-agenda-cts)) "[x]" "[ ]"))
  ("y" org-agenda-year-view
       (if (eq 'year (org-agenda-cts)) "[x]" "[ ]"))
  ("l" org-agenda-log-mode
       (format "% -3S" org-agenda-show-log))
  ("L" (org-agenda-log-mode '(4)))
  ("c" (org-agenda-log-mode 'clockcheck))
  ("f" org-agenda-follow-mode
       (format "% -3S" org-agenda-follow-mode))
  ("a" org-agenda-archives-mode)
  ("A" (org-agenda-archives-mode 'files))
  ("r" org-agenda-clockreport-mode
       (format "% -3S" org-agenda-clockreport-mode))
  ("e" org-agenda-entry-text-mode
       (format "% -3S" org-agenda-entry-text-mode))
  ("g" org-agenda-toggle-time-grid
       (format "% -3S" org-agenda-use-time-grid))
  ("D" org-agenda-toggle-diary
       (format "% -3S" org-agenda-include-diary))
  ("!" org-agenda-toggle-deadlines)
  ("["
   (let ((org-agenda-include-inactive-timestamps t))
     (org-agenda-check-type t 'timeline 'agenda)
     (org-agenda-redo)))
  ("q" (message "Abort") :exit t))

And here's how it looks like in action, I simply pressed v while in the agenda:

Since many functions that org-agenda-view-mode-dispatch calls are toggles, it makes sense for hydra-org-agenda-view to display the status of these toggles.

And it's actually convenient to toggle a whole lot of things at once, and the default red hydra keys really come in handy here.

Quick explanation of the syntax

Each head of a hydra looks like:

(key cmd &optional doc &rest plist)

The fairly new bit that I'm using here is the ability to use a sexp instead of a plain string in the doc part. This sexp will be evaluated each time the doc is re-displayed. This means that it can represent a changing variable, for instance the state of a minor mode or a variable.

And here's the best part: the doc of each head can be quoted in the hydra's docstring by using the corresponding key, e.g. ?g?. This allows to have very complex docstrings while keeping them easily aligned in a tabular format.

Here is only the hydra's docstring, copied from the above code:

_d_: ?d? day        _g_: time grid=?g? _a_: arch-trees
_w_: ?w? week       _[_: inactive      _A_: arch-files
_t_: ?t? fortnight  _f_: follow=?f?    _r_: report=?r?
_m_: ?m? month      _e_: entry =?e?    _D_: diary=?D?
_y_: ?y? year       _q_: quit          _L__l__c_: ?l?

Doesn't that look simple?

Emacs completion for launching Linux desktop apps.

2016-03-16T00:00:00+01:00

I'd like to highlight the new command counsel-linux-app that I recently added to the counsel package:

This command looks through your /usr/share/applications/*.desktop and offers to launch them, just like the launcher that you normally get when you press the super key. My current system is Ubuntu, and the launcher here is really horrible, so I'm glad to have a much faster and reliable replacement.

Here's another screenshot, I open the keyboard settings quite often:

Using rsync in dired

2016-02-24T00:00:00+01:00

Here's a code snippet I've found long ago on the internet (the source seems to be no longer accessible), that has proven valuable time and time again:

;;;###autoload
(defun ora-dired-rsync (dest)
  (interactive
   (list
    (expand-file-name
     (read-file-name
      "Rsync to:"
      (dired-dwim-target-directory)))))
  ;; store all selected files into "files" list
  (let ((files (dired-get-marked-files
                nil current-prefix-arg))
        ;; the rsync command
        (tmtxt/rsync-command
         "rsync -arvz --progress "))
    ;; add all selected file names as arguments
    ;; to the rsync command
    (dolist (file files)
      (setq tmtxt/rsync-command
            (concat tmtxt/rsync-command
                    (shell-quote-argument file)
                    " ")))
    ;; append the destination
    (setq tmtxt/rsync-command
          (concat tmtxt/rsync-command
                  (shell-quote-argument dest)))
    ;; run the async shell command
    (async-shell-command tmtxt/rsync-command "*rsync*")
    ;; finally, switch to that window
    (other-window 1)))

(define-key dired-mode-map "Y" 'ora-dired-rsync)

Lets you copy huge files and directories without Emacs freezing up and with convenient progress bar updates. That is all.

Thanks to tmtxt, the mysterious hacker-person from whom the snippet likely originated . Good luck with getting your blog back up.

Visiting URLs and issues with counsel-find-file

2016-02-15T00:00:00+01:00

Many experienced Emacs users are aware of ffap command:

Find FILENAME, guessing a default from text around point. If ffap-url-regexp is not nil, the FILENAME may also be an URL.

It's a great way to open an link, if you plan things in advance. But for me it was usually C-x C-f (annoyed grunt) C-g M-x ffap RET.

Now, thanks to counsel-find-file, it's C-x C-f (anticipated annoyance, followed by a sigh of relief) M-n.

With Ivy completion, M-n calls ivy-next-history-element, which tries to

predict the history element in case you've reached history's edge. The prediction usually simply inserts thing-at-point into the minibuffer. My favorite applications of this are:

C-s M-n - swiper thing-at-point, to get the occurrences of the current symbol in the current file.
C-c j M-n - counsel-git-grep thing-at-point, to get the mentions within the current project.
C-c g M-n - counsel-git thing-at-point to open a file to which the current symbol links.

One thing I've recently added is the \_<...\_> wrapper for when major-mode derives from prog-mode. Since the \_< regex matches the symbol start, and \_> matches the symbol end, there's no chance of getting partial matches. You can call undo or press M-n again in case the symbol bounds aren't useful.

Finally, C-x C-f M-n can be used to open URLs. Recently, I've added functionality to counsel-find-file that allows me to also visit Github issues by simply pointing at the plain issue number, e.g. #123 in either a version-controlled file or in a Magit buffer. The command will query:

$ git remote get-url origin

and fill in all the details. So I no longer bother with bug-reference-url-format and bug-reference-mode - now it's all automatic.

It's also possible to make it work for places other than Github, for instance this code (already included in counsel) makes it work for the Emacs Git repository:

(defun counsel-emacs-url-p ()
  "Return a Debbugs issue URL at point."
  (when (and (looking-at "#[0-9]+")
             (or
              (eq (vc-backend (buffer-file-name)) 'Git)
              (memq major-mode '(magit-commit-mode))))
    (let ((url (match-string-no-properties 0))
          (origin (shell-command-to-string
                   "git remote get-url origin")))
      (when (string-match "git.sv.gnu.org:/srv/git/emacs.git"
                          origin)
        (format "http://debbugs.gnu.org/cgi/bugreport.cgi?bug=%s"
                (substring url 1))))))

(add-to-list 'ivy-ffap-url-functions 'counsel-emacs-url-p)

avy 0.4.0 is out

2016-01-23T00:00:00+01:00

This release consists of 77 commits done over the course of the last 7 months by me and many contributors. Similarly to the 0.3.0 release, the release notes are in Changelog.org. You can read them either at github or inside Emacs. Big thanks to all contributors.

Highlights

A lot of new code is just straight upgrades, you don't need to do anything extra to use them. Below, I'll describe the other part of the new code, which is new commands and custom vars.

`avy-goto-char-timer`

This command now allows as many characters as you like, which makes it similar to a isearch + avy-isearch combination. As you type, you get an isearch-like highlight, then after a short delay you automatically get the avy selection.

Switch the action midway from goto to kill/mark/copy

This is similar to the cool feature of ace-window that allows you to switch the action after you get the avy prompt.

For example, suppose you have:

(global-set-key (kbd "M-t") 'avy-goto-word-1)

Here's what you can do now to a word that starts with a "w" and is select-able with "a":

To jump there: M-t w a.
To copy the word instead of jumping to it: M-t w na
To mark the word after jumping to it: M-t w ma.
To kill the word after jumping to it: M-t w xa.

You can customize avy-dispatch-alist to modify these actions, and also ensure that it plays nicely with your avy-keys, if you customized them. By default, it works fine, since avy-keys is '(?a ?s ?d ?f ?g ?h ?j ?k ?l) and the keys on avy-dispatch-alist are '(?x ?m ?n).

`avy-pop-mark`

This command reverses avy-push-mark which most of avy commands call. It has its own history and works across multiple windows and frames. I'm using it currently as an upgrade to my old (set-mark-command 4) lambda:

(global-set-key (kbd "M-p") 'avy-pop-mark)

Here's a line to make avy-pop-mark work also for swiper:

(advice-add 'swiper :before 'avy-push-mark)

Using Emacs as system-wide Rhythmbox interface

2016-01-18T00:00:00+01:00

In an earlier post, I described how I've been managing Rhythmbox from Emacs. I've bound the entry point to C-S-o:

(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)

Obviously, this entry point won't work while outside Emacs. Today, I'll describe how I've made it work everywhere. Everywhere on Ubuntu 14.04, that is, although a similar approach should work for other distributions.

Step 1: Make sure the Emacs server is running

Here's the relevant part of my init.el:

(require 'server)
(or (server-running-p) (server-start))

Using emacsclient is essential to avoiding the extra startup time: even a startup time of one second feels sluggish when all I need is to open a menu with a song playlist.

Step 2: Install the relevant X window tool

Initially, I only wrote a call to emacsclient, which resulted in the Emacs window gaining focus in the end. Then I thought it would be nice to give the focus back the original window after the end of selection, and raise it as well.

I wanted to do something with wmctrl, but I found that xdotool can do what I want in a simple way.

sudo apt-get install xdotool

Step 3: Write a shell script

#!/bin/bash
wnd_id="$(xdotool getwindowfocus)"
emacsclient --eval "(progn (x-focus-frame nil) (counsel-rhythmbox))"
xdotool windowfocus $wnd_id
xdotool windowraise $wnd_id

Here, (x-focus-frame nil) will raise the Emacs window and give the keyboard input focus. emacsclient will return as soon as I select something or press C-g. At that point the keyboard focus will be returned to whatever window had it when the script was invoked.

By the way, here's a cool configuration that automatically makes a file executable if it starts with #!.

(add-hook
 'after-save-hook
 'executable-make-buffer-file-executable-if-script-p)

Step 4: Bind the shell script to a key

Open this (possibly using gnome-control-center instead, if applicable):

unity-control-center keyboard

And add a new shortcut in Shortcuts/Custom Shortcuts. I've bound that one to C-S-o as well.

The final result

It's pretty convenient: as I'm scrolling something I'm reading in Firefox with j (via Firemacs), I can seamlessly press C-S-o moo RET to play "Sisters of the Moon", and continue scrolling the web page with j.

What's more, Emacs has very nice support for input methods with C-\ (toggle-input-method), so I can also quickly select Ukrainian-titled songs, while still keeping shortcuts like C-n and C-m (without having to switch the input method back).

The whole experience is similar to gnome-do/synapse, which I was using a few years back, except better because now it's in Emacs.

Better fuzzy matching support in Ivy

2016-01-06T00:00:00+01:00

Recently, I wrote some code to add better highlighting for Ivy's fuzzy matcher. Here's a quick step-by-step to get an equivalent of flx-ido-mode working with Ivy.

Step 1: install the packages

M-x package-install - counsel and flx (MELPA should be configured).

Step 2: configure `ivy-re-builders-alist`

Here's the default setting:

(setq ivy-re-builders-alist
      '((t . ivy--regex-plus)))

The default matcher will use a .* regex wild card in place of each single space in the input. If you want to use the fuzzy matcher, which instead uses a .* regex wild card between each input letter, write this in your config:

(setq ivy-re-builders-alist
      '((t . ivy--regex-fuzzy)))

You can also mix the two regex builders, for example:

(setq ivy-re-builders-alist
      '((ivy-switch-buffer . ivy--regex-plus)
        (t . ivy--regex-fuzzy)))

The t key is used for all fall-through cases, otherwise the key is the command or collection name.

The fuzzy matcher often results in substantially more matching candidates than the regular one for similar input. That's why some kind of sorting is important to bring the more relevant matching candidates to the start of the list. Luckily, that's already been figured out in flx, so to have it working just make sure that the flx package is installed.

Step 3: optionally configure `ivy-initial-inputs-alist`

The ivy-initial-inputs-alist variable is pretty useful in conjunction with the default matcher. It's usually used to insert ^ into the input area for certain commands.

If you're going fuzzy all the way, you can do without the initial ^, and simply let flx (hopefully) sort the matches in a nice way:

(setq ivy-initial-inputs-alist nil)

The result

Here's how M-x counsel-M-x looks like now:

Ivy-mode 0.7.0 is out

2015-12-07T00:00:00+01:00

Intro

Ivy-mode is a completion method that's similar to Ido, but with emphasis on simplicity and customizability. Currently, there are two related packages on MELPA: swiper and counsel:

swiper provides an isearch replacement, using ivy-read for completion, as well as the basic ivy-mode.
counsel provides some extra commands that use ivy-read, like -M-x, -ag, -load-theme etc.

Release Notes

The release notes are available at the homepage as usual. There are 220 commits since the last release, which was on Aug 5, roughly 4 months ago. Slowly but surely, the contributors list has grown to 20 people, besides me. A few people even got their Emacs Copyright Assignment just to make large contributions. Statistically, Org-mode is probably the prime package that leads to the most CA, but I'm glad that Ivy is there as well, contributing in a small way.

The release notes are made in Org-mode, each new version is a level 1 heading. With time, hopefully, their parts will make their way into the manual, which is also in Org-mode.

In addition, I also export each new release notes to Markdown using pandoc, since that's what Github prefers.

Release Process

Since the release notes for 0.7.0 are huge, I don't embed them into the post, they're listed separately. You can go through them at your own pace, or wait until I make some highlights for each piece either or the blog or in the manual. The manual, by the way, is a work in progress but is already distributed in MELPA. Use C-h i followed by g (ivy) to read it. If you're new to reading the info pages, there's info on info in info format: use dg (info) to access it.

Today, I'll describe some cool stuff that I used to generate the Markdown notes from Changelog.org.

Org-mode's `org-narrow-to-subtree`

Since Changelog.org already has a 0.6.0 branch that I didn't want to see, I've narrowed the buffer to only the 0.7.0 branch. This is possible to do thanks to Emacs' narrowing feature and org-narrow-to-subtree. After this command, the buffer behaves as if the 0.6.0 branch isn't there and the only content is 0.7.0 branch. But if I perform any edits and save the file, everything that was hidden is still there.

As a shortcut, I'm using my worf to narrow faster. Pressing [ while worf-mode is active goes back to the current heading start. While at heading start, pressing alphanumeric keys calls commands instead of self-inserting:

N calls org-narrow-to-subtree,
W calls widen, which turns narrowing off.

There are, of course, many more commands and bindings in worf. Check it out if you like Org's Speed Keys feature, but feel like it could use more structure.

`pandoc-mode`

pandoc-mode is an Emacs interface to pandoc - a tool that allows to export documents from one format to another. The Elisp package is available in MELPA. And I installed pandoc-1.15.2-1-amd64.deb from its homepage with:

sudo dpkg -i pandoc-1.15.2-1-amd64.deb

After that, M-x pandoc-mode and I'm on easy street: C-c / calls pandoc-main-hydra/body:

Set the output format to Github-flavored Markdown with OG.
Set the input format to Org-mode with bIo.
Export with C-c / r.
View the resulting buffer with C-c / V.

Add table of contents to Markdown

I used M-x markdown-toc/generate-toc for this. The MELPA package markdown-toc provides this function. The resulting table of contents is a list with a bunch of links, which turned out to be dead, because of the way Github renders Markdown for releases.

Use `swiper` to replace each Markdown link with its title

Since swiper works with regexps, here's what I input to match each link:

\[\(.*?\)\](.*?)

This matches anything in brackets (non-greedy), followed by anything in parens; the bracket's content is captured in a group.

Then I press M-q (swiper-query-replace) and enter \1 as replacement - the first captured group. After this, I confirm each replacement with y or confirm them all at once with !.

Use `rectangle-mark-mode` to promote TOC one level

Since all entries in the TOC were children to a single 0.7.0 entry, I wanted to remove that entry and promote its children one level. This can be done with rectangle-mark-mode, bound by default to C-x SPC.

In my config, I use this instead:

(global-set-key (kbd "C-x SPC") 'hydra-rectangle/body)

Where, hydra-rectangle/body is provided by hydra-examples.el and is also described in an earlier post. I really liked the hydra-rectangle/body idea and use it all the time. Here's a key sequence I used to delete a 4x95 rectangle in order to promote the list items: C-x SPC 4l95jdo.

Use basic Elisp to turn each bug reference into an Org-mode link

When copy-pasting from the commit log into Changelog.org, I quickly tired of putting the each issue link as e.g. [[https://github.com/abo-abo/swiper/issues/244][#244]]. So I wrote e.g. #244 instead, and used this code in the end to make the transformation:

(defun ora-quote-github-issues ()
  (interactive)
  (let ((base "https://github.com/abo-abo/swiper/issues/"))
    (goto-char (point-min))
    (while (re-search-forward "\\([^[]\\)#\\([0-9]+\\)" nil t)
      (replace-match
       (format "%s[[%s%s][#%s]]"
               (match-string 1)
               base
               (match-string 2)
               (match-string 2))))))

If anyone reading the blog wants to start with some basic Elisp, the above function is a nice intro to a lot of useful functions. And I expect that many people face this sort of automation scenario pretty often. I'm pretty sure that M-% query-replace-regexp could work here as well, but it's easier for me to just write out the code and save it for later.

Outro

Thanks to everyone who contributed issues, code and documentation. Enjoy the new release.

I move my s-expressions back and forth

2015-11-30T00:00:00+01:00

Some people find lispy too weird and/or complex to try, quite possibly because of it's sort-of-modal key binding structure. Which is a shame, since out of 7k lines of lispy's code, only 500 lines do key bindings, the rest do all sorts of useful stuff, like sexp navigation/modification, outlines and REPL interaction.

In this post, I'll show a short example of using lispy's functions outside of lispy-mode, and compare it with the default approach.

Moving s-expressions while the point is anywhere

Using this simple hydra, and the key sequence C-c m sss www I got the following GIF:

Doing the same lispy-way

To do it the lispy-way, I move the point before the list that I wish to operate on (with [ key), and press sss www to get the following GIF:

The difference here is that no hydra is necessary in the second case, the key bindings come only from lispy-mode. But the first case will also work if lispy-mode is off.

Which way is better?

I think the second way is better, since it's faster and more clear, but you can decide for yourself. By the way, you can also move symbols, comments and sub-words (if that makes sense) with w and s, provided you mark them with a region first.

New feature in Ivy - ivy-occur

2015-11-04T00:00:00+01:00

I've had an idea with this feature for quite some time, and only recently got to finally implement it. So here it goes: with ivy-occur, bound to C-c C-o while in the minibuffer, you can store almost Ivy any completion session in progress, and you can have as many of them as you like.

Example 1

This is where the command name originates from: swiper + ivy-occur = occur. You can store all of swiper's matching lines into a separate buffer. This doesn't give too much advantage over the good-old occur, the only thing is that you can use ivy-style regexps with wild spaces, and have an interactive preview beforehand. Having said that, it actually sounds pretty good!

Example 2

I press C-S-o, bound to counsel-rhythmbox, and enter u2. After pressing C-c C-o, bound to ivy-occur, the completion session is closed (effectively C-g), and a new buffer *ivy-occur counsel-rhythmbox "u2"* is generated with all songs that match u2.

As a reminder, counsel-rhythmbox has two actions: play (the default) and enqueue. In this new buffer, pressing RET or mouse-1 will call the play action (since it was active at the moment ivy-occur was called) for the current candidate. So I've effectively added a playlist functionality to counsel-rhythmbox through a generic command.

Note that it's very easy to identify a completion session by the command name and input. So I can distinguish e.g. *ivy-occur counsel-rhythmbox "u2"* and *ivy-occur counsel-rhythmbox "скря"*, and quickly select them with ivy-switch-buffer: just input rhy, usually only these two and similar buffers will match.

Example 3

Suppose I want to go through the documentation of all variables that end in -function. Easy:

<f1> v (counsel-describe-variable) with input function$.
C-c C-o (ivy-occur).

I get a new buffer named *ivy-occur cousnel-describe-variable "function$*" with 346 candidates. I can go through them at my own pace, possibly doing other completion stuff in between without disturbing my process. It's also convenient to navigate these buffers with swiper.

Example 4

Let's tweak the previous one. After inputting function$ I can press C-M-a (ivy-read-action) followed by d to select the definition action. Then again C-c C-o (ivy-occur). Pressing RET in the resulting buffer will take me to that variable's definition, instead of describing it as before. A similar thing could be done for counsel-rhythmbox to get the enqueue action in *ivy-occur* buffer, instead of play.

Example 5

This is an improvement to my workflow for quickly looking at a new package's features. This can be done with oge (lispy-goto-elisp-commands) from lispy, which scans the source for (interactive) tags and allows to jump to their definition.

It's a pretty cool optimization, compared to looking at all tags. For example, projectile currently has 375 top-level tags (functions and variables). But with lispy-goto-elisp-commands I only get 48 tags. And now I can have them in a convenient permanent list too.

Alternatively, if projectile is already loaded, I can use counsel-M-x with input projectile-, followed by C-M-a d to select the definition action, followed by C-c C-o.

As a reminder of how it works, counsel-M-x is defined with a single action that calls the selected command. But then, I've also added this statement at top-level of counsel.el:

(ivy-set-actions
 'counsel-M-x
 '(("d" counsel--find-symbol "definition")))

This means that you can add as many actions as you like to ivy-read commands. And of course customize the binding and the hint, which are in this case d and definition respectively.

Limitations

Unfortunately, since the *ivy-occur* buffer needs to know the action to execute, it only works for commands that explicitly pass :action to ivy-read. For instance, it won't work for package-install with ivy-mode on: the buffer will be properly generated, but pressing RET won't install a package.

Fortunately, it's not hard to write a version that works:

(defun counsel-package-install ()
  (interactive)
  (ivy-read "Install package: "
            (delq nil
                  (mapcar (lambda (elt)
                            (unless (package-installed-p (car elt))
                              (symbol-name (car elt))))
                          package-archive-contents))
            :action (lambda (x)
                      (package-install (intern x)))
            :caller 'counsel-package-install))

Here's a buffer with a list of packages matching "ga"; pressing RET will install the selected package:

Small note on key bindings

In the initial post, I wanted to bind ivy-occur to C-c o instead of C-c C-o. But I was reminded that C-c LETTER are reserved. I still think it's a better binding. If you agree, you can add it to your config:

(define-key ivy-minibuffer-map (kbd "C-c o") 'ivy-occur)

Additionally, ivy-occur is also available on C-o u, through the C-o hydra.

Outro

I think ivy-occur is a very powerful command that shouldn't be overlooked. Just as ivy-resume implements a sort of DEL or C-u key for completion, ivy-occur implements a convenient way to switch and store the completion context, a sort of C-x o or C-x b for completion.

New in Emacs 25 - convenient compression/decompression in Dired

2015-10-23T00:00:00+02:00

Today I'll describe my past and current workflows for compressing files and directories in Dired. In my opinion, Dired is one of the best features of Emacs - a great abstraction of cd+ls that lets you get things done much faster. The default binding for dired is C-x d (I bind it to C-;-d though, see my xmodmap post).

My previous workflow

To compress several files in Dired, first I compile a list of files to work on by marking them with m (dired-mark), navigating to ones that you want with n (dired-next-line) and p (dired-previous-line).

Once a list is ready, I press & (dired-do-async-shell-command), which allows me to run an arbitrary shell command. I enter:

tar -czf ~/tmp/path/foo.tar.gz *

into the minibuffer, press RET and I'm done. It's a standard shell command with 2 advantages:

I get TAB completion for the directory of the created archive.
* means the selected file list, so I don't enter them by hand.

My current workflow

Since I often forget the command for tar, and I really don't want to remember the commands for zip etc, I've implemented a more convenient approach:

(define-key dired-mode-map "c" 'dired-do-compress-to)

This new command dired-do-compress-to, bound to c, will prompt me for a file name of the output archive. So now it's easier to type in that file name, if you use ido-mode / ivy-mode / helm-mode. What's more, the command will be automatically determined from the archive extension and executed. Here's the corresponding customization variable:

(defvar dired-compress-files-alist
  '(("\\.tar\\.gz\\'" . "tar -c %i | gzip -c9 > %o")
    ("\\.zip\\'" . "zip %o -r --filesync %i"))
  "Control the compression shell command for `dired-do-compress-to'.

Each element is (REGEXP . CMD), where REGEXP is the name of the
archive to which you want to compress, and CMD the the
corresponding command.

Within CMD, %i denotes the input file(s), and %o denotes the
output file. %i path(s) are relative, while %o is absolute.")

This thing is pretty self-explanatory. It currently only supports *.tar.gz and *.zip, use M-x report-emacs-bug if you want to add more options.

Other improvements in compression/decompression

I improved the good-old Z (dired-do-compress) as well. Now it can compress directories to *.tar.gz, as well as decompress *.tar.gz and *.zip to directories. It's all automatic, you only have to press Z, either on an archive to decompress, or on a directory to compress.

Easy way to have a bleeding edge Emacs

If you want to get these improvements right now and are on a Debian type system (I use Ubuntu), you can use:

sudo apt-add-repository ppa:ubuntu-elisp/ppa
sudo apt-get update
sudo apt-get install emacs-snapshot

Then just use emacs-snapshot executable. It updates every few days.

Myself, I track the Emacs master from git. But emacs-snapshot is very useful for CI tests, and can also be used by people who don't want to build the executable from git.

How to get your improvements into Emacs

If you'd like to contribute code to the Emacs core yourself, it takes two steps:

Sign the Copyright Assignment (CA). This gives the Copyright for your changes to Emacs to the Free Software Foundation. This is useful so that the FSF can defend your rights in court, in case the GPL regarding your contribution is broken by someone.
M-x report-emacs-bug and attach a patch.

It seems that some people could have a moral objection to the CA. I see no reason for it whatsoever. Since Elisp libraries make calls to GPL code and are GPL themselves, you have to publish Elisp code under GPL, there's no choice there. GPL means basically that, while you're still acknowledged as the author, everyone else has about as much right to your code as you do. No one can hide or restrict access to it, but neither can you. The CA is a further step, which makes the FSF own the Copyright to your changes to Emacs. You submit these changes yourself, and the Copyright over these changes isn't really that useful: they're only changes - they do nothing on their own, outside of Emacs. Besides, with the FSF owning the Copyright, the range of things that you can do to your code stays exactly the same as if you owned the Copyright, as long as you publish under GPL.

To illustrate, the FSF CA is very polite and benign, compared to the CA that I have to give to Elsevier when I publish an article. That CA means that a multi-billion dollar corporation owns the right to my paper until the end of time, and can charge people to view it (including myself and my peers) as much as they see fit (currently, $30). Of course, I don't receive a dime of that money, but hey - I get published, and at least I can share my article for free for the first 50 days of the publish date. And if that one doesn't seem draconian enough for you, just think of the NDAs in commercial companies: out there, you can't even publish or mention anything related to your work. So please, if you're hating on the FSF, do reconsider, they're the good guys in my book.

Eventually, after a few submitted patches, you'll be granted commit access. This is a great way to implement small improvements faster. However, the larger issues that aren't simple improvements still need to be discussed with other developers, either on debbugs or on emacs-devel. For example, initially I went with the tar -czf command. But it turns out that it can't be used on Solaris 10 or AIX 7.1. Whatever those things are, people still use Emacs on them, and it's important that the core features are usable on all supported systems.

A simple multiple-cursors extension to swiper

2015-10-14T00:00:00+02:00

When using Emacs, it happens sometimes that I accumulate too many buffers. The usual next action is to close the buffers for the project that I'm not currently working on. Previously, I marked those buffers in *Buffer List* by hand with d and C-n. Today, I'll show a faster way.

It's very easy to select these buffers in *Buffer List* with swiper: just type a part the shared directory name. Another example is to select all dired buffers: a "dired by" input will usually match all of them, since they all have Dired by name in their line.

Afterwards, I want to open multiple-cursors for each matched line. I've bound this action to C-7. Here's the very simple code:

(defun swiper-mc ()
  (interactive)
  (unless (require 'multiple-cursors nil t)
    (error "multiple-cursors isn't installed"))
  (let ((cands (nreverse ivy--old-cands)))
    (unless (string= ivy-text "")
      (ivy-set-action
       (lambda (_)
         (let (cand)
           (while (setq cand (pop cands))
             (swiper--action cand)
             (when cands
               (mc/create-fake-cursor-at-point))))
         (mc/maybe-multiple-cursors-mode)))
      (setq ivy-exit 'done)
      (exit-minibuffer))))

After C-7, here's the sequence to delete the selected buffers:

d (Buffer-menu-delete) to mark each item for deletion.
C-g (keyboard-quit) to exit multiple-cursors.
x (Buffer-menu-execute) to execute the deletions.

And that's it: all selected buffers are now deleted. To summarize, C-s dired by C-7 d C-g x will close all dired buffers from your *Buffer List*.

Other interesting applications are also possible, like mass renames in wdired, or un-commenting everything in a function. For example, suppose that you have this code:

(progn
  ;; (check-1)
  (foo)
  ;; (check-2)
  (bar)
  ;; (check-3)
  (baz))

If it's a part of a larger buffer, you can narrow with C-x nd (narrow-to-defun) or C-x nn (narrow-to-region). Then C-s ;; C-7 DEL DEL C-d C-g to remove all comments.

I have to say that the functionality intersects a bit with mc/mark-all-like-this. Except you know the result ahead of time (number and position of matches), and you can use a regex instead of a literal string.

Swiper and visual-line-mode

2015-10-02T00:00:00+02:00

In case you encounter files with very long lines, the built-in M-x visual-line-mode might come in handy. Although 1MB long one-line files are a disaster for Emacs, there's no problem handling smaller files with long lines that result from bad markdown renderers (notably Github). They way visual-line-mode works, is it inserts virtual newlines in appropriate positions, so that no line is truncated. The advantage is that these newlines aren't written to the file when the buffer is saved (otherwise, a simple M-q (fill-paragraph) would work too).

Today I've added visual-line-mode support to swiper, so handling these files should be even easier now. The change was surprisingly simple: just two checks for visual-line-mode variable and these basic replacements:

forward-line -> line-move,
line-beginning-position -> beginning-of-visual-line,
line-end-position -> end-of-visual-line.

By the way, visual-line-mode is one of the small number of commands that I call by name instead of by key chord. But thanks to counsel-M-x and smex calling this command by name is as short as C-t v RET. To explain a bit more, here's my setup:

;; make sure to install smex
(global-set-key (kbd "C-t") 'counsel-M-x)

The default command bound to C-t is transpose-chars - a highly situational and ultimately counter-productive command (M-DEL and re-typing the word is faster than surgically navigating to the transpose point and calling transpose-chars, plus it trains the hands to type the word correctly next time). Anyway, C-t is a prime binding for launching interactive commands. And since smex is installed it remembers that my most used command that starts with "v" is visual-line-mode - so it's the first one that gets selected after C-t v. This means that I can just press RET and be done with it.

Finally, related to visual-line-mode, here's a command I use to negate M-q (fill-paragraph) (source):

(global-set-key (kbd "C-M-q") 'ora-unfill-paragraph)

(defun ora-unfill-paragraph ()
  "Transform a paragraph into a single line."
  (interactive)
  (let ((fill-column (point-max)))
    (fill-paragraph nil t)))

Thanks to @joostkremers for the suggestion in #227.

More tweaks to Ivy minibuffer faces

2015-09-29T00:00:00+02:00

This is a continuation of the thought that I started in the last post a few weeks ago. I don't fancy myself a graphical designer, but I kind of have a feeling of what I like - I certainly know it when I see it.

I wasn't quite happy with the color of the current selection in the minibuffer. Then it hit me that I like the way the Firefox address bar does it: invert the selected text foreground to white and add a flashy background. After that, it was only a matter of going though a few random color permutations in the GIMP color selector to arrive to a nice state:

I did add something similar for dark background themes, although I rarely use them myself, since they contrast too much with Firefox, with most websites having a light background:

(defface ivy-current-match
  '((((class color) (background light))
     :background "#1a4b77" :foreground "white")
    (((class color) (background dark))
     :background "#65a7e2" :foreground "black"))
  "Face used by Ivy for highlighting first match.")

Of course, the standard recommendation follows to use rainbow-mode in buffers that deal with colors - it's great.

Finally, counsel-git-grep and counsel-ag now also add the proper minibuffer coloring if you have it turned on:

(setq ivy-display-style 'fancy)

If you're interested in how the face backgrounds are combined, you can read my older article on color blending in Elisp.

Fancy minibuffer faces for Ivy completion

2015-09-04T00:00:00+02:00

Today, I'll describe a recent improvement to the display of Ivy completion. To use it, add this code to your configuration:

(setq ivy-display-style 'fancy)

After this, swiper will look like this:

And counsel-M-x will look like this:

If you haven't used it before, counsel-M-x is part the counsel package on MELPA, or part of swiper package if you're installing from GNU ELPA. Basically, it's a M-x replacement (that I like to bind to C-t for efficiency reasons), that doubles as find-function (just press C-. instead of RET to find the function instead of calling it). If you're using counsel-M-x I highly recommend to also install smex, since then counsel-M-x will use smex for sorting the matched commands.

The update will propertize the minibuffer contents with a new set of faces:

(defcustom swiper-minibuffer-faces
  '(swiper-minibuffer-match-face-1
    swiper-minibuffer-match-face-2
    swiper-minibuffer-match-face-3
    swiper-minibuffer-match-face-4)
  "List of `swiper' faces for minibuffer group matches.")

Initially, when responding to #212, I used the original swiper faces in the minibuffer as well. But after some use, their brightness became a bit annoying. So I introduced a new set of faces that can be customized separately.

Here are the settings that I'm currently using:

(custom-set-faces
 '(swiper-minibuffer-match-face-1
   ((t :background "#dddddd")))
 '(swiper-minibuffer-match-face-2
   ((t :background "#bbbbbb" :weight bold)))
 '(swiper-minibuffer-match-face-3
   ((t :background "#bbbbff" :weight bold)))
 '(swiper-minibuffer-match-face-4
   ((t :background "#ffbbff" :weight bold))))

It's similar to what the Firefox address bar uses: gray background and bold font. Additionally, the matching parts are highlighted with pale gray, blue and magenta colors. If you like the color scheme, it's part of eclipse-theme. Another choice, for even less distraction, could be to remove the background from these faces, only leaving the bold part on the matches.

Thanks to @Wilfred for nudging me to finally implement this feature. It's been on my list for a long time, but I've been putting it off.

Complete Python symbols using Ivy

2015-08-26T00:00:00+02:00

I had a fascination with Python at one point, until I got too annoyed with the indentation rules. I still have a few scripts left over, so I'm sympathetic to Python support in Emacs. The reason for today's post comes from this question on Emacs StackExchange. Essentially, the user wants to insert parens automatically when a function name is completed.

The completion candidates come from jedi plugin. To quickly see where the list of strings is coming from, I've examined ac-sources variable and saw that it contains ac-source-jedi-direct, which evaluates to:

((candidates . jedi:ac-direct-matches)
 (prefix . jedi:ac-direct-prefix)
 (init . jedi:complete-request)
 (requires . -1))

This means that jedi:complete-request has to be called at point, followed by jedi:ac-direct-matches to obtain the list of strings. So basically, this code:

(progn
  (deferred:sync!
   (jedi:complete-request))
  (jedi:ac-direct-matches))

Note the call to deferred:sync!. I had to add that one to make sure that jedi:complete-request completes before jedi:ac-direct-matches is called.

Testing with some Python code, where | is the point:

params = {"foo":"bar"}
params.i

The Elisp code above will return:

(#("items"
   0 5 (summary
        "function: __builtin__.dict.items"
        symbol
        "f"
        document
        "items(self)

D.items() -> list of D's (key, value) pairs, as 2-tuples"))
  #("iteritems"
    0 9 (summary
         "function: __builtin__.dict.iteritems"
         symbol
         "f"
         document
         "iteritems(self)

D.iteritems() -> an iterator over the (key, value) items of D"))
  #("iterkeys"
    0 8 (summary
         "function: __builtin__.dict.iterkeys"
         symbol
         "f"
         document
         "iterkeys(self)

D.iterkeys() -> an iterator over the keys of D"))
  #("itervalues"
    0 10 (summary
          "function: __builtin__.dict.itervalues"
          symbol
          "f"
          document
          "itervalues(self)

D.itervalues() -> an iterator over the values of D")))

So these strings come with the symbol documentation and symbol type encoded as string properties. After this, the rest of the Elisp code follows very easily, you can find it as part of counsel package on MELPA:

(defun counsel-jedi ()
  "Python completion at point."
  (interactive)
  (let ((bnd (bounds-of-thing-at-point 'symbol)))
    (if bnd
        (progn
          (setq counsel-completion-beg (car bnd))
          (setq counsel-completion-end (cdr bnd)))
      (setq counsel-completion-beg nil)
      (setq counsel-completion-end nil)))
  (deferred:sync!
   (jedi:complete-request))
  (ivy-read "Symbol name: " (jedi:ac-direct-matches)
            :action #'counsel--py-action))

(defun counsel--py-action (symbol)
  "Insert SYMBOL, erasing the previous one."
  (when (stringp symbol)
    (with-ivy-window
      (when counsel-completion-beg
        (delete-region
         counsel-completion-beg
         counsel-completion-end))
      (setq counsel-completion-beg
            (move-marker (make-marker) (point)))
      (insert symbol)
      (setq counsel-completion-end
            (move-marker (make-marker) (point)))
      (when (equal (get-text-property 0 'symbol symbol) "f")
        (insert "()")
        (setq counsel-completion-end
              (move-marker (make-marker) (point)))
        (backward-char 1)))))

Essentially, the last interesting part is (equal (get-text-property 0 'symbol symbol) "f") which test if the string corresponds to a function or not. The rest of the code just fiddles with symbol markers with ensure that the previous symbol is erased before the new symbol is inserted if you press C-M-n (ivy-next-line-and-call), or use ivy-resume. Just to describe how this would be useful for the Python code above: I call counsel-jedi, followed by C-M-n to get:

params = {"foo":"bar"}
params.iteritems(|)

Pressing C-M-n again will result in:

params = {"foo":"bar"}
params.iterkeys(|)

Once I'm satisfied with my selected candidate, I can press either C-m or C-j or C-g. Most of the above code can be used almost verbatim if you're a Helm fan and want to implement helm-jedi. Basically, the approach I described (going through ac-sources) can be used to implement alternative completion in a lot of cases where auto-complete-mode completion is already available.

Finally, if you like the idea of auto-inserting parens with completion and are using C/C++, have a look at function-args - this package does that too, with Ivy, Ido and Helm as available back ends.

Store all current ivy candidates into the kill ring

2015-08-14T00:00:00+02:00

I'd like to highlight a new command added to ivy-mode today: ivy-kill-ring-save. It allows to store all current candidates to the kill ring. This could have a number of uses.

Scenario 1

Suppose you want to learn some Elisp, specifically all functions that start with forward-. Then call counsel-describe-function with "forward-" as input and press M-w. Then just yank this into some buffer, org-mode for instance, and go through the functions one-by-one takings notes on the way:

forward-comment
forward-paragraph
forward-thing
forward-symbol
forward-visible-line
forward-word
forward-same-syntax
forward-whitespace
forward-button
forward-line
forward-list
forward-sentence
forward-point
forward-to-indentation
forward-ifdef
forward-char
forward-sexp
forward-page

Scenario 2

Suppose you want to store a subset of projectile-find-file names that match a pattern. Just press M-w and those file names will be on the top of the kill ring. Of course, you need to have this setting on:

(setq projectile-completion-system 'ivy)

This scenario should apply to basically any place where you're completing file names, like counsel-locate or counsel-find-file. Also find-file-in-project, which uses ivy for completion if it's installed.

Outro

Note also that the command comes for free, since normally nothing is done by M-w when the region isn't active. When the region is active, this command will store the selected text instead of matched candidates.

Thanks to @drorbemet for giving me the idea in #197.

Ivy-mode 0.6.0 is out

2015-08-05T00:00:00+02:00

For those who don't keep up, ivy-mode is a completion method that's similar to ido, but with emphasis on simplicity and customizability. Currently, there are two related packages on MELPA: swiper and counsel:

swiper provides an isearch replacement, using ivy-read for completion, as well as the basic ivy-mode.
counsel provides some extra commands, like -M-x, -ag, -load-theme etc.

The reasoning behind the split into two packages is that there's less update overhead if only one of them is updated.

`completing-read-function` conundrum

This is to explain a bit the presence of the counsel package. Initially, I hoped that ivy-mode could do most of the work, via the Emacs' completing-read-function interface. How it works: most built-in packages will call completing-read when they require completion. That function will forward the completion to completing-read-function if it's set. This is the way how things like icomplete-mode or ivy-mode or helm-mode work.

Unfortunately, the interface rather limits what you can do in completing-read-function. Essentially, you're given a list of strings and you have to return a string. You have no idea which function called you, so you can't do any fancy stuff depending on the caller, short of examining this-command which isn't very reliable. You have no idea what will be done with the one string that you return, so you can't do something fancy like select two or three strings and perform that action for each of them.

The result is that sometimes I have to replace the built-in functions, instead of re-using them. So instead of re-using find-file, I wrote my own counsel-find-file that looks like this:

(defun counsel-find-file ()
  "Forward to `find-file'."
  (interactive)
  (ivy-read "Find file: " 'read-file-name-internal
            :matcher #'counsel--find-file-matcher
            :action
            (lambda (x)
              (with-ivy-window
                (find-file (expand-file-name x ivy--directory))))
            :preselect (when counsel-find-file-at-point
                         (require 'ffap)
                         (ffap-guesser))
            :require-match 'confirm-after-completion
            :history 'file-name-history
            :keymap counsel-find-file-map))

It's still possible to call the original find-file, and you'll get ivy-read completion for it, but:

ivy-resume won't work, since ivy-read doesn't know what to do with the string that you select.
C-M-n (ivy-next-line-and-call) won't work to select another file within the same completion session, for the same reason.
M-o (ivy-dispatching-done) may work with some customization, but since it dispatches on this-command to get the extra actions, it can cause a problem if the command wasn't called directly.

I think it would be cool to extend the built-in completing-read-function interface in the future Emacs versions. Both Ivy and Helm (which uses the same strategy of passing the action to the completion) would benefit from this.

Release summary and highlights

It's been two months and 150 commits since the last version. The full release notes can be found inside the repository in Changelog.org or at Github's release tab.

I recommend to look through the whole list to see if anything catches your attention. I'll highlight a few things that I think the users might be interested in most.

Fuzzy completion

This is off by default, since I think having less candidates is better than having more. You can customize this for all commands or per-command. For example:

(setq ivy-re-builders-alist
      '((t . ivy--regex-fuzzy)))

`swiper` has a `case-fold-search` optimization

Binds case-fold-search to t when the input is all lower-case:

input "the" matches both "the" and "The".
input "The" matches only "The".

Anzu things

To see not only the number of matched candidates, but also the index of the current one, set this:

(setq ivy-count-format "(%d/%d) ")

Customize additional exit points for any command

For any command that uses ivy-read that is. Example for ivy-switch-to-buffer:

(ivy-set-actions
 'ivy-switch-buffer
 '(("k"
    (lambda (x)
      (kill-buffer x)
      (ivy--reset-state ivy-last))
    "kill")
   ("j"
    ivy--switch-buffer-other-window-action
    "other")))

After this:

Use M-o k to kill a buffer.
Use M-o j to switch to a buffer in other window.

You can always use M-o o to access the default action. When there is only one action, M-o does the same as C-m.

More descriptions with a built-in Hydra

Toggle C-o in any completion session to get an overview of the things that you can do.

Many commands that interface with shell calls

The following commands will call the appropriate shell tool to give you a list of candidates:

counsel-git-grep
counsel-ag
counsel-locate
counsel-recoll

These commands will refresh after each new letter entered, and they account for the fact that the shell call will usually take more time than the time it takes to input a new letter. So the process will be killed and restarted, resulting in virtually no keyboard delay and no downtime.

Many commands that offer more options than the built-in counterparts

This list includes:

counsel-find-file,
counsel-M-x,
counsel-load-theme,
counsel-org-tag and counsel-org-tag-agenda.

Most extra things that you can do are:

Doing stuff with multiple candidates through C-M-n like in this video.
Using ivy-resume to resume the last completion session.

Make sure to try counsel-org-tag, this one is a bit tricky for completion, since it requires to return multiple candidates at once. So you can toggle each tag with C-M-m (ivy-call) and then exit with C-m (ivy-done). The currently selected tags will be displayed in the prompt.

Outro

A big thanks to all people who contributed code and issues towards this release. I'm really happy that you're helping me to refine this nice package.

Using Recoll desktop search database with Emacs

2015-07-27T00:00:00+02:00

I know that most Emacs hackers love the simplicity and usability of grep, but sometimes it just doesn't cut it. A specific use case is my Org-mode directory, which includes a lot of org files and PDF files. There are just too many files for grep to be efficient, plus the structure of PDF doesn't lend itself to grep, so another tool is required: a desktop database.

I got into the topic by reading John Kitchin's post on swish-e, however, I just couldn't get that software to work. But as a reply to his post, another tool - recoll was mentioned on Org-mode's mailing list. In this post, I'll give step-by-step instructions to make Recoll work with Emacs.

Building Recoll

I'm assuming that you're on a GNU/Linux system, since it's my impression is that it's the easiest system for building (as in make ...) software. Also, it's the only system that I've got, so it would be hard for me to explain other systems.

If you want to toy around with the graphical back end of Recoll, you can install it with:

sudo apt-get install recoll

Unfortunately, the shell tool recollq isn't bundled with that package, so we need to download the sources. The current version is 1.20.6.

Extract the archive

After downloading the archive, I open ~/Downloads in dired and press & (dired-do-async-shell-command). It guesses from the tar.gz extension that the command should be tar zxvf. By pressing RET, I have the archive extracted to the current directory. I've actually allocated ~/Software/ for installing stuff from tarballs, since I don't want to put too much stuff in ~/Downloads.

Open ansi-term

I navigate to the recoll-1.20.6/ directory using dired, then press ` to open an *ansi-term* buffer for the current directory.

Here's the setup for that (part of my full config):

(defun ora-terminal ()
  "Switch to terminal. Launch if nonexistent."
  (interactive)
  (if (get-buffer "*ansi-term*")
      (switch-to-buffer "*ansi-term*")
    (ansi-term "/bin/bash"))
    (get-buffer-process "*ansi-term*"))

(defun ora-dired-open-term ()
  "Open an `ansi-term' that corresponds to current directory."
  (interactive)
  (let ((current-dir (dired-current-directory)))
    (term-send-string
     (ora-terminal)
     (if (file-remote-p current-dir)
         (let ((v (tramp-dissect-file-name current-dir t)))
           (format "ssh %s@%s\n"
                   (aref v 1) (aref v 2)))
       (format "cd '%s'\n" current-dir)))
    (setq default-directory current-dir)))

(define-key dired-mode-map (kbd "`") 'ora-dired-open-term)

Configure and make

Here's a typical sequence of shell commands.

./configure && make
sudo make install
cd query && make
which recoll
sudo cp recollq /usr/local/bin/

I was a total Linux newbie 5 years ago and had no idea about shell commands. Using only the first two lines, you can build and install a huge amount of software, so these are a great place to start if you want to learn these tools. I actually got by using only those two lines for a year a so.

After the first run or ./configure it turned out that I was missing one library, so I had to do this one and redo the ./configure step.

sudo apt-get install libqt5webkit5-dev

I think this one would work as well:

sudo apt-get build-dep recoll

Configuring Recoll

I only launched the graphical interface to select the indexing directory. It's the home directory by default, I didn't want that so I chose ~/Dropbox/org/ instead. Apparently, there's a way to make the indexing automatic via a cron job; you can even configure it via the graphical interface: it's all good.

Using Recoll from Emacs

Emacs has great options for processing output from a shell command. So first I had to figure out how the shell command should look like. This should be good enough to produce a list of indexed files that contain the word "Haskell":

recollq -b 'haskell'

And there's how to adapt that command to the asynchronous ivy-read interface:

(defun counsel-recoll-function (string &rest _unused)
  "Issue recallq for STRING."
  (if (< (length string) 3)
      (counsel-more-chars 3)
    (counsel--async-command
     (format "recollq -b '%s'" string))
    nil))

(defun counsel-recoll (&optional initial-input)
  "Search for a string in the recoll database.
You'll be given a list of files that match.
Selecting a file will launch `swiper' for that file.
INITIAL-INPUT can be given as the initial minibuffer input."
  (interactive)
  (ivy-read "recoll: " 'counsel-recoll-function
            :initial-input initial-input
            :dynamic-collection t
            :history 'counsel-git-grep-history
            :action (lambda (x)
                      (when (string-match "file://\\(.*\\)\\'" x)
                        (let ((file-name (match-string 1 x)))
                          (find-file file-name)
                          (unless (string-match "pdf$" x)
                            (swiper ivy-text)))))))

The code here is pretty simple:

I don't start a search until at least 3 chars are entered, in order to not get too many results.
I mention :dynamic-collection t which means that recollq should be called after each new letter entered.
In :action, I specify to open the selected file and start a swiper with the current input in that file.

Outro

I hope you found this info useful. It's certainly pretty cool:

cd ~/Dropbox/org && du -hs
# 567M .

So there's half of a gigabyte of stuff, all of it indexed, and I'm getting a file list update after each new key press in Emacs.

If you know of a better tool than recoll (I'm not too happy that match context that it gives via the -A command option), please do share. Also, I've just learned that there's helm-recoll out there, so you can use that if you like Helm.

New Ivy multi-action exit

2015-07-23T00:00:00+02:00

So many Emacs commands and bindings, but little time to learn them all. That's why many-in-one solutions like hydra are often a good deal: you only remember the base binding, and get more info along the way if you get lost.

I've wanted to optimize this approach when it comes to completion as well. In last month's post I described how you can get help / jump to definition / jump to info for the current F1 v (counsel-describe-variable) candidate with C-m / C-. / C-,. While that approach can be viable, it has a few problems. The first problem is that it's not discoverable: you may be using C-m option for ages and not know that C-. and C-, exist. The second problem is that it's not extensible: if you wanted more actions, there are hardly any good bindings left in the minibuffer to bind those actions.

In a more recent post, I described a solution that alleviates both problems. When you press C-o, you see how many actions are available, and you can cycle them with w and s. However, while discoverable, this approach is cumbersome if you already know what you want to do. Especially cycling can't be great when there are a lot of actions.

So today I've added a new approach in addition to the previous one. When you press M-o (ivy-dispatching-done), you get a hint showing you which actions are available. It's like C-m (ivy-done), only allows you to quickly select the action. Conveniently, the default action is bound to o, so M-o o is equivalent to C-m.

Here's how I add one more action to the default one of ivy-switch-buffer:

(ivy-set-actions
 'ivy-switch-buffer
 '(("k"
    (lambda (x)
      (kill-buffer x)
      (ivy--reset-state ivy-last))
    "kill")))

So now:

M-o o will still switch to selected buffer.
M-o k will kill the selected buffer.

If you're familiar with hydra, the format is the same: (key cmd hint). This approach is very extensible: you can add actions and bindings to commands without changing the code of the original command. It's really fast: you're typing just one extra key to select an action. And you'll hardly run out of keys to bind, with 25 lower case keys at your disposal (other bindings work as well, I just think that lower case keys are the fastest to press).

In case you wonder what (ivy--reset-state ivy-last) does, it's used to update the list of buffers, since one of them was deleted. This way, you can delete e.g. 4 buffers with C-x b C-o s gggg, and have the buffer list update after each g.

New functionality in action

Let's look at one package that has a multitude of actions available for each candidate - projectile:

(defvar helm-projectile-projects-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map helm-map)
    (helm-projectile-define-key map
        (kbd "C-d") #'dired
        (kbd "M-g") #'helm-projectile-vc
        (kbd "M-e") #'helm-projectile-switch-to-eshell
        (kbd "C-s") #'helm-find-files-grep
        (kbd "M-c") #'helm-projectile-compile-project
        (kbd "M-t") #'helm-projectile-test-project
        (kbd "M-r") #'helm-projectile-run-project
        (kbd "M-D") #'helm-projectile-remove-known-project)
    map)
  "Mapping for known projectile projects.")

Here's the basic Ivy function for selecting a project:

(defun ivy-switch-project ()
  (interactive)
  (ivy-read
   "Switch to project: "
   (if (projectile-project-p)
       (cons (abbreviate-file-name (projectile-project-root))
             (projectile-relevant-known-projects))
     projectile-known-projects)
   :action #'projectile-switch-project-by-name))
(global-set-key (kbd "C-c m") 'ivy-switch-project)

And now let's add all those actions:

(ivy-set-actions
 'ivy-switch-project
 '(("d" dired "Open Dired in project's directory")
   ("v" helm-projectile-vc "Open project root in vc-dir or magit")
   ("e" helm-projectile-switch-to-eshell "Switch to Eshell")
   ("g"
    (lambda (x)
      (helm-do-grep-1 (list x)))
    "Grep in projects")
   ("c" helm-projectile-compile-project "Compile project")
   ("r" helm-projectile-remove-known-project "Remove project(s)")))

Here's what I get now after pressing M-o:

Looks pretty good, I think. I hope you find the new approach useful. The multi-action exit is currently enabled by default for ivy-switch-buffer, counsel-locate and counsel-rhythmbox, but you can add actions yourself to almost any command that uses ivy-read. In the rare case when ivy-read isn't in the tail position, you can use ivy-quit-and-run inside the added action functions.

Easily arrange hydra into a matrix

2015-07-20T00:00:00+02:00

The new `:columns` option

Today I'll introduce a pretty cool new option that you can use to quickly create hydra docstrings arranged in a matrix. This, of course, was already possible before, but you had to format the matrix by-hand like this (I cite just bit instead of the full code, it was cut to fit into the Jekyll code column restriction):

(defhydra hydra-projectile (:color teal
                            :hint nil)
  "
     PROJECTILE:

     Find File            Search/Tags
-----------------------------------------
_s-f_: file            _a_: ag
 _ff_: file dwim       _g_: update gtags
 _fd_: file curr dir   _o_: multi-occur
 "
  ("s-f" projectile-find-file)
  ("a" projectile-ag)
  ("ff" projectile-find-file-dwim)
  ("fd" projectile-find-file-in-directory)
  ("g" ggtags-update-tags)
  ("o" projectile-multi-occur)
  ("q" nil "cancel"))

The syntax above is still very useful if you want to arrange every detail perfectly or need Ruby-style quoting. But here's the new syntax that allows to get almost the same docstring much easier:

(defhydra hydra-projectile (:color blue
                            :columns 4)
  "Projectile"
  ("a" projectile-ag "ag")
  ("b" projectile-switch-to-buffer "switch to buffer")
  ("c" projectile-invalidate-cache "cache clear")
  ("d" projectile-find-dir "dir")
  ("s-f" projectile-find-file "file")
  ("ff" projectile-find-file-dwim "file dwim")
  ("fd" projectile-find-file-in-directory "file curr dir")
  ("g" ggtags-update-tags "update gtags")
  ("i" projectile-ibuffer "Ibuffer")
  ("K" projectile-kill-buffers "Kill all buffers")
  ("o" projectile-multi-occur "multi-occur")
  ("p" projectile-switch-project "switch")
  ("r" projectile-recentf "recent file")
  ("x" projectile-remove-known-project "remove known")
  ("X" projectile-cleanup-known-projects "cleanup non-existing")
  ("z" projectile-cache-current-file "cache current")
  ("q" nil "cancel"))

It still looks pretty good, in my opinion:

Note how all redundant information has been removed. Another advantage is the you can easily:

Add/remove heads.
Update head hints.
Change the number of columns.

A bit of customization

After each change, just re-eval the defhydra and you're done - no need to manually re-arrange the docstring. Since there already is an interface that allows you to customize the docstring very precisely, I tried to make the new interface as automatic as possible: just specify the number of columns and you're done. But if you want just a little bit more customization, look at this code:

(defvar hydra-key-doc-function 'hydra-key-doc-function-default
  "The function for formatting key-doc pairs.")

(defun hydra-key-doc-function-default (key key-width doc doc-width)
  (format (format "%%%ds: %%%ds" key-width (- -1 doc-width))
          key doc))

So if you want to add a little space here and there, or e.g. wrap key bindings in brackets, just clone hydra-key-doc-function-default, customize it a bit and set hydra-key-doc-function to the new function.

Outro

If you've been using just the plain style before and felt that you can't fit your docstring on one line, try the new style: it's just one line of change with respect to your old code. And if you've been building the docstring by-hand, see if it's possible to transform it to the new style: adding and removing new heads will become easier. Thanks to @Fuco1 for the suggestion in #140.

Quitting to command loop in Elisp

2015-07-16T00:00:00+02:00

Today I'd like to share an interesting bit of Elisp that comes up every now and then for me. Imagine that you have this:

(defun useful-command ()
  (interactive)
  (do-thing-1)
  (do-thing-2 (funcall callback-function))
  (do-thing-3))

Sometimes, when you are in callback-function, you might want to abandon the function that called you, useful-command in this case, and call a different function, with the current context.

Here's what I've come up with to do just that:

(defmacro ivy-quit-and-run (&rest body)
  "Quit the minibuffer and run BODY afterwards."
  `(progn
     (put 'quit 'error-message "")
     (run-at-time nil nil
                  (lambda ()
                    (put 'quit 'error-message "Quit")
                    ,@body))
     (minibuffer-keyboard-quit)))

To break it up into parts:

minibuffer-keyboard-quit will unwind the call stack all the way to the command loop, preventing e.g. do-thing-3 from being called. Note that the call stack can be as deep as you like, e.g. useful-command might be called by utility-command etc.
run-at-time with the argument nil will run the code as soon as possible, which is almost exactly after we're back into the command loop.
The final trick is to prevent Quit from being displayed in the minibuffer.

Sample application

Suppose that I've called find-file when ivy-mode is active. Typically, I'd select a file and press C-m to open it. However, sometimes I just want to see the selected file in dired instead of opening it. This code is from before ivy multi-action interface, it plainly binds a command in ivy-minibuffer-map:

(define-key ivy-minibuffer-map (kbd "C-:") 'ivy-dired)

(defun ivy-dired ()
  (interactive)
  (if ivy--directory
      (ivy-quit-and-run
       (dired ivy--directory)
       (when (re-search-forward
              (regexp-quote
               (substring ivy--current 0 -1)) nil t)
         (goto-char (match-beginning 0))))
    (user-error
     "Not completing files currently")))

So at the moment when C-: is pressed, the call stack is:

C-x C-f called find-file.
find-file called completion-read-function which is set to ivy-completing-read.
ivy-completing-read called ivy-read.
ivy-read called read-from-minibuffer.

Thanks to the new macro, I can unwind all of that stuff, making sure nothing extra will be executed that was supposed to be executed after read-from-minibuffer had returned. In other words, the file will not be opened. Instead, a dired buffer will be opened, centered on the selected candidate.

What I described above can actually be a pretty common scenario, you could adapt it to helm or avy or projectile. Basically to anything that includes some form of completion (i.e. commands that wait for input) and offers you a customizable keymap. Small disclaimer: the above code falls into the quick-and-dirty category, I don't recommend it if you can do something smarter instead. But if you can't do anything smarter due to being constrained by an interface you don't control, this macro could help you out.

Command Rhythmbox from Emacs

2015-07-09T00:00:00+02:00

I might have mentioned before that I'm using GNU/Linux on all of my computers. The particular flavor is Ubuntu, although it shouldn't matter much, since I can count the graphical applications that I use at all, besides Emacs, on one hand. They are: Firefox, Evince, Rhythmbox and VLC. Of course, as most true Emacs-ers, I strive to reduce this number to zero. So I got quite excited when I saw helm-rhythmbox show up in my package list. It works great: you can play and enqueue tracks with completion without leaving Emacs. Big thanks to @mrBliss, and, of course, the authors for dbus.el which makes interaction with D-Bus possible through Elisp.

I'm not as big a fan of Helm as I used to be, so I quickly implemented an Ivy equivalent:

(defun counsel-rhythmbox-enqueue-song (song)
  "Let Rhythmbox enqueue SONG."
  (let ((service "org.gnome.Rhythmbox3")
        (path "/org/gnome/Rhythmbox3/PlayQueue")
        (interface "org.gnome.Rhythmbox3.PlayQueue"))
    (dbus-call-method :session service path interface
                      "AddToQueue" (rhythmbox-song-uri song))))

;;;###autoload
(defun counsel-rhythmbox ()
  "Choose a song from the Rhythmbox library to play or enqueue."
  (interactive)
  (unless (require 'helm-rhythmbox nil t)
    (error "Please install `helm-rhythmbox'"))
  (unless rhythmbox-library
    (rhythmbox-load-library)
    (while (null rhythmbox-library)
      (sit-for 0.1)))
  (ivy-read "Rhythmbox: "
            (helm-rhythmbox-candidates)
            :action
            '(1
              ("Play song" helm-rhythmbox-play-song)
              ("Enqueue song" counsel-rhythmbox-enqueue-song))))

I listed the whole code just to show how easy it is to interact with D-Bus, and also to show-off the shiny new multi-action interface of ivy-read. Besides being discoverable via C-o, the multi-action interface is extensible as well. Here's how to add a "Dequeue" action without touching the original code:

(defun counsel-rhythmbox-dequeue-song (song)
  "Let Rhythmbox dequeue SONG."
  (let ((service "org.gnome.Rhythmbox3")
        (path "/org/gnome/Rhythmbox3/PlayQueue")
        (interface "org.gnome.Rhythmbox3.PlayQueue"))
    (dbus-call-method :session service path interface
                      "RemoveFromQueue" (rhythmbox-song-uri song))))
(ivy-set-actions
 'counsel-rhythmbox
 '(("Dequeue song" counsel-rhythmbox-dequeue-song)))

Very simple, counsel-rhythmbox-dequeue-song is a clone of counsel-rhythmbox-enqueue-song with only the method change from AddToQueue to RemoveFromQueue (I blind-guessed the name, but there should be a reference somewhere). If you got tired of having a whole three actions to choose from, you can revert to the initial two with:

(ivy-set-actions 'counsel-rhythmbox nil)

And here's how the updated C-o option panel now looks like:

A bit of descriptions:

j moves to the next one of the 18 current candidates.
k moves to the previous candidate.
h moves to the first candidate.
l moves to the last candidate.
g calls the current action without exiting.
d calls the current action and exits.
s moves to the next action.
w moves to the previous action.
i and C-o close the options panel without exiting.
o closes the panel and exits.

Similarly to hydra, each action has a short docstring, like "Play song" that should describe what it does. Here are a few usage scenarios:

If I wanted to play the first song and enqueue the third and the sixth and exit the minibuffer, I would press gsjjgjjjd.
If I wanted to play the third and enqueue all the following, I would press jjgsjcjjjjjjjjjjjo. The many j is just me holding j until the selection reaches the end, then I simply exit without doing anything else by pressing o. The way c works is that it toggles the "calling" state - a state where the current action is called whenever a different candidate is selected.

Almost forgot, if this little intro got you excited, the packages that you should install from MELPA are: helm-rhythmbox and counsel.

Pause or resume the current Hydra

2015-07-07T00:00:00+02:00

Today I'd like to highlight a generic command recently added to hydra. It's kind of cute, and maybe something that you didn't even know you wanted. Basically, the hydra-pause-resume command allows to pause and resume the current hydra with one key. And it works for all hydras at once, without any extra configuration. All you have to do is to bind it globally to whatever you like, for example:

(global-set-key (kbd "C-M-k") 'hydra-pause-resume)

What it does:

If a hydra is active, deactivate and push it on the stack.
If no hydra is active, pop one from the stack and call it.
If the stack is empty, call the last hydra.

Personally, I haven't found too much use from the stack - resuming the last one is enough for me. But the stack comes at no extra cost, and might be useful to someone.

If, for example, you have 2 hydras on the stack, how to resume the older one?

The way stacks work, you simply have to go through all elements one by one. So that's:

C-M-k to resume the newer one.
Quit the current one with the appropriate shortcut, only not with C-M-k, since that would just put it back on the stack.
C-M-k to resume the only one remaining on the stack - the older one.

Thanks to @QiangF for the suggestion in #135.

Power up your locate command

2015-07-02T00:00:00+02:00

`locate`

I'm sure many people know that Emacs comes with a locate command. This command, if you're on a Linux system, will find all files on your system that match a particular pattern. The advantage of locate over find when searching the whole system, is that it is much faster, since it uses a pre-computed database. This database is updated periodically, you can force an update with:

sudo updatedb

Of course find is faster if you need to search only a specific directory instead of the whole system, but sometimes you just don't know that directory.

`counsel-locate`

Dynamic

The way locate works it that it asks you for a query, which is glob-based instead of regex-based, and then prints the results to a static buffer.

On the other hand, counsel-locate is dynamic: each time you input a new character a new locate query is ran, and the old one is terminated. On my system, it takes around 2 seconds for a query to complete, so it requires a bit of patience.

Regex-based

I like regex way more than globs for some reason. Here's the command called for the input mp3$:

locate -i --regex mp3$

Of course, the standard ivy-mode method is used to build the regex from a list of space separated words. So the input fleet mp3$ will result in:

locate -i --regex \\(fleet\\).*?\\(mp3$\\)

You could go your own way and update the regex matcher to be ivy--regex-fuzzy, which results in:

locate -i --regex f.*l.*e.*e.*t.* .*m.*p.*3$

But I think less matches is usually better than more matches.

Multi-exit

This is just the coolest feature. Basically, for each file you locate, you can easily:

Open it in Emacs (default).
Open it with xdg-open, so that PDF files are forwarded to evince and MP3 files are forwarded to rhythmbox etc.
Open it in dired.

Here's an example of how to do it. First I call counsel-locate, which I like to bind to C-x l. Then I enter emacs pdf$ and wait around 2 seconds for the 248 results to come up. Then I scroll to the 18th result and press C-o to open up the hydra-based option panel:

The last column (Action) is newer than others. As you can see, it has 3 exit points, which I can scroll with w and s. And currently I'm on the default exit point, which would open the file in Emacs.

For the next screenshot:

I pressed s twice to change the action to dired.
I pressed c to make the current action execute each time a new candidate is selected.

So now, I could just scroll through all my directories on my system that contain PDF files related to Emacs by just holding j.

A similar thing can be done for music tracks:

C-x l dire mp3$ to get the list of all Dire Straits tracks on my system.
C-o s to switch the action from "open in Emacs" to "xdg-open".
From here, I could open one track after another by pressing C-M-n repeatedly. Or I can press c and then j repeatedly.

I've been experimenting with opening EPS and PDF files in quick succession. It's still a work in progress, since I need to use a special wmctrl script to prevent the Emacs window from losing focus each time a new Evince instance is opened.

Outro

You can check out the new feature by installing counsel from MELPA. It will automatically fetch ivy-mode as well. When you enable ivy-mode, besides doing all your completion, it will also remap switch-to-buffer to ivy-switch-buffer. That command also has a multi-exit: pressing C-o sd instead of C-m will kill the selected buffer instead of switching to it. It's a very minor optimization: instead of C-m C-x k you press C-o sd, however you could e.g. use C-o scjjjj to kill five buffers at once.

While the idea of multi-exits is powerful, it's hard to find places to use it efficiently. I think counsel-locate is a nice place for it, although it could work without it:

Find file in Emacs with C-m in the completion interface.
Call dired-jump with C-x C-j.
Type ! and xdg-open RET.
Select and kill the unneeded file with C-x k.

I hope you see now why I prefer C-o sd.

Context aware hydra

2015-06-30T00:00:00+02:00

In this post, I'll demonstrate a snippet that came up this week in a conversation over John Kitchin's post. While the following snippet isn't inherently useful, it might help a creative user to understand Hydra a bit more and accomplish more advanced things.

This hydra demonstrates that the hint and even the key bindings aren't set in stone: you can modify them depending on the current state of your Emacs, in this case the current line number.

(defhydra hydra-vi (:hint nil)
  "vi"
  ("j" next-line)
  ("k" previous-line)
  ("n" next-line)
  ("p" previous-line))

(setq hydra-vi/hint
  '(if (evenp (line-number-at-pos))
    (prog1 (eval
            (hydra--format nil '(nil nil :hint nil)
                           "\neven: _j_ _k_\n" hydra-vi/heads))
      (define-key hydra-vi/keymap "n" nil)
      (define-key hydra-vi/keymap "p" nil)
      (define-key hydra-vi/keymap "j" 'hydra-vi/next-line)
      (define-key hydra-vi/keymap "k" 'hydra-vi/previous-line))
    (prog1 (eval
            (hydra--format nil '(nil nil :hint nil)
                           "\nodd: _n_ _p_\n" hydra-vi/heads))
      (define-key hydra-vi/keymap "j" nil)
      (define-key hydra-vi/keymap "k" nil)
      (define-key hydra-vi/keymap "n" 'hydra-vi/next-line)
      (define-key hydra-vi/keymap "p" 'hydra-vi/previous-line))))

The first statement is one of the most elementary defhydra calls. The only extra thing is that it sets the :hint to nil.

The defhydra statement generates a bunch of function and variable definitions. You can examine them closely by evaluating:

(macroexpand
 '(defhydra hydra-vi (:hint nil)
   "vi"
   ("j" next-line)
   ("k" previous-line)
   ("n" next-line)
   ("p" previous-line)))

Just paste that code into *scratch*, and press C-j. If you want pretty output (153 lines of code instead of 26), turn on lispy-mode and press E instead of C-j.

Anyway, among these defined variables is hydra-vi/hint which is evaluated each time to display the hint. So now we can just redefine hydra-vi/hint to make it so that on even lines n calls next-line, while on odd lines it's j, with the appropriate changes in the doc. The change in bindings, modifying hydra-vi/keymap - also one of the defined variables, needs to be a side-effect, since hydra-vi/hint is expected to evaluate to a string.

Just to give you some idea of how it could be used: you can have a context-aware "open" command that, for instance, delegates to open-in-pdf-tools or open-in-firefox or open-in-emacs when it detects that the point is on a link. And of course all these commands would have their own key binding that works only if the command makes sense.

This approach is described on the wiki, in case you read this post much later and want to see an up-to-date code, or even update it yourself. In case something cool comes out of this snippet, I can try to implement a more palatable API for defhydra, most likely an option to supply a function name in the docstring argument position.

New video demo - counsel-load-theme

2015-06-23T00:00:00+02:00

Without further ado, here's the video link.

The code

(defun counsel--load-theme-action (x)
  "Disable current themes and load theme X."
  (condition-case nil
      (progn
        (mapc #'disable-theme custom-enabled-themes)
        (load-theme (intern x))
        (when (fboundp 'powerline-reset)
          (powerline-reset)))
    (error "Problem loading theme %s" x)))

;;;###autoload
(defun counsel-load-theme ()
  "Forward to `load-theme'.
Usable with `ivy-resume', `ivy-next-line-and-call' and
`ivy-previous-line-and-call'."
  (interactive)
  (ivy-read "Load custom theme: "
            (mapcar 'symbol-name
                    (custom-available-themes))
            :action #'counsel--load-theme-action))

It looks almost trivial, the main idea is to disable all current themes and load the new one. Additionally, try to reset the powerline, since it has to match the mode-line face, which most themes customize.

The Interface

The interface of ivy-read is the same as the built-in completing-read in first two arguments. The difference is that it also accepts a callback through the :action argument. This callback will make the completion engine aware of what needs to be done with the completion result. The presence of the callback allows these completion engine features to work:

ivy-resume will resume the last completion. Very useful if you change your mind on the candidate, or want to examine a related candidate.
ivy-next-line-and-call selects the next matching candidate and executes the callback for it.
ivy-previous-line-and-call selects the previous matching candidate and executes the callback for it.

I like to think of ivy-resume as a DEL or <left> for completion. As you can erase or go back one character with the same DEL binding, regardless of the last character inputted (a or B etc), in the same way you can call the completion again with the same <f6> binding, regardless of the command that required completion (counsel-git-grep or counsel-load-theme or counsel-load-library etc). ivy-resume isn't bound by default, since it needs to be a global binding. I just use this in my config:

(global-set-key [f6] 'ivy-resume)

For the functions that execute the callback while changing the candidate, the idea is:

C-M-n (ivy-next-line-and-call) corresponds to C-n (ivy-next-line),
C-M-p (ivy-previous-line-and-call) corresponds to C-n (ivy-previous-line).

I've also showed off a generic ivy feature: M-j will yank the word at point into the minibuffer. Think of it as the mirror of C-w in isearch. It could not be C-w, since I like C-w being bound to kill-region.

The command/insert mode split

Finally, I show off the equivalent hydra-based modal selection method. So instead of pressing C-M-n C-M-n C-M-n C-M-p C-M-p, you can press the equivalent C-o c jjjkk. Luckily, you don't need to remember a lot of bindings for this hydra mode: just press C-o and read the hints. I'll just list the exit points, since that's usually the more important stuff:

To exit the "command-mode" completely, press o or the standard C-g.
To exit the "command-mode" with the current candidate, press f or d.
To exit the "command-mode" and once again edit the minibuffer, press i.

You might ask why f and d do the same. They actually mirror C-j (ivy-alt-done) and C-m (ivy-done). And if you ask what the difference between those two is, the answer is that ivy-alt-done will not exit the completion when selecting directories during file name completion. It may be possible to extend this to other types of completion where it makes sense to select something but not to exit the minibuffer.

Outro

If you're using ivy-mode, make sure to try the new features: the action-using commands should work for any command that starts with counsel-. For other commands, like package-install, you can only select one candidate with C-m.

Also do try C-M-n with counsel-find-file: you'll be able to cycle through all files in a directory without exiting the completion. Same goes for ivy-switch-buffer, which should probably be renamed to counsel-switch-buffer for consistency.

Debug Clojure with CIDER and lispy

2015-06-22T00:00:00+02:00

To commemorate the release of CIDER 0.9.0, I've just added the ability to debug-step-in Clojure expressions to lispy.

This ability was present for Elisp for a very long time, and it's instrumental to my Elisp output. So now I've added exactly the same thing to Clojure.

How it works

Suppose that you have this function (borrowed from The Joy of Clojure):

(defn l->rfix
  ([a op b]
   (op a b))
  ([a op1 b op2 c]
   (op2 c (op1 a b)))
  ([a op1 b op2 c op3 d]
   (op3 d (op2 c (op1 a b)))))

An important thing is that the function needs to be loaded (probably with cider-load-file), in order for Clojure to know its location. If you only evaluate the function with C-x C-e, it won't work. Actually, the same applies to Elisp.

And then you have the corresponding function call (| is the point, as usual):

|(l->rfix 10 * 2 + 3)

As you press xj (lispy-debug-step-in), the following code is evaluated on the Clojure side:

(do
  (def a 10)
  (def op1 *)
  (def b 2)
  (def op2 +)
  (def c 3))

At the same time, you are taken to the second branch of the body of l->rfix - exactly the one that corresponds to 5 arguments. And that's it: you now have a, op1 etc defined to their proper values. You can now continue within the function body with many possible follow-ups. I'll just list the eval-related ones:

Use e to evaluate expression at point.
If you want to evaluate a symbol, mark it with M-m, end evaluate with e. Actually, I prefer to mark stuff with m and hjkl arrows, using i to mark the first element of the region. It's also possible to mark with a, and 2m, 3m etc.
If you want to bind a symbol in a let binding, mark both the symbol and its value, and press e. If there are many let bindings, you can navigate to the next one with either jj or 2j.
You can debug-step-in again if needed with xj.
You can flatten a function or a macro call with xf.
You can eval-and-insert with E.
You can eval-and-commented-insert with 2e.

Just to add, any of these will work properly and switch to an appropriate body branch:

(l->rfix 1 * 1 + 1)
(l->rfix 2 + 7)
(l->rfix 1 + 2 + 3 + 4)
(l->rfix (str "a" "b" "c") + 7)

Outro

Enjoy the new code, but be mindful that it's really fresh, so it will certainly have some quirks. For instance, function arguments as a map won't work since I haven't programmed for that yet. Big thanks to @bbatsov and all CIDER contributors.

A really cool thing that I hope to get in the future, is to make Z (lispy-edebug-stop) also work in Clojure. What it does currently for Elisp, is to use edebug to setup the function arguments. It may be possible to use @Malabarba's new debugger implementation for the same thing.

The advantages of using lispy-style debugger are the following:

You can navigate your code the way you want, not just in a way that the debugger allows you to.
You can multi-debug, and have sessions last for days.
You can edit the code as you debug. For this new code, I started debugging when there was only a function name. I added the body code expression-by-expression, simultaneously debugging it.

The disadvantage is a bit of namespace pollution, but I think it's more or less acceptable.

avy 0.3.0 is out

2015-06-19T00:00:00+02:00

This is a feature-packed release consisting of 57 commits done over the course of the last month by me and many contributors.

I'm trying something different this time with the release-notes: I've started a Changlelog.org in the repository, which is much more pleasant to read (and write) in org-mode form inside Emacs:

Then I used pandoc to convert the Org file to Markdown. Too bad, the pandoc install-able through apt-get knows nothing of Org mode, so I had to

cabal install pandoc

and let cabal do its thing for like 30 minutes. The exported Markdown wasn't too bad, just had to reformat most things to one line, since Github's fill-column is like 150 chars instead of the usual 80. If someone has more experience of exporting Org to Markdown, please do share: maybe there's a better way to do this.

Anyway, read the release notes either at github or inside Emacs and enjoy the cool new stuff. Big thanks to all contributors.

Also check out the wiki page on customization and other pages. I think it would be cool to have a separate page for e.g. avy-goto-char with the screenshots (or gifs) for all values of avy-style:

pre
post
at
at-full
de-bruijn

So if anyone is willing to contribute (and check out those overlay styles in the process), please go ahead: you can either clone the wiki with:

git clone https://github.com/abo-abo/avy.wiki.git

and push, or just edit it using Github's widgets.

Transform a LISP case into a cond with lispy

2015-06-09T00:00:00+02:00

Just a little extension to the old xc (lispy-to-cond) command that I've added today to lispy:

Previously, xc could only transform a series of nested if into a cond. You can even chain xcxi to transform a case statement into equivalent if statements.

Note also that unwanted whitespace is properly removed. What you see in the picture is actually an ERT test that's being run each time I commit new stuff. It makes sure that starting in the first buffer state and pressing xc really results in the second buffer state. With this test, it's reasonable to believe that xc will actually work the same way in an interactive scenario. Right now, there are 599 of these type of tests in lispy-test.el. To view them like in the screenshot, you can press xv.

Final note, I realize that it should be eql instead of eq, but I like eq more: it's 33% more efficient.

More productive describe-variable

2015-06-08T00:00:00+02:00

I refer to counsel-describe-variable here, which you can get from the MELPA counsel package, or from Github. If you're not familiar, counsel contains specialized functions using ivy-mode completion. Being specialized means that you can do more than usual, for instance here are the exit points of counsel-describe-variable:

RET calls describe-variable: a plain describe-variable with ivy-mode on looks like counsel-describe-variable, but has only this exit point.
C-. calls counsel-find-symbol: jump to symbol declaration.
C-, calls counsel--info-lookup-symbol: jump to symbol reference in *Info*.

These can also be extended by binding new commands in counsel-describe-map.

I'll just describe one useful scenario that happened just now. I was working on a checkdoc.el change and was testing it with avy.el. And I got a few style warnings for this code, which I got from a contributor (thanks for the code btw):

(defvar avy-translate-char-function #'identity
  "Function to translate user input key. This can be useful for
adding mirror key. E.g. one can make SPACE an alternative of 'a',
by adding:

\(setq avy-translate-char-function
      (lambda (c) (if (= c 32) ?a c)))

to allow typing SPACE instead of character 'a' to jump to the location
highlighted by 'a'.")

One of the warnings that avy-translate-char-function should be quoted while inside the docstring like so:

"`avy-translate-char-function'"

Of course that wouldn't play well with setq, so I wanted to see if any other variables that end in -function provide an example of use like here, and, if so, how they quote.

This is my personal configuration:

(global-set-key (kbd "<f1> v") 'counsel-describe-variable)

So I did <f1> v function$ to describe a variable that ends with function. Here, $ is a part of a regular expression, which should be a priority to learn if you want to be a (not just) Emacs Power User.

And now the key part: instead of pressing RET to describe just the current candidate, I repeatedly press C-M-n (ivy-next-line-and-call). After each C-M-n, the next candidate will be selected and the *Help* window will be updated.

With this trick I was able to skim through the 346 matches in seconds. The conclusion was that an example isn't usually provided, with nnmail-expiry-wait-function being an exemption. In the end, I decided not to provide such an explicit example and shorten the doc to this:

(defvar avy-translate-char-function #'identity
  "Function to translate user input key into another key.
For example, to make SPC do the same as ?a, use
\(lambda (c) (if (= c 32) ?a c)).")

counsel-git-grep, in async

2015-06-04T00:00:00+02:00

Introduction

It took me quite a while to figure out, but finally counsel-git-grep, which I've described before works completely asynchronously, which means it's very fast and smooth even for huge repositories.

If you don't know what git grep is: it allows you to search for a regular expression in your Git repository. In a way, it's just a find / grep combo, but very concise and fast. It's particularly great for finding all uses and references to a symbol.

It can be useful even for non-programmers. One great application is to stick all your org-mode files into a Git repository. Then you can search all your files at once very fast: all my org stuff takes more than 1000,000 lines and there's no lag while searching. I really should remove some pdfs from the repository at some point.

The Video Demo

Check out the speed and the various command in this Video Demo. Each key stroke starts two asynchronous shell calls, while canceling the current ones if they are still running. Here are the example calls:

$ git --no-pager grep --full-name -n --no-color \
    -i -e "forward-line 1" | head -n 200
$ git grep -i -c 'forward-line 1' \
    | sed 's/.*:\\(.*\\)/\\1/g' \
    | awk '{s+=$1} END {print s}'

The Elisp side

I figure since I was interested in this topic, probably a few more people are as well. So I'll explain below how async processing is done (in this case):

(defun counsel--gg-count (regex &optional no-async)
  "Quickly count the amount of git grep REGEX matches.
When NO-ASYNC is non-nil, do it synchronously."
  (let ((default-directory counsel--git-grep-dir)
        (cmd (concat (format "git grep -i -c '%s'"
                             regex)
                     " | sed 's/.*:\\(.*\\)/\\1/g'"
                     " | awk '{s+=$1} END {print s}'"))
        (counsel-ggc-process " *counsel-gg-count*"))
    (if no-async
        (string-to-number (shell-command-to-string cmd))
      (let ((proc (get-process counsel-ggc-process))
            (buff (get-buffer counsel-ggc-process)))
        (when proc
          (delete-process proc))
        (when buff
          (kill-buffer buff))
        (setq proc (start-process-shell-command
                    counsel-ggc-process
                    counsel-ggc-process
                    cmd))
        (set-process-sentinel
         proc
         #'(lambda (process event)
             (when (string= event "finished\n")
               (with-current-buffer
                   (process-buffer process)
                 (setq ivy--full-length
                       (string-to-number
                        (buffer-string))))
               (ivy--insert-minibuffer
                (ivy--format ivy--all-candidates)))))))))

Since we're calling a shell command, it's important to set default-directory to a proper value: the shell command will be run there.
The output from the process will be channeled into a buffer. I start the buffer name with a space to make it hidden: it will not be shown in the buffer list and switch-to-buffer completion.
I leave the sync option and use shell-command-to-string for that. Sometimes it's necessary to know the amount of candidates without a delay.
If get-process and get-buffer return something it means that the shell command is still running from the previous input. But the input has changed and that data has become useless, so I kill both the process and the buffer.
Then I start a new process with start-process-shell-command- a convenience wrapper around the basic start-process that's useful for passing a full shell command with arguments.
Finally, I let counsel--gg-count return without waiting for git grep to finish. But something needs to be done when it finishes, so I use set-process-sentinel. Emacs will call my lambda when there's a new event from the process.

Outro

To check out the new stuff, just install or upgrade counsel from MELPA. Or clone the source. I hope that my Elisp explanations were useful, async stuff is awesome, and I hope to see more of it in future Emacs packages.

lispy 0.26.0 is out

2015-05-29T00:00:00+02:00

Lispy 0.25.0 came out 2 months ago; 177 commits later, comes version 0.26.0. The release notes are stored at Github, and I'll post them here as well.

The coolest changes are the new reader-based M, which:

Gives out very pretty output, with minor diffs for actual code, which is quite impressive considering all newline information is discarded and then reconstructed.
Works for things that Elisp can't read, like #<marker ...> etc, very useful for debugging.
Customizable rule sets; rules for Elisp and Clojure come with the package.

The improvements to g and G also great:

Because of caching, the prettified tags can be displayed in less than 0.15s on Emacs' lisp/ directory, which has 21256 tags in 252 files.
The tags collector looks at file modification time, so you get the updated tags right after you save.

The details for these and other features follow below.

Fixes

C-k should delete the whole multi-line string.
y should work for all parens, not just (.
p should actually eval in other window for dolist.
Prevent pairs inserting an extra space when at minibuffer start.
ol works properly for active region.

New Features

Misc

xf will pretty-print the macros for Elisp.
M-m works better when before ).
Fix ', ^ after a ,.
Improve / (splice) for quoted regions.
Z works with &key arguments.
The new M is used in xf.
Allow to flatten Elisp defsubst.
c should insert an extra newline for top-level sexps.

Paredit key bindings

You can have only Paredit + special key bindings by using this composition of key themes:

(lispy-set-key-theme '(special paredit))

The default setting is:

(lispy-set-key-theme '(special lispy c-digits))

New algorithm for multi-lining

M is now bound to lispy-alt-multiline instead of lispy-multiline. It has a much better and more customizable algorithm.

See these variables for customization:

lispy-multiline-threshold
lispy--multiline-take-3
lispy--multiline-take-3-arg
lispy--multiline-take-2
lispy--multiline-take-2-arg

They are set to reasonable defaults. But you can customize them if you feel that a particular form should be multi-lined in a different way.

lispy-multiline-threshold is a bit of ad-hoc to make things nice. Set this to nil if you want a completely rigorous multi-line. With the default setting of 32, expressions shorter than this won't be multi-lined. This makes 95% of the code look really good.

The algorithm has a safety check implemented for Elisp: if read on the transformed expression returns something different than read on the original expression, an error will be signaled and no change will be made. For expressions that can't be read, like buffers/markers/windows/cyclic lists/overlays, only a warning will be issued (lispy can read them, unlike read).

`d` and `>` give priority to `lispy-right`

For the expression (a)|(b), (a) will be considered the sexp at point, instead of (b). This is consistent with show-paren-mode. If a space is present, all ambiguities are resolved anyway.

`b` works fine even if the buffer changes

I've switched the point and mark history to markers instead of points. When the buffer is changed, the markers are updated, so b will work fine.

Extend Clojure reader

In order for i (prettify code) to work for Clojure, it must be able to read the current expression. I've been extending the Elisp reader to understand Clojure. In the past commits, support was added for:

empty sets
commas
auto-symbols, like p1__7041#

Extend Elisp reader

It should be possible to read any #<...> form, as well as #1-type forms.

`g` and `G` get a persistent action for `ivy`

This is a powerful feature that the helm back end has had for a long time. When you press g, C-n and C-p will change the current selection. But C-M-n and C-M-p will change the current selection and move there, without exiting the completion.

This also means that you can call ivy-resume to resume either g (lispy-goto) or G (lispy-goto-local).

`e` works with `defvar-local`

As you might know, the regular C-x C-e or eval-buffer will not reset the values of defvar, defcustom and such (you need C-M-x instead). But e does it, now also for defvar-local.

Improve faces for dark backgrounds

I normally use a light background, so I didn't notice before that the faces looked horrible with a dark background.

The ` will quote the region

If you have a region selected, pressing ` will result in:

`symbol'

Customize the file selection back end for `V`

V (lispy-visit) allows to open a file in current project. Previously, it used projectile. Now it uses find-file-in-project by default, with the option to customize to projectile.

Fixup calls to `looking-back`

Apparently, looking-back isn't very efficient, so it's preferable to avoid it or at least add a search bound to improve efficiency. Also the bound became mandatory in 25, while it was optional before.

`M-m` will work better in strings and comments.

See the relevant test:

(should (string= (lispy-with "\"See `plu|mage'.\"" (kbd "M-m"))
                 "\"See ~`plumage'|.\""))

Thanks to this, to e.g. get the value of a quoted var in a docstring or a comment, or jump to its definition, you can M-m. Then, you can step-in with i to select the symbol without quotes.

Update the tags strategy

A much better algorithm with caching an examining of file modification time is used now. This means that the tags should be up-to-date 99% of the time, even immediately after a save, and no necessary re-parsing will be done. And it all works fine with the lispy-tag-arity modifications.

1% of the time, lispy-tag-arity stops working, I don't know why, since it's hard to reproduce. You can then pass a prefix arg to refresh tags bypassing the cache, e.g 2g or 2G.

Also a bug is fixed in Clojure tag navigation, where the tag start positions were off by one char.

The fetched tags retrieval is fast: less than 0.15s on Emacs' lisp/ directory to retrieve 21256 tags from 252 files. Which means it's lightning fast on smaller code bases (lispy has only 651 tags).

`xj` can also step into macros

lispy-debug-step-in, bound to xj locally and C-x C-j globally can now step into macros, as well as into functions. This command is very useful for Edebug-less debugging. Stepping into macros with &rest parameters should work fine as well.

`p` can now lax-eval function and macro arguments

When positioned at function or macro args, p will set them as if the function or macro was called with empty args, or the appropriate amount of nils. If the function is interned and interactive, use its interactive form to set the arguments appropriately.

Again, this is very useful for debugging.

Allow to paste anywhere in the list using a numeric arg

As you might know, P (lispy-paste) is a powerful command that:

Replaces selection with current kill when the region is active.
Yanks the current kill before or after the current list otherwise.

Now, you can:

Yank the current kill to become the second element of the list with 2P
Yank the current kill to become the third element of the list with 3P
...

It's OK to pass a larger arg than the length of the current list. In that case, the paste will be made into the last element of the list.

Update the way `/` (`lispy-splice`) works

When there's no next element within parent, jump to parent from appropriate side. When the region is active, don't deactivate it. When splicing region, remove random quotes at region bounds.

This change makes the splice a lot more manageable. For example, starting with this Clojure code, with | marking the current point:

(defn read-resource
  "Read a resource into a string"
  [path]
  (read-string
   |(slurp (clojure.java.io/resource path))))

A double splice // will result in:

(defn read-resource
  "Read a resource into a string"
  [path]
  |(read-string
   slurp clojure.java.io/resource path))

After xR (reverse list), 2 SPC (same as C-f), -> (plain insert), [M (back to parent and multi-line), the final result:

(defn read-resource
  "Read a resource into a string"
  [path]
  |(-> path
      clojure.java.io/resource
      slurp
      read-string))

This also shows off xR - lispy-reverse, which reverses the current list. Finally, reverting from the last code to the initial one can be done simply with xf - it will flatten the -> macro call.

Outro

Thanks to all who contributed, enjoy the new stuff. Would also be nice to get some more feedback and bug reports. Currently, it might seem that a large part of the features are either perfect or unused.

Ivy-mode 0.5.0 is out

2015-05-23T00:00:00+02:00

At this point, swiper is only a fraction of ivy-mode's functionality. Still, it's nice to keep them all, together with counsel, in a single repository: counsel-git-grep works much better this way.

Anyway, I'll echo the release notes here, there are quite a few exciting new features.

Fixes

TAB shouldn't delete input when there's no candidate.
TAB should switch directories properly.
require dired when completing file names, so that the directory face is loaded.
TAB should work with confirm-nonexistent-file-or-buffer.
TAB should handle empty input.
work around grep-read-files: it should be possible to simply M-x rgrep RET RET RET.
Fix the transition from a bad regex to a good one - you can input a bad regex to get 0 candidates, the candidates come back once the regex is fixed.
ivy-switch-buffer should pre-select other-buffer just like switch-buffer does it.
Fix selecting "C:\" on Windows.
counsel-git-grep should warn if not in a repository.
C-M-n shouldn't try to call action if there isn't one.
Turn on sorting for counsel-info-lookup-symbol.
ivy-read should check for an outdated cons initial-input.

New Features

Out of order matching

I actually like in-order matching, meaning the input "in ma" will match "in-order matching", but not "made in". But the users can switch to out-of-order matching if they use this code:

(setq ivy-re-builders-alist
          '((t . ivy--regex-ignore-order)))

ivy-re-builders-alist is the flexible way to customize the regex builders per-collection. Using t here, means to use this regex builder for everything. You could choose to have in-order for files, and out-of-order for buffers and so on.

New defcustom: `ivy-tab-space`

Use this to have a space inserted each time you press TAB:

(setq ivy-tab-space t)

ignore case for TAB

"pub" can expand to "Public License".

New command: `counsel-load-library`

This command is much better than the standard load-libary that it upgrades. It applies a sort of uniquify effect to all your libraries, which is very useful:

In this case, I have avy installed both from the package manager and manually. I can easily distinguish them.

Another cool feature is that instead of using find-library (which is also bad, since it would report two versions of avy with the same name and no way to distinguish them), you can simply use counsel-load-library and type C-. instead of RET to finalize.

Here's another scenario: first load the library, then call ivy-resume and immediately open the library file.

New command: `ivy-partial`

Does a partial complete without exiting. Use this code to replace ivy-partial-or-done with this command:

(define-key ivy-minibuffer-map (kbd "TAB") 'ivy-partial)

Allow to use `^` in `swiper`

In regex terms, ^ is the beginning of line. You can now use this in swiper to filter your matches.

New command: `swiper-avy`

This command is crazy good: it combines the best features of swiper (all buffer an once, flexible input length) and avy (quickly select one candidate once you've narrowed to about 10-20 candidates).

For instance, I can enter "to" into swiper to get around 10 matches. Instead of using C-n a bunch of times to select the one of 10 that I want, I just press C-', followed by a or s or d ... to select one of the matches visible on screen.

So both packages use their best feature to cover up the others worst drawback.

Add support for virtual buffers

I was never a fan of recentf until now. The virtual buffers feature works in the same way as ido-use-virtual-buffers: when you call ivy-switch-buffer, your recently visited files as well as all your bookmarks are appended to the end of the buffer list.

Suppose you killed a buffer and want to bring it back: now you do it as if you didn't kill the buffer and instead buried it. The bookmarks access is also nice.

Here's how to configure it, along with some customization of recentf:

(setq ivy-use-virtual-buffers t)

(use-package recentf
  :config
  (setq recentf-exclude
        '("COMMIT_MSG" "COMMIT_EDITMSG" "github.*txt$"
          ".*png$"))
  (setq recentf-max-saved-items 60))

Add a few wrapper commands for the minibuffer

All these commands just forward to their built-in counterparts, only trying not to exit the first line of the minibuffer.

M-DEL calls ivy-backward-kill-word
C-d calls ivy-delete-char
M-d calls ivy-kill-word
C-f calls ivy-forward-char

Allow to customize the minibuffer formatter

See the wiki on how to customize the minibuffer display to look like this:

100 Find file: ~/
  file1
  file2
> file3
  file4

When completing file names, `TAB` should defer to `minibuffer-complete`

Thanks to this, you can TAB-complete your ssh hosts, e.g.:

/ss TAB -> /ssh
/ssh:ol TAB -> /ssh:oleh@

More commands work with `ivy-resume`

I've added:

counsel-git-grep
counsel-git

Others (that start with counsel-) should work fine as well. Also don't forget that you can use C-M-n and C-M-p to:

switch candidate
call the action for the candidate
stay in the minibuffer

This is especially powerful for counsel-git-grep: you can easily check the whole repository for something with just typing in the query and holding C-M-n. The matches will be highlighted swiper-style, of course.

Allow to recenter during `counsel-git-grep`

Use C-l to recenter.

Update the quoting of spaces

Split only on single spaces, from all other space groups, remove one space.

As you might know, a space is used in place of .* in ivy. In case you want an actual space, you can now quote them even easier.

Outro

Thanks to all who contributed, check out the new stuff, and make sure to bind ivy-resume to something short: it has become a really nice feature.

New on MELPA - define word at point

2015-05-22T00:00:00+02:00

Doing things in Emacs is superlatively better than having to switch to another application.

In this case, "doing things" is getting the dictionary definition of word at point, and "superlatively" is a word that I didn't know - a straw that broke the camel's back and caused me to finally automate the process of getting the definition of a word that I encounter in an Emacs buffer.

The whole process of writing the define-word package took around 30 minutes, I just had to:

See which engine DuckDuckGo uses.
Follow to wordnik.
Try to get an API key, read their draconian TOS and decide that I don't want to agree to it just to get their key.
Examine the HTML that it returns and note that it's quite regular.
Write a 10 line function with re-search-forward to extract the word definitions from a sample page that I saved with wget.

Then just wrap the function in an url-retrieve and done. It's a good thing that I learned to use url-retrieve when I wrote org-download.

Here's how it looks like in action, the word under point is "Authors" and instead of visiting this page, you can see it right away in your Echo Area:

The result is displayed simply with message, so it doesn't mess with your window config. You read it, press any key and the Echo Area popup will vanish automatically.

Install the package from MELPA or check it out at github. You just need to decide where to bind it:

(global-set-key (kbd "C-c d") 'define-word-at-point)
(global-set-key (kbd "C-c D") 'define-word)

At less than 50 lines, the source is very easy to understand. So if you're looking to write some Elisp that retrieves and parses some HTML from a web service, it's nice to look at a simple implementation of how it's done.

New in Emacs - run checkdoc in batch mode

2015-05-19T00:00:00+02:00

More `checkdoc` goodness

If you're doing some Elisp coding, you should definitely check out the built-in checkdoc command. Too bad it's (was) interactive-only. With a small modification, I've made it suitable for batch.

You can check out how I did it in the avy (or lispy) repository. Here's my compile target in the Makefile:

emacs ?= emacs

compile:
    $(emacs) -batch -l targets/avy-init.el

And here are the contents of avy-init.el:

(add-to-list 'load-path default-directory)
(mapc #'byte-compile-file '("avy.el"))
(require 'avy)
(require 'checkdoc)
(with-current-buffer (find-file "avy.el")
  (checkdoc-current-buffer t))

I made compile target a dependency of the all target, so with a single make I can:

run the tests
check for compiler warnings
check for checkdoc style warnings

`compile` over `ansi-term`

There's no reason to use ansi-term (or an external shell) over compile in this case. Using M-x compile (or actually M-x helm-make) I can navigate to any compilation or style warning or failed test from the *compilation* buffer.

For the lazy, it's possible to jump to errors with a mouse, but navigating errors is a breeze with this Hydra:

(defhydra hydra-error (global-map "M-g")
  "goto-error"
  ("h" first-error "first")
  ("j" next-error "next")
  ("k" previous-error "prev")
  ("v" recenter-top-bottom "recenter")
  ("q" nil "quit"))

There is also ace-link-compilation, but I tend not to use it often.

I make good use of one of the coolest compilation-mode features: pressing g will restart the compilation process.

Outro

Check out the new feature, I think it's really cool. Another incentive to try is that lately the emacs trunk has been extremely stable: I'm on Emacs25 almost all the time now, since it feels a lot faster.

Here are my aliasing settings:

$ which newemacs
/usr/local/bin/newemacs
$ readlink -f `which newemacs`
/home/oleh/git/gnu-emacs/src/emacs

To run the tests with newemacs instead of emacs (since that's the one for which checkdoc works in batch), use M-x setenv -> emacs -> newemacs.

Free avy with your goto-line

2015-05-17T00:00:00+02:00

I have a fondness for Emacs commands and key bindings that you can get for free. Here, by "free" I mean customizations that don't require you to change your old workflow (i.e. unbind your old bindings), but still get the new workflow with comfortable bindings.

For free (almost physical) keys, see my post on xmodmap.
See the last post to see how you can get window manipulation commands "for free" when you call ace-window.
With hydra, you can define lightweight minor modes for almost free or even completely free key bindings.
With lispy, you get list manipulation bindings (single letters, no less) for free when your point is positioned at a list boundary, or when the region is active.
With worf, you get heading navigation and manipulation bindings, also single-letter, when your point is at a heading or markup start.

Today, I describe a recent addition to avy: when you call avy-goto-line and decide that you don't want to use avy-keys to select a line on screen, and you want to select a line by number, you can just enter that number.

avy-goto-line will recognize that you entered a digit, and forward to goto-line with that digit already pre-entered. So basically there's no disadvantage to doing this:

(global-set-key (kbd "M-g g") 'avy-goto-line)

Even if you use the avy method zero times, you lose no efficiency when compared with regular goto-line, you just get a pretty light-show with each call:

You can customize a lot of things in avy, for instance the keys or the way the overlays are displayed. See the new wiki page on customization for more info.

ace-window 0.9.0 is out

2015-05-13T00:00:00+02:00

I kind of forgot to tag the 0.8.0 release on Github, so it's been a whole 3 months since the last release. In this post, I'll only describe the newest exciting feature in more detail, see the archive for older posts on ace window.

New Features

Display the window decision chars in the mode line

Enable ace-window-display-mode for this. This gives you the advantage of always being aware which window corresponds to which char.

New defcustom: `aw-ignore-current`

This is off by default. When t, ace-window will ignore selected-window.

Allow to switch the window action midway

Ace-window has many commands available, like:

ace-select-window
ace-delete-window
ace-swap-window
...

But did you wish sometimes when you called ace-select-window that you should have called ace-delete-window? In the old way, you would cancel ace-select-window with C-g and call ace-delete-window.

With the new way, you can, just press x followed by the decision char. All keys are customizable through aw-dispatch-alist.

(defvar aw-dispatch-alist
  '((?x aw-delete-window " Ace - Delete Window")
    (?m aw-swap-window " Ace - Swap Window")
    (?n aw-flip-window)
    (?v aw-split-window-vert " Ace - Split Vert Window")
    (?b aw-split-window-horz " Ace - Split Horz Window")
    (?i delete-other-windows " Ace - Maximize Window")
    (?o delete-other-windows))
  "List of actions for `aw-dispatch-default'.")

The strings beside each command are important: they are used to update the mode line when you press a char. They also mean that a window should be selected using aw-keys for the corresponding command. If there's no string, the command is just called straight away, with no arguments. To reiterate, for each entry without a string, its command will be called immediately, and for others the window will be selected first.

Also, take note of aw-flip-window. Suppose the you have a lot (say 7) windows, but you only want to cycle between the most recent two. You can do so with n, with no need to press the decision char.

I call this feature "the dispatch". The dispatch normally happens when:

you're prompted for aw-keys
you press a char that isn't in aw-keys
there's an entry in aw-dispatch-alist for this char

If you want to skip step 1 always (since, by default, you're not prompted for aw-keys when you have 2 or less windows), use:

(setq aw-dispatch-always t)

Be careful though, setting this means that you'll always have to select a window with aw-keys, even if there are only two. This is a large toll on the muscle memory. On the other hand, even with one window, assuming you've bound ace-window to M-p, you get:

split-window-vertically on M-p v
split-window-horizontally on M-p b
delete-other-windows on M-p o

What's also nice is that these commands scale with the amount of windows: if you have only one window, you get no prompt for M-p v, so it acts just like C-x 2. But if you have more windows, you don't have to select the window that you want to split beforehand: you can select it after you decided to issue a split operation.

See the wiki for a nice customization setup by @joedicastro.

Outro

Give the new feature a try. The jump in utility between the new and old ace-window, I feel, is of the same magnitude as the jump between other-window and ace-window. However, it doesn't come for free and the muscle memory needs to be readjusted slightly.

Big thanks to all who contributed, especially to @joedicastro.

New on MELPA - avy

2015-05-08T00:00:00+02:00

This package contains the library on which ace-window and ace-link now depend, as well as a multitude of navigation commands.

Intro

Yes, they used to depend on ace-jump-mode, hence the ace in their names, but as I added features to my packages over time, it became harder to compose features because of ace-jump-mode inflexibility.

Don't get me wrong, ace-jump-mode is a fine standalone package, and if you're using it only for jumping to chars, there are few reasons for you to make the switch. However, if you're interested in the new and juicy features, such as:

jumping to word starts
jumping to sub-word starts
jumping to line beginnings or endings
copying and moving lines

with most of the features coming in -0, -1, or -2 flavor, or if you're interested in building an ace-jump-mode-based package, then you should consider avy.

The leading chars flavor

All of the commands provided are about jumping to visible characters, and possibly doing some stuff. Since usually there are a lot of these visible characters, it's advantageous to first narrow them somewhat. So each command can be divided into two phases: the narrowing phase and the decision phase.

There are 3 variations of the narrowing phase:

The -0 flavor, e.g. avy-goto-word-0 or avy-goto-line doesn't narrow at all. The advantage that there's minimum context switching (no narrowing phase, only decision phase). The disadvantage is that the number of candidates in the decision phase can be quite large.
The -1 flavor, e.g. avy-goto-word-1 or avy-goto-char narrows by the first character of the thing. The disadvantage is the context switch: first you call the command, then you switch context to scan and input the leading char, then you switch context to scan and input the decision chars. The advantage is less candidates in the decision phase.
The -2 flavor is my favorite avy-goto-char-2: it reads two consecutive chars, instead of just one. This doesn't impact the narrowing phase too much, since inputting two consecutive chars isn't much more than just one. But it greatly decreases the number of candidates in the decision phase. The small amount of candidates allows me to use this setting for the decision:

(setq avy-keys '(?a ?s ?d ?f ?g ?h ?j ?k ?l))

That's only 9 decision chars, all of them on the home row.

The decision char overlay flavors

Once again, there are three, here are their corresponding defcustoms:

(defcustom avy-goto-char-style 'pre
  "Method of displaying the overlays for `avy-goto-char' and `avy-goto-char-2'."
  :type '(choice
          (const :tag "Pre" pre)
          (const :tag "At" at)
          (const :tag "Post" post)))

(defcustom avy-goto-word-style 'pre
  "Method of displaying the overlays for `avy-goto-word-0' and `avy-goto-word-0'."
  :type '(choice
          (const :tag "Pre" pre)
          (const :tag "At" at)
          (const :tag "Post" post)))

If you're used to ace-jump-mode, the corresponding style is at, which displays the overlay at the target position, one character at a time. I don't like this style most of the time, I prefer pre which is more similar to vim-easymotion: it will display the full char path at once, before the target position. This results in less feedback and more efficiency, in my opinion.

Outro

Give the new package a try, it's already been pretty active the last few days, with bugs being fixed and new features appearing, thanks to all who contributed.

If you want to see some screenshots, there are plenty at the repository page, and also in an earlier post.

Finally, the package in on MELPA, so it's convenient to install. The only hassle is to decide where to bind all these commands.

Ivy-mode 0.4.0 is out

2015-05-02T00:00:00+02:00

This is a feature-packed release with a lot of cool things like:

Partial completion on TAB
Resume the last completion session with ivy-resume
Multi-tier regex matching

The detailed release notes follow.

Fixes

Glob expansion in `rgrep`

While completing file names, ivy expands the file name to full. Unfortunately, rgrep uses read-file-name-internal and isn't receptive to globs being expanded with the current directory. A work-around this is to use the generic strategy when ivy is in trouble:

enter the input text as if there was no completion.
exit with C-u C-j (forwards to ivy-immediate-done).

ivy-immediate-done is currently unbound by default. If you want, you can bind it in your config like this:

(define-key ivy-minibuffer-map (kbd "C-c C-d") 'ivy-immediate-done)

Exclude a couple more modes from font-lock

This time, they are jabber-chat-mode and elfeed-search-mode.

Fix a flag in `swiper-query-replace`

You can launch a query replace with M-q from swiper.

Avoid sorting `org-refile` candidates

By default, ivy completion candidates are sorted with string-lessp. The sorting can be customized with ivy-sort-functions-alist. While refiling, the natural order is actually best, so the sorting is turned off in that case.

Reset to the first candidate when switching directories

With ivy-mode you can select a file anywhere on your file system by switching directories repeatedly with C-j (ivy-alt-done). After moving to a new directory, the point should be on the first candidate.

Fixup the face order

All this time there was an issue with the face order swapping between 1 and 2 groups. This is now fixed. Also, I've made swiper-match-face-4 inherit from isearch-fail. It's important to have all 4 faces be different.

Don't error on bad regex

When the current input is a bad regex, just display no candidates and continue. Don't throw an error.

New Features

Use `//` instead of `/` to move to root

While completing file names, you can enter // to move to the root directory. This change was necessary in order to make it possible to enter e.g. /sudo: or /ssh:.

Host completion for `/sudo:` and `/ssh:`

This feature is a bit flaky for now. But it works well on my machine. It should get better after a few bug reports. You can start the completion right after the method, e.g. /ssh: RET, or after method+user, e.g. /ssh:oleh@ RET.

Respect `confirm-nonexistent-file-or-buffer`

If you set confirm-nonexistent-file-or-buffer to t (it's nil by default), you'll have to confirm when you create a new file or buffer with ivy.

Highlight remote buffers with `ivy-remote` face

Just some extra polish to make things look nicer. The buffers to which you're connected through TRAMP will be highlighted with the new ivy-remote face.

Change the prompt for `match-required` interactions

Sometimes, the Emacs functions that call completion specify to it that a match is required, i.e. you can't just type in some random stuff - you have to select one of the candidates given to you. In that case ivy will appropriately change the prompt like this:

Improve the candidate selection while using history

While completing, you press M-p to select the previous input. This update tries to select not just the first candidates that matches, but the actual previous candidate that you selected before.

Use alpha compositing to add `ivy-current-match-face`

This is only relevant for when the completion candidates have custom face backgrounds. But in that case, the minibuffer looks a lot nicer.

Add partial completion

Press TAB to do call ivy-partial-or-done to complete the current thing to the largest possible prefix. When called twice in a row, it's the same as C-j, i.e. it will finish the completion.

Improve completion of hidden buffers

In Emacs, hidden buffer names start with a space. To see them all, press a single space while completing buffers in ivy-mode. You can toggle between hidden and non-hidden buffers by editing the first space in your input query. Remember that with ivy-mode the minibuffer is a proper editable area, so C-a works properly (unlike in isearch or ido-mode).

Allow to quote spaces while matching

Spaces are wild while matching - they serve as group boundaries. However, sometimes it would be useful to quote them. From now on, you can quote N consecutive spaces by inputting N+1 consecutive spaces.

Add multi-tier regex matching

This is actually a really cool feature, so if you're paying attention to any section, let it be this one.

User side

For example, I cloned boost-1.58.0 and called counsel-git, which is like a find-file for all files in a git repository at once.

Initially, it gives 45919 candidate files.
With input "utility", there are 234 candidates.
With input "utility hpp", there are 139 candidates.

Now, the interesting part. If I want to exclude anything with "hpp" in it, I change the input to "utility !hpp" (with M-b !) to get 95 candidates (95=234-139, it checks out). I could exclude some more:

with input "utility !hpp cpp" there are 57 candidates.
with input "utility !hpp cpp ipp" there are 46 candidates.
I can unify the regex to "utility ![hic]pp" and also get 46 candidates.
exclude htm with "utility ![hic]pp htm" to get only 17 candidates.

You can use this strategy anywhere, not just for git file. For example, in describe-function or swiper.

Elisp side

You can customize ivy-re-builders-alist to make ivy-mode complete in the way that you like. The alist dispatches on the collection type, so you can have one completion strategy for buffers, another for files and still another for everything else.

Each function on the alist should turn the string input into a string regex. So the simplest one would be regexp-quote. If you want to use multi-tier matching, the function should instead return a list of regexps of two types:

the ones that should match (will be joined by and).
the ones that should not match (will be joined by or).

Add `ivy-resume`

This feature is still a bit of a work-in-progress. But it allows you to resume the last completion to the point before you entered RET or C-g etc. It only works for features that specifically passed :action to ivy-read. You could resume other features, but nothing would be done when you select the candidate, since ivy-completing-read has no idea what the function that called it was going to do with the result.

Currently, you can resume:

counsel-describe-variable
counsel-describe-function
lispy-goto
swiper

Here's how I've bound it in my config:

(global-set-key (kbd "C-c C-r") 'ivy-resume)
(global-set-key [f6] 'ivy-resume)

The ivy-resume feature adds occur-like functionality to swiper. Calling ivy-resume is like switching to the *Occur* buffer.

Outro

Big thanks to all who contributed, especially @tsdh and @zhaojiangbin.

If you're considering to switch from ido-mode to ivy-mode, now is a good time, since the most glaring gaps have now been filled. You can find some up-to-date info on the swiper wiki. I switched the page syntax from markdown to org-mode, but Github makes the headings way to big. So it might be easier to clone the wiki and view the org files in Emacs:

git clone https://github.com/abo-abo/swiper.wiki.git

GCC macros and auto-yasnippet

2015-04-30T00:00:00+02:00

As one thing leads to another, it occurred to me that I didn't know what __GNUC__ macro does. Which brought me to the manual page on Common Predefined Macros.

Using `org-mode` Babel to check the macro values

I decided that just skimming through the page wasn't enough, and I wanted to brush up on my org-mode babel. So I created this wiki page to which you're welcome if you ever need to check __BYTE_ORDER_ or __UINT_FAST16_TYPE__ on your system.

Here's a small excerpt of it:

#+begin_src C :results verbatim
#include <stdio.h>

int main() {
  // version stuff
  printf("__GNUC__ %d\n", __GNUC__);
  printf("__GNUC_MINOR__ %d\n", __GNUC_MINOR__);
  printf("__GNUC_PATCHLEVEL__ %d\n", __GNUC_PATCHLEVEL__);
  printf("__VERSION__ %s\n", __VERSION__);
  return 0;
}
#+end_src

When you navigate to any place in the code and press C-c C-c, which calls (sic) org-ctrl-c-ctrl-c, it will re-compile and re-run your program.

I list here some of the config to make it all work:

(org-babel-do-load-languages
 'org-babel-load-languages
 '((C . t)
   ;; ...
   ))

(setq org-babel-C-compiler "gcc -std=c99")

New `auto-yasnippet` method

You can read up on what auto-yasnippet is in this post. For the wiki page, I had to insert the printf statements a bunch of times, some of them with triply-repeated symbols. Take, for instance, this statement:

printf("__INT32_TYPE__ %s (%d)\n", ESTR(__INT32_TYPE__), sizeof(__INT32_TYPE__));

With the old method, I would insert ~ before each INT32 and call aya-create. But it would result in this snippet, which isn't optimal:

printf("__$1 %s (%d)\\n", ESTR(__$1), sizeof(__$1));

With the new method (the old one still works, it's just that the new one takes priority), I would only quote the first field like so:

printf("__`INT32'_TYPE__ %s (%d)\n", ESTR(__INT32_TYPE__), sizeof(__INT32_TYPE__));

Which results in this snippet:

printf("__$1_TYPE__ %s (%d)\n", ESTR(__$1_TYPE__), sizeof(__$1_TYPE__));

Much better.

`oremacs` wiki workflow

If you're crazy enough (in a good way) to follow oremacs, you'll get the new wiki page delivered right to your config with

make install

which will also update to the latest org-mode and CEDET.

And here's how to access it:

run xmodmap etc/.Xmodmap to make ; into a modifier
press ;-k to open a dispatch hydra
press w to select the wiki
select C (currently, the only other candidate is git)

Outro

Check out the new auto-yasnippet method, I think it's pretty efficient. I hope that you'll find the wiki page useful in your C pursuits. And a big thanks to Eric Schulte for org-babel.

Blending colors in Elisp

2015-04-28T00:00:00+02:00

Intro

This is a slightly obscure feature that I've added today to ivy-mode. It's obscure, since very few packages give their candidates a face with a custom background. Still, when that happens, a conflict arises:

Which face to apply: ivy-current-match or the existing one?

In the image below, I've blended them both in a 50-50 mixture:

By the way, if you're wondering where the backgrounds come from in the first place, it's lispy-goto function (if you know what imenu is, it's an advanced version of that). This function collects all the Elisp tags in the current directory, and offers to jump to them. The functions that have interactive in them, are highlighted with lispy-command-name-face. In the above screenshot, the first 7 functions are interactive, and the other 2 are not.

If you're interested in how color blending is done, I'll describe it shortly below.

Color-building internals

First, a smaller and more clear example (I've used rainbow-mode and htmlize-buffer):

(colir-blend
 (color-values "red")
 (color-values "blue"))
;; => "#800080"

Here, colir-blend is a very small function that I'll describe below, and color-values is a function from faces.el that forwards to a C function xw-color-values with this doc:

Return a list of three integers, (RED GREEN BLUE), each between 0 and either 65280 or 65535 (the maximum depends on the system).

Which is a bit weird, since the last time I checked, the standard for colors was one-byte per channel, not two. Granted, it was about 10 years ago that I checked, and indeed, the entry on Wikipedia says:

High-end digital image equipment are often able to deal with larger integer ranges for each primary color, such as 0..1023 (10 bits), 0..65535 (16 bits) or even larger, by extending the 24-bits (three 8-bit values) to 32-bit, 48-bit, or 64-bit units

Apparently, Emacs is outfitted to deal high-end digital image equipment. But I'm still pretty sure that most graphics cards that you can buy only give 8 bits per each channel. Anyway, here's the code for the basic functions:

(defun colir-join (r g b)
  "Build a color from R G B.
Inverse of `color-values'."
  (format "#%02x%02x%02x"
          (ash r -8)
          (ash g -8)
          (ash b -8)))

(defun colir-blend (c1 c2 &optional alpha)
  "Blend the two colors C1 and C2 with ALPHA.
C1 and C2 are in the format of `color-values'.
ALPHA is a number between 0.0 and 1.0 which corresponds to the
influence of C1 on the result."
  (setq alpha (or alpha 0.5))
  (apply #'colir-join
         (cl-mapcar
          (lambda (x y)
            (round (+ (* x alpha) (* y (- 1 alpha)))))
          c1 c2)))

All pretty simple:

Split each color into red, green, and blue integers with color-values.
Compute a mean for each color channel.
Build the new color by concatenating the hex components into a string.

In the example above:

The result of (color-values "red") is (65535 0 0).
The result of (color-values "blue") is (0 0 65535).
Their arithmetic mean is (32768 0 32768).
Divided by 256 with ash, we get (128 0 128).
Converted to hex, (128 0 128) is (80 0 80).
And the final color is "#800080".

Outro

I hope that you've enjoyed this little venture into Elisp and colors. People say rough things about Elisp sometimes, but hey: it offers functions ranging from the assembly-level ash, all the way up to Photoshop-grade color channel handling.

If only it could get a good optimization bump, like JavaScript got at one point, and a small threading library, we'd be all set.

Oremacs config is on Github

2015-04-24T00:00:00+02:00

I noticed that the packages that I've published on Github in the last year did get a nice boost in quality just from being published, viewed, used and commented on.

So it makes sense to do the same for my full Emacs config, which lives in the oremacs repository as of today.

The config is personal in the sense that I'm actually using it verbatim, but it's been configured in a way that's it's easy to replicate and modify it.

Who can benefit from this config

The audience is people like me, who like to tinker with Elisp just for fun of it. If you want things to just work, or you find learning Elisp a chore, it's not for you.

The config won't work initially, it won't work always, but when it finally does work (hopefully), it will be glorious!

Installation and Running

Requirements

Emacs 24 is required. Obviously, newer versions are better, but the default emacs24 that you get from the package manager should work.

I'm currently switching between Emacs 24.5.2 built from source and the current master from git.

Install command

This config doesn't assume to become your main config when you install it. It installs in-place in the git directory and will start from there without touching your main config. But you still get access to all your stuff, like bookmarks stored in your actual ~/.emacs.d/ etc.

cd ~/git
git clone https://github.com/abo-abo/oremacs
cd oremacs
make install

Run command

Run without updating:

make run

Run with an upstream + ELPA update:

make up

Run with an upstream + ELPA + org-mode + CEDET update:

make install

Perks

Standalone

You can try it without messing up your current Emacs config. I actually have multiple versions of this on my system to work-around incompatibility between versions. This way, I can use my full setup even in case I get a bug report for an older Emacs version.

Fast start up

With a SSD, it starts in 1 second. Most features are autoloaded and it's easy to add new autoloaded features.

Tracks the most recent org-mode and CEDET

Since these packages take a long time to byte compile, they are updated not with make up but with make install. They are actually git submodules, which means that they won't update if I don't update them in the upstream.

Bankruptcy-proof

It's hard to become Emacs-bankrupt with this config, since the config is composed of many independent pieces that you can simply ignore if you don't need them.

Anti-RSI QWERTY mod

The config comes with its own .Xmodmap that makes ; into an additional modifier. RSI savers:

;-v instead of Enter.
;-o instead of Backspace.
;-f instead of Shift-9 and Shift-0.
;-a instead of -.
;-s instead of Shift--.
;-q instead of Shift-'.
;-e instead of =.
;-u in addition / instead of C-u.

And obviously the replacements for the two keys that the mod takes away:

;-j instead of ;.
;-d instead of Shift-;.

One more Elisp-level RSI-saver is the swap between C-p and C-h. Moving up/down line is very important, and it's nice to have these keys close, which C-n and C-h are.

It also includes:

a bunch of Hydras that save you key strokes.
lispy-mode which quickens any LISP mode, especially Elisp.
worf-mode which quickens org-mode.
ivy-mode which quickens all completion.
swiper which quickens isearch (by replacing it).
C/C++ is customized with function-args-mode and a bunch of hacks.

Org mode starter

The config starts you off with a fully configured org-mode setup that includes:

gtd.org for getting things done.
ent.org to track entertainment.
wiki folder for quickly starting and selecting wikis.

Outro

I hope that you try and enjoy the new config. Perhaps not verbatim, but if you find the tips on this blog helpful, this config is their actual implementation that you can use for reference.

Swiper 0.3.0 is out, with ivy-mode.

2015-04-22T00:00:00+02:00

This release packs more than 90 commits, which is quite a lot for me. The most important part of this release is ivy-mode, which is a nice alternative to ido-mode or helm-mode. I've mentioned it already in an earlier post, I'll just review all the little details, changes and customizations here.

Important: remove the old `ivy` package

One important change related to MELPA is that the ivy package was merged into swiper package. So if you still have a stand-alone ivy package, you should delete it, or you'll get incompatibility problems.

Video Demo of `counsel-git-grep`

If you like videos, you can watch the this quick demo which mostly shows off the new counsel-git-grep function.

Fixes

Add work-around for `window-start` being not current

From now on, you won't encounter some un-highlighted matches when your window is scrolled.

Make `thing-at-point` work

C-h v and C-h f should select thing-at-point properly.

Don't try to fontify huge buffers

It's a nice feature of swiper that everything in the minibuffer is fontified. However, this can cause a slowdown for buffers with x10000 lines. So this feature is automatically turned off for these large buffers.

Exclude a few modes from font locking

Some modes just misbehave when font-lock-ensure is called. Excluded:

org-agenda-mode
dired-mode

New Features

`ivy-mode`: complete everything with Ivy

ivy-mode uses swiper's approach to completion for almost all completion in Emacs, like:

execute-extended-command
package-install
find-file

See the wiki page for the details on the key bindings related to ivy-mode, which are especially important to know for find-file. Also see the intro video.

New Counsel functions

counsel-describe-variable - replacement for C-h v.
counsel-describe-function - replacement for C-h f.
counsel-info-lookup-symbol - just a wrapper around info-lookup-symbol, you get the same behavior by just calling info-lookup-symbol with ivy-mode on.
counsel-unicode-char - replacement for ucs-insert.

`counsel-git-grep`

This is a really cool command for grepping at once all the files in your current git repository. For smaller repositories (<20000) lines, ivy handles the completion by itself. For larger repositories, it defers the work to git grep. It works really well for the Emacs repo with its 3,000,000 lines, especially if you're using Emacs 25 (from emacs-snapshot or self-built).

This function makes use of C-M-n and C-M-p bindings, which switch between candidates without exiting the minibuffer. Also, they highlight the current candidate with the swiper faces. You can think of this command as multi-swiper.

Even for very large repos, it will always display the amount of matches correctly. Also note that swiper-style regex is used here (spaces are wild), and the case is ignored.

The arrows can take numeric arguments

C-n / C-p, C-s / C-r, and C-M-n / C-M-p can all take numeric args, e.g. M-5 or C-u.

Add a recenter binding

C-l will recenter the window in which swiper was called.

Look up Ivy key bindings with `C-h m`

While in the minibuffer, press C-h m to see the active modes. Ivy also has a paragraph with its bindings.

Use `C-v` and `M-v` to scroll

You can use these bindings to speed up your minibuffer scrolling.

Allow `C-.` to jump-to-definition

For counsel-describe-variable and counsel-describe-function:

pressing C-m will actually describe the current candidate.
pressing C-. will instead jump to definition of the the current candidate.

This is very useful for me, I jump to definitions more often that describe.

Bind arrows

The actual arrow keys are also bound to the corresponding Emacs arrows.

Add a way to exit ignoring the candidates

If your current input matches a candidate, C-m and C-j will exit with that candidate. If you want to exit with your exact input instead, press C-u C-j. This is very useful for creating new files and directories.

Use `M-q` to toggle `regexp-quote`

This can be useful while completing file names (with a lot of dots). Pressing M-q toggles between regex and non-regex matching.

Customize `ivy-re-builders-alist`

This is pretty intricate, look up the variable to see the details. In short, you can use this to apply `regexp-quote' for some types of completion if you want.

Customize what to do on `DEL` error

The standard behavior on a DEL error (usually empty minibuffer) is to exit the minibuffer. I like this behavior, since it's similar to the behavior to fixing wrongly typed chars: only in this case DEL "fixes" a wrongly typed command.

But if you want to customize it, just set ivy-on-del-error-function to something other than minibuffer-keyboard-quit.

Customize `ivy-extra-directories`

Customize this if you don't want to see ../ and ./ while completing file names.

Customize `ivy-sort-functions-alist`

Use this variable to customize sorting, depending on what you're completing. For example:

(setq ivy-sort-functions-alist
  '((read-file-name-internal . ivy-sort-file-function-default)
    (internal-complete-buffer . nil)
    (counsel-git-grep-function . nil)
    (t . string-lessp)))

Customize `ivy-subdir-face`

While completing file names, the directories will use ivy-subdir-face.

Outro

Big thanks to all who contributed, especially @tsdh.

Grep in a git repository using ivy

2015-04-19T00:00:00+02:00

Just got this request a few minutes ago, and now this feature is in the swiper repository (available as counsel from MELPA).

The motivation was to write an ivy equivalent of helm-git-grep. I didn't use this feature before, but the only thing that I needed to get me started was this shell command:

git --no-pager grep --full-name -n --no-color -i -e foobar

The rest of the code (just 20 lines) followed all by itself:

(defun counsel-git-grep-function (string &optional _pred &rest _u)
  "Grep in the current git repository for STRING."
  (split-string
   (shell-command-to-string
    (format
     "git --no-pager grep --full-name -n --no-color -i -e \"%s\""
     string))
   "\n"
   t))

(defun counsel-git-grep ()
  "Grep for a string in the current git repository."
  (interactive)
  (let ((default-directory (locate-dominating-file
                             default-directory ".git"))
        (val (ivy-read "pattern: " 'counsel-git-grep-function))
        lst)
    (when val
      (setq lst (split-string val ":"))
      (find-file (car lst))
      (goto-char (point-min))
      (forward-line (1- (string-to-number (cadr lst)))))))

Thanks to the push from Stefan Monnier, ivy-read also supports a function to be passed instead of a static collection of strings. In this case, it's counsel-git-grep-function that basically takes one argument: the thing that we're looking for.

After this, shell-command-to-string is my go-to function to quickly bring some shell output into Elisp. As you can see, it's enough to pass it a shell command in a string form to get a string response. I transform the response into a list of line strings with split-string, making sure to pass the t argument to avoid empty strings.

One final trick that you can learn for your own Elisp programming is the let / default-directory / (locate-dominating-file default-directory ".git") combo. It's quite useful for dealing with git shell commands. And that's it, it only remains to open a file and jump to the selected line.

I think that counsel-git-grep might complement and slightly displace rgrep or ag in my setup. So I've given it a nice binding:

(global-set-key (kbd "C-c j") 'counsel-git-grep)

I hope that I've made a good case of how easy it is to quickly write something in Elisp, especially if it's just a shell command wrapper. So if you're on the fence of whether to learn Elisp or not, do yourself a favor and learn it: it pays off quickly and is a lot of fun.

Side note: I've mentioned \bfun\b in this blog 182 times, mostly as a variable representing a function (courtesy of counsel-git-grep).

Introducing ivy-mode

2015-04-16T00:00:00+02:00

Today I'd like to introduce a function that has completely replaced ido-mode for me: ivy-mode. It comes with the swiper package, available both in MELPA and GNU ELPA. The latter is a bit slower to update, so the version there can be a bit outdated sometimes.

The quick video demo

If you prefer listening and watching to reading, check out the video demo here. It repeats most of the stuff written down below.

Generic completion

ivy-mode is simply a minor mode that changes completing-read-function to ivy-completing-read while it's active. This function is used in most of the places where Emacs requires completion, like:

M-x execute-extended-command
C-h f describe-function
C-h v describe-variable
package-install
C-x b switch-to-buffer
C-x C-f find-file

So, while ivy-mode is on, all these functions and more will use ivy completion.

Package-specific completion

org-mode

With the most recent master version, org-mode will obey completing-read-function, so it should work by default. If you try it for refiling to headings with similar names, you'll really notice how much better ivy-mode is at it. helm-mode also does well, if you don't mind the large window.

magit

This setting is needed to use ivy completion:

(setq magit-completing-read-function 'ivy-completing-read)

find-file-in-project

find-file-in-project will use ivy by default if it's available.

projectile

You can set this to make it work:

(setq projectile-completion-system 'ivy)

smex

Yes, it's also possible, since today. Although you'll have to use my fork of smex if you want to try it. I've sent a pull request, it's all backwards-compatible, so hopefully it'll get merged.

The nice thing is that smex can take care of the sorting all by itself, since ivy doesn't do that yet.

my packages

lispy and function-args use ivy by default. You can also enable it for helm-make, for which the default is obviously helm.

File name completion

When ivy-mode is on, find-file will also use it. The completion is considerably different from all other cases, since it's done in stages, just like ido-find-file does it.

The key bindings are:

RET will select the current candidate and finish.
C-j will try to continue the completion, i.e. if the current candidate is a directory, move to that directory. But if the current candidate is a file or ./, then finish.
/ will switch to completing the sub-directories of /, but if the candidate is a perfect match, it will act like C-j.
~ will switch to completing the sub-directories of ~/.
C-n and C-p naturally select the next and the previous candidate.

What's it all for?

Well, for me the advantage is obvious: I get my completion just the way I like it. You can use it as well if you find that you like it more than ido. I'll just list a list of features that I like:

The current number of candidates is robustly displayed and updated after each key stroke.
The minibuffer is an actual editing area, where the bindings like C-a, M-DEL and C-k etc. work just as you expect. Once you internalize the way that the regex is built, you can get your match very quickly and intuitively.
The actual regular expressions constructs like \\b or $ and ^ work. The only thing that works differently is the space: you can't match a single space because any amount of spaces translates into the .* wild card. But you can use it to your advantage and use the space instead of all the various symbol joining constructs out there, like snake_case, or kebab-case (yeah, it's totally called that, check the wiki), or whatever/this/is/case.
The familiar M-< and M-> key bindings also work as expected, navigating you to the first and last candidate respectively. When you press C-p on the first match or C-n on the last match, the match will not change, unlike the behavior of ido that has annoyed me a lot.
The minibuffer key bindings can actually be properly customized: just set ivy-minibuffer-map to whatever you like, it won't be changed. Even in Emacs 24.5, if you customize ido-completion-map, the change will be reset. That was fixed only in the current master.
You don't have to rely on flx or flx-ido to save you from the overwhelming number of matches. Instead, you type maybe a bit more, but in return you get a very consistent and predictable result. No black boxes or hidden variables that dramatically change the order of candidates from time to time.

Outro

Check it out, I hope you like it. And a big thanks to all who contributed code or bug reports.

Display the initial Hydra hint with a delay

2015-04-15T00:00:00+02:00

More hydra goodness incoming, this time thanks to @joedicastro. Firstly, he contributed this awesome-looking twittering-mode hydra to the wiki:

And a similarly nice one for helm:

You can look up the code for both hydras by following the above two links.

Secondly, he gave me a nice idea in #108:

A nice thing that guide-key has is that you can set an idle time to wait until you press a key to activate any head before show the hydra hints buffer (explained in hydra terms). This is very helpful when you know the key bindings by memory and you do not need to see the hints buffer, but if you forget how to activate any head, you simple press the hydra binding and wait the "idle time" and the hints buffer is shown to help you to choose the right next binding.

So this option is now also possible. Here's an example, using hydra-toggle from hydra-examples.el:

(defhydra hydra-toggle (:color blue
                        :idle 1.0)
  "toggle"
  ("a" abbrev-mode "abbrev")
  ("d" toggle-debug-on-error "debug")
  ("f" auto-fill-mode "fill")
  ("t" toggle-truncate-lines "truncate")
  ("q" nil "cancel"))
(global-set-key (kbd "C-c C-v") 'hydra-toggle/body)

So the single change from the old code is :idle 1.0, which means:

After a call to hydra-toggle/body, instead of displaying the hint as usual, start a timer for 1.0 seconds. Once the timer runs out, display the hint. But if the hydra has exited before that time, cancel the timer.

Typically, I'm not a huge fan of timers, but it's nice to have the option. And indeed, I've been noticing that I could do without a hint for some simple and more often used hydras. But a command can go from often to barely used quickly, and disabling the hint altogether seems too harsh. A timer could be a nice middle ground, especially since I can decide whether to use it or not and the interval for each specific hydra.

Anyway, thanks for the contributions. Enjoy the new feature, and keep those good ideas coming!

Org-mode Hydras incoming!

2015-04-14T00:00:00+02:00

A hydra for org-mode time/clock/capture

This is a categorized version of the hydra that @WorldsEndless contributed today to the wiki.

(defhydra hydra-global-org (:color blue
                            :hint nil)
  "
Timer^^        ^Clock^         ^Capture^
--------------------------------------------------
s_t_art        _w_ clock in    _c_apture
 _s_top        _o_ clock out   _l_ast capture
_r_eset        _j_ clock goto
_p_rint
"
  ("t" org-timer-start)
  ("s" org-timer-stop)
  ;; Need to be at timer
  ("r" org-timer-set-timer)
  ;; Print timer value to buffer
  ("p" org-timer)
  ("w" (org-clock-in '(4)))
  ("o" org-clock-out)
  ;; Visit the clocked task from any buffer
  ("j" org-clock-goto)
  ("c" org-capture)
  ("l" org-capture-goto-last-stored))

I've bound it like this:

(global-set-key [f11] 'hydra-global-org/body)

Previously, I had f11 bound to org-clock-goto, thanks to the Org Mode - Organize Your Life In Plain Text! post. I kind of recommend that post, as it has a tonne of useful stuff. At the same time, it resulted in me copying too much stuff that I didn't understand into my config, ultimately discouraging me from using org-mode. YMMV.

Screenshot:

A hydra for refile/archive

Inspired by the previous one, I wanted to write a hydra of my own. As it happened, I was just about to clean up my git notes. So I wanted a nice refile hydra to speed up the process.

Here's the hydra's code, which is now part of worf. Worf is a package for quickly navigating around an org-mode buffer, you can get it from MELPA.

(defhydra hydra-refile (:hint nil
                        :color teal)
  "
Refile:^^   _k_eep: %`org-refile-keep
----------------------------------
_l_ast      _a_rchive
_o_ther
_t_his

"
  ("t" worf-refile-this)
  ("o" worf-refile-other)
  ("l" worf-refile-last)
  ("k" (setq org-refile-keep (not org-refile-keep))
       :exit nil)
  ("a" (org-archive-subtree))
  ("q" nil "quit"))

Some explanations:

worf-refile-this will give you a choice of this file's headings for refiling.
worf-refile-other will give you a choice of your org-refile-targets except the current file.
worf-refile-last will refile to the last refile location without prompting.
k will toggle org-refile-keep, which decides if refiling moves or copies the text.

And here's how it looks like:

Outro

Thanks for the contribution, enjoy the new stuff. Also, if you ever want to dig around someone's git notes, you can read mine, courtesy of org-mode export.

Hydra 0.13.0 is out

2015-04-13T00:00:00+02:00

A lot of the changes for this release aren't very user-visible, although they are important in improving the usability. The main change is the move from the standard set-transient-map to my own hydra-set-transient-map.

This change has allowed to remove the part where the amaranth and pink hydras intercept a binding which doesn't belong to them and then try to forward it back to Emacs. It was done in this way, which might be interesting for people who write Elisp:

(define-key hydra-keymap t 'hydra-intercept)

Binding t means that when the keymap is active, any binding which doesn't belong to the keymap will be interpreted as t. Then, I would use lookup-key and this-command-keys and try to call the result. That method was quite fragile:

It didn't work for prefix keys while a pink hydra was active.
It didn't work for some keys in the terminal because of input-decode-map.

The new method solves the mentioned issues by not using t and instead running this function in the pre-command-hook:

(defun hydra--clearfun ()
  "Disable the current Hydra unless `this-command' is a head."
  (if (memq this-command '(handle-switch-frame
                           keyboard-quit))
      (hydra-disable)
    (unless (eq this-command
                (lookup-key hydra-curr-map
                            (this-single-command-keys)))
      (unless (cl-case hydra-curr-foreign-keys
                (warn
                 (setq this-command 'hydra-amaranth-warn))
                (run
                 t)
                (t nil))
        (hydra-disable)))))

This approach is actually very similar to what the built-in set-transient-map does from Emacs 24.4 onward. Of course, changing the a large cog in the Hydra mechanism can lead to some new bugs, or even old bugs to re-surface. So I really appreciate the help from @jhonnyseven in testing the new code.

As always, if you find something very broken, you can roll back to the GNU ELPA version and raise an issue.

Fixes

single command red/blue issue

Fix the uniqueness issue, when a single command is assigned to both a red and a blue head.

Here's an example:

(defhydra hydra-zoom (global-map "<f2>")
  "zoom"
  ("g" text-scale-increase "in")
  ("l" text-scale-decrease "out")
  ("r" (text-scale-set 0) "reset")
  ("0" (text-scale-set 0) :bind nil :exit t)
  ("1" (text-scale-set 0) nil :bind nil :exit t))

Here, three heads are assigned (text-scale-set 0), however their behavior is different:

r doesn't exit and has a string hint.
0 exits and has an empty hint (so only the key is in the docstring).
1 exits and has a nil hint (will not be displayed in the docstring).

The latter two call hydra-zoom/lambda-0-and-exit, while r calls hydra-zoom/lambda-r.

Don't default `hydra-repeast--prefix-arg` to 1

See #61 for more info.

Allow `hydra-repeat` to take a numeric arg

For hydra-vi, it's now possible to do this 4j.2... The line will be forwarded:

4 times by 4j
4 times by .
2 times by 2.
2 times by .

See #92 for more info.

Key chord will be disabled for the duration of a hydra

This means that hydras have become much more easy to use with key chords. For instance, if dj key chord calls a hydra or is part of the hydra, you won't call the jj key chord by accident with djj.

See #97 for more info.

New Features

Variable as a string docstring spec

You can now use this form in your hydras:

(defvar foo "a b c")
(defhydra bar ()
  "
  bar %s`foo
"
  ("a" 't)
  ("q" nil))

Previously, it would only work for %s(foo) forms.

`:bind` property can also be a keymap

If you remember, you can set :bind in the body to define in which way the heads should be bound outside the Hydra. You also assign/override :bind for each head. This is especially useful to set :bind to nil for a few heads that you don't want to bind outside.

Previously, :bind could be either a lambda or nil. Now a keymap is also accepted.

Integration tests

In addition to the abundant macro-expansion tests, integration tests are now also running, both for emacs24 and for emacs-snapshot. This means that hydra should be a lot more stable now.

Here's an example test:

(defhydra hydra-simple-1 (global-map "C-c")
  ("a" (insert "j"))
  ("b" (insert "k"))
  ("q" nil))

(ert-deftest hydra-integration-1 ()
  (should (string= (hydra-with "|"
                               (execute-kbd-macro
                                (kbd "C-c aabbaaqaabbaa")))
                   "jjkkjjaabbaa|"))
  (should (string= (hydra-with "|"
                               (condition-case nil
                                   (execute-kbd-macro
                                    (kbd "C-c aabb C-g"))
                                 (quit nil))
                               (execute-kbd-macro "aaqaabbaa"))
                   "jjkkaaqaabbaa|")))

In the tests above, hydra-simple is a defined and bound hydra. "|" represents the buffer text (empty), where | is the point position. And (kbd "C-c aabbaaqaabbaa") represents the key sequence that you can normally press by hand. Finally, "jjkkjjaabbaa|" is what the buffer and the point position should look like afterwards. If you find a hydra bug, it would be really cool to submit a new integration test to make sure that this bug doesn't happen in the future.

Basic error handling

I really like the use-package feature where it catches load-time errors and issues a message instead of bringing up the debugger. This is really useful, since it's hard to fix the bug with a mostly broken Emacs, in the case when the error happened early in the load process. So the same behavior now happens with defhydra. In case of an error, defhydra will be equivalent to a no-op, and the error message will be written to the *Messages* buffer.

Use a variable instead of a function for the hint

This leads up to the yet unresolved #86, which asks for heads to be activated conditionally.

For now, you can modify the docstring on your own if you wish. Here's some code from the expansion of hydra-zoom to explain what I mean:

(set
 (defvar hydra-zoom/hint nil
   "Dynamic hint for hydra-zoom.")
 '(format
   #("zoom: [g]: in, [l]: out."
     7 8 (face hydra-face-red)
     16 17 (face hydra-face-red))))
;; in head body:
(when hydra-is-helpful
  (if hydra-lv
      (lv-message
       (eval hydra-zoom/hint))
    (message
     (eval hydra-zoom/hint))))

Eventually, I'll add some automatic stuff to fix #86. But for now, you can experiment with modifying e.g. hydra-zoom/hint inside heads, if you want.

Multiple inheritance for Hydra heads

Each hydra, e.g. hydra-foo will now declare its own heads as a variable hydra-foo/heads. It's possible to inherit them like this:

(defhydra hydra-zoom (global-map "<f2>")
  "zoom"
  ("g" text-scale-increase "in")
  ("s" text-scale-decrease "out"))

(defhydra hydra-arrows ()
  ("h" backward-char "left")
  ("j" next-line "down")
  ("k" previous-line "up")
  ("l" forward-char "right"))

(defhydra hydra-zoom-child (:inherit (hydra-zoom/heads
                                      hydra-arrows/heads)
                            :color amaranth)
  "zoom"
  ("q" nil))

Here, hydra-zoom-child inherits the heads of hydra-zoom and hydra-arrows. It adds one more head q to quit. Also, it changes the color to amaranth, which means that it's only possible to exit it with q or C-g. This hydra's parents remain at their original (red) color.

See #57 for more info.

Outro

A big thanks to all who contributed towards this release and to the wiki. If you have an idea that would be cool in Hydra, do raise an issue. And if you written some cool code that uses the already available Hydra features, please share it on the wiki. It's also a good way to protect your code against regressions (although the best one would be an integration test).

Finally, check out the new version of pandoc-mode which is one of the coolest and most elaborate uses of Hydra yet.

Complete stuff with Counsel

2015-04-09T00:00:00+02:00

Intro

If you like my package swiper, I'm sure you'll also like counsel. It lives in the same repository, but you can install it separately from MELPA.

Counsel uses ivy - the same method as swiper to:

Complete Elisp at point with counsel-el.
Complete Clojure at point with counsel-clj.
Open a git-managed file with counsel-git.
Describe an Elisp variable with counsel-describe-variable.
Describe an Elisp function with counsel-describe-function.
Look up an Elisp symbol in the info with counsel-info-lookup-symbol.
Insert a Unicode character at point with counsel-unicode-char.

Below, I'll describe the functions that I added just today.

`counsel-describe-function`

This is just a replacement for describe-function:

As you can see, regular expressions work here as well. The space-splitting behavior is the same as in swiper, so don't expect to be able to match a single space: spaces are wild.

`counsel-describe-variable`

This is just a replacement for describe-variable:

Well, actually I've used ido-mode with flx matching for these two functions before. In my experience, ivy handles much better:

you are in charge of which regex you're searching for
you see the candidate count
no crazy wrap-around candidate cycling

And it works faster, too.

Here are my bindings:

(global-set-key (kbd "<f1> f") 'counsel-describe-function)
(global-set-key (kbd "<f1> v") 'counsel-describe-variable)

`counsel-info-lookup-symbol`

I don't use this one too often, but it's nice to have the option:

(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)

`counsel-unicode-char`

At around 40000 candidates, ivy starts to feel clunky (around 0.1s display delay). Unfortunately, I don't really see a way around this, except using tricks like while-no-input, which didn't work right when I tried it earlier. It would be really cool to do the completion in another thread, but alas.

Outro

Give the new functions a try. I think ivy can become a viable ido replacement, at least it has done so for me: the only ido functions that I'm still using are ido-switch-buffer and ido-find-file.

Also, if you're using projectile, you can use ivy completion for it:

(setq projectile-completion-system 'ivy)

Rule-based multi-line in lispy

2015-04-06T00:00:00+02:00

Where do one-line expressions come from?

When programming LISP, especially with lispy, it's easy to generate random one-line expressions. This is, of course, because the results of read or eval don't contain any whitespace information: all original newlines are lost.

Just to review the multitude of ways to insert generated code into a buffer using lispy I'll list the shortcuts and the test-based explanations (at around 2000 lines of tests and 54% test coverage, lispy is pretty well tested).

eval-and-insert

E calls lispy-eval-and-insert.

The image above is generated using the interactive test visualizer lispy-view-test, bound to xv. If you want to explore how a certain command is intended to behave, just find the corresponding test (with the same name as the command) and call xv.

eval-and-replace

xr calls lispy-eval-and-replace. This function evaluates the current expression and replaces it with the result.

The sequence of actions in the test:

e calls lispy-eval to set foo to 42.
j calls lispy-down to move to the next sexp.
xr calls lispy-eval-and-replace.

Ideally, there should have been "xr" instead of (lispy-eval-and-replace) in the test, but there's a small wrinkle in the lispy-with macro that needs to be fixed before that can happen.

flatten

xf calls lispy-flatten. This function expands in-place the current function or macro call.

In this test, the misleadingly named function square is evaluated and flattened, to see if the &optional and &rest argument passing rules indeed work.

The flatten operation works really well for Elisp and quite well for Clojure. The CL implementation would need to heavily rely on SLIME features (currently absent), since the CL spec doesn't define an equivalent of Elisp's symbol-function. The same applies to Scheme, I guess.

oneline

O calls lispy-oneline. It's not eval-based, it just deletes the newlines. If there are any comments present, they are pushed out.

`lispy-alt-multiline` Demo 1

In the following image, I just press T once, starting from an unchanged buffer:

`lispy-alt-multiline` Demo 2

Flatten `push`

Start from this code (the cursor is in the CSS, if you don't see it):

(let (res)
  (dotimes (i 10)
    (push i res))
  (nreverse res))

After xf it becomes:

(let (res)
  (dotimes (i 10)
    (setq res
          (cons i res)))
  (nreverse res))

Since push is a macro, macroexpand is used. And since macroexpand doesn't give newline information, pp-to-string is used, and it gives a reasonable result.

Flatten `dotimes`

Start with the same code, but with cursor on dotimes this time:

(let (res)
  (dotimes (i 10)
    (push i res))
  (nreverse res))

After xf it becomes:

(let (res)
  (cl--block-wrapper
   (catch '--cl-block-nil--
     (let
         ((--dotimes-limit-- 10)
          (i 0))
       (while
           (< i --dotimes-limit--)
         (setq res
               (cons i res))
         (setq i
               (1+ i))))))
  (nreverse res))

This time pp-to-string isn't as good: let and while statements are messed up. Follow this up with T which calls lispy-alt-multiline:

(let (res)
  (cl--block-wrapper
   (catch '--cl-block-nil--
     (let ((--dotimes-limit-- 10)
           (i 0))
       (while (< i
                 --dotimes-limit--)
         (setq res
               (cons i
                     res))
         (setq i
               (1+
                i))))))
  (nreverse res))

Well, at least some parts look better. It could be make perfect by adding a sort of threshold when printing each sub-expression. It's less than, say 15 chars, which (setq i (1+ i)) is, no newlines should be added. I'll add this a bit later.

More on `lispy-alt-multiline`

lispy-alt-multiline can be used on a LISP expression to re-format it across multiple lines. It doesn't matter in which shape the expression currently is, since all current newlines will be removed before the algorithm starts.

This has to be done with some rules, since a one-line expression can transform to multiple viable multi-line forms. So far, these rules are implemented by customizing these variables:

(defvar lispy--multiline-take-3
  '(defvar defun defmacro defcustom defgroup)
  "List of constructs for which the first 3 elements are on the first line.")

(defvar lispy--multiline-take-2 '(defface define-minor-mode
  condition-case while incf car cdr > >= < <= eq equal incf decf
  cl-incf cl-decf catch require provide setq cons when if unless interactive)
  "List of constructs for which the first 2 elements are on the first line.")

The name suggests that there should be lispy-multiline, and there is, bound to M. The difference between M and T is that M is older and ad-hoc, while T is newer and rule-based. This means that the latter can misbehave, since it's not yet fully tested. However, it has the following built-in check to make sure that it doesn't mess up your code:

The read of the expression before transformation should be equal to the read of the transformed expression.

If the above check fails, no change will be performed on the source code. So your code should be pretty safe. One more cool thing that I want to add to other operations is that it checks if the buffer will be changed after the transformation. If there will be no change, it will just issue a "No change" message, and no change will be performed. This is really cool if you obsess about the buffer changed marker in the mode line like I do.

Outro

The functions bound to O, M, and T apply to the current expression. To be really sure which one, turn on show-paren-mode. You can also call these functions not from special, although it's not very convenient. The typical strategy in that case would be to bind all of them on a prefix map, e.g. C-c. How is it different from special then?

Instead of typing [T you would type C-c T.

But the advantage of the special approach is that [ actually does something (moves point to the start of the current list), instead of just being a useless part of a key combination like C-c. And if you're in special already, there's no need for [.

I hope that you enjoy the new update. If it's needed, variables like lispy--multiline-take-3 can be made buffer-local so that T works appropriately for Clojure, CL and Scheme, instead of just Elisp. If you'd like to add support for your favorite dialect in this way, I'd be happy to explain some details if needed and to merge the PR. Happy hacking!

Paredit emulation in lispy

2015-04-02T00:00:00+02:00

Intro

I just finished this feature today. Almost all Paredit functionality is available in terms of lispy's own functions. The only functions that I didn't implement were the ones that I didn't find any use for: paredit-backslash (ugh, prompts), paredit-comment-dwim (covered by regular ;), paredit-forward-down and paredit-backward-down (both just move out of special, and throw a lot).

Setting the keymap theme

So if you ever thought that lispy could be a good idea, but the non-special key bindings are weird, and you're too used to Paredit, you can now try this setting:

(lispy-set-key-theme '(special paredit c-digits))

Here's the setting that I'm using, since I love lispy's default bindings:

(lispy-set-key-theme '(oleh special lispy c-digits))

The default setting actually is this one, lispy-mode-map-oleh is an additional map for use with my Xmodmap setup:

(lispy-set-key-theme '(special lispy c-digits))

Each item in the list passed to lispy-set-key-theme designates a keymap to turn on. So in a non-LISP buffer you could turn on just the special map:

(lispy-set-key-theme '(special))

This would mean that zero regular bindings get overridden, but when the point is before or after a paren, you get the lispy bindings. Actually, I've just enabled lispy-mode for markdown-mode, and it's working great. Unfortunately, I haven't yet figured out how to make a minor mode's keymap buffer-local. Maybe someone reading has an idea.

The screencast

I went through all of Paredit tests and made ERT tests out of them, to make sure that the features are actually working. I've recorded a short (<3 minutes) screencast of implementing one of the tests. Have a look, maybe you'll something interesting in my setup. There are two short pauses in the video, that's just me thinking how to write down a function. My ERT and Magit workflows are also shown.

Outro

The new key-theme feature is meant to make lispy super-not-annoying. I think it's useful, since using lispy in Paredit mode was annoying for me, so the opposite has to be true for people that are used to Paredit. So if you notice a bug, please report it, bug reports are very important for my non-annoyance agenda.

Finally, if you're super-devoted to Paredit and don't want to drop it, now you can easily have both lispy-mode and paredit-mode on. Just use this setting:

(lispy-set-key-theme '(special))

Or this one if you additionally want C-1 to show the inline doc, and C-2 to show the inline args:

(lispy-set-key-theme '(special c-digits))

lispy 0.25.0 is out

2015-04-01T00:00:00+02:00

Seriously, check the release notes if you don't believe me.

Fixes

Add minibuffer-inactive-mode to the lispy-elisp-modes list. It means that you can eval there if you want.
V (lispy-visit) should turn on projectile-global-mode if it's not on.
M (lispy-multiline) works better for Clojure: the regexes for vectors, maps and sets have been improved.
C-k should not delete only the string when located at start of string.
M will not turn vectors into lists any more.
the backquote bug for i and M was fixed.
you can flatten Elisp closures as well, at least the plain ones.

New Features

`b` calls `lispy-back`

The movement commands, such as:

the arrows hjkl (lispy-left, lispy-down etc.)
f (lispy-flow)
q (lispy-ace-paren)
i (lispy-tab), only when called for an active region

will not store each movement in the point-and-mark history. You can press b to go back in history. This is especially useful for h, l, and f, since they are not trivially reversible.

b was previously bound to lispy-store-region-and-buffer, so you could do Ediff with b and B. Now it's bound to xB.

Hungry comment delete

C-d (lispy-delete) when positioned at the start of a comment, and with only whitespace before the start of the line, will delete the whole comment.

If you want to un-comment, just use C-u ; from any point in the comment.

Added flatten operation for Clojure

xf (lispy-flatten) now also works for Clojure, before it was only for Elisp.

Example 1 (flatten a macro):

|(->> [1 2 3 4 5]
     (map sqr)
     (filter odd?))

When you press xf you get this:

|(filter odd? (map sqr [1 2 3 4 5]))

Example 2 (flatten a standard function):

Start with:

|(map odd? [1 2 3 4 5])

After xf:

(let [f odd? coll [1 2 3 4 5]]
  (lazy-seq (when-let [s (seq coll)]
              (if (chunked-seq? s)
                (let [c (chunk-first s)
                      size (int (count c))
                      b (chunk-buffer size)]
                  (dotimes [i size]
                    (chunk-append b (f (.nth c i))))
                  (chunk-cons (chunk b)
                              (map f (chunk-rest s))))
                (cons (f (first s))
                      (map f (rest s)))))))

A bit of a gibberish, but at least we can confirm that map is indeed lazy.

Example 3 (flatten your own function):

Example function:

(defn sqr [x]
  (* x x))

This one requires the function to be properly loaded with C-c C-l (cider-load-file), otherwise Clojure will not know the location of the function.

Example statement:

(+ |(sqr 10) 20)

After xf:

(+ |(let [x 10]
     (* x x)) 20)

Added lax eval for Clojure

This is similar to the lax eval for Elisp. If you mark an expression with a region:

asdf [1 2 3]

and press e, you will actually eval this:

(do (def asdf [1 2 3])
    asdf)

You can do this for let bindings, it's super-useful for debugging. The rule is that if the first element of the region is a symbol, and there's more stuff in the region besides the symbol, a lax eval will be performed.

`e` will auto-start CIDER

If CIDER isn't live, e will start it and properly eval the current statement.

`2F` will search for variables first

Since Elisp is a LISP-2, there can be a function and a variable with the same name. F (lispy-follow) prefers functions, but now 2F will prefer variables.

`2e` will eval and insert the commented result

Starting with:

|(filter odd? (map sqr [1 2 3 4 5]))

Pressing 2e gives:

(filter odd? (map sqr [1 2 3 4 5]))
;; =>
;; (1 9 25)

This works for all dialects, so you can also have:

(symbol-function 'exit-minibuffer)
;; =>
;; (closure (t)
;;          nil "Terminate this minibuffer argument." (interactive)
;;          (setq deactivate-mark nil)
;;          (throw (quote exit)
;;            nil))

*MODULES*
;; =>
;; ("SWANK-ARGLISTS" "SWANK-FANCY-INSPECTOR" "SWANK-FUZZY" 
;;                   "SWANK-UTIL" "SWANK-PRESENTATIONS" 
;;                   "SWANK-TRACE-DIALOG" "SB-CLTL2")

To do the last eval you need to be in special. It means that you first have to mark the symbol *MODULES* with a region. A convenient function to mark the current symbol is M-m (lispy-mark-symbol).

`y` (`lispy-occur`) now has an `ivy` back end

lispy-occur launches an interactive search within the current top-level expression, usually a defun. This is useful to see where a variable is used in a function, or to quickly navigate to a statement.

You can customize lispy-occur-backend to either ivy (the default) or helm (if you have it, since it's no longer a dependency of lispy).

Add ivy back end to `lispy-completion-method`

Now it's the default one for navigating to tags. You can select alternatively helm or ido if you wish.

Remove the dependency on `ace-jump-mode`

Instead the dependency on ace-window will be re-used. This allows for a lot of code simplifications and better tests.

New custom variables:

lispy-avy-style-char: choose where the overlay appears for Q (lispy-ace-char)
lispy-avy-style-paren: choose where the overlay appears for q (lispy-ace-paren)
lispy-avy-style-symbol: choose where the overlay appears for a (lispy-ace-symbol) and - (lispy-ace-subword) and H (ace-symbol-replace).

There's also lispy-avy-keys, which is a ... z by default.

Add `lispy-compat`

This is a list of compatibility features with other packages, such as edebug and god-mode. They add overhead, so you might want to turn them off if you don't use the mentioned packages.

`F` works for Scheme

You can navigate to a symbol definition in Scheme with F. This feature was already in place for Elisp, Clojure and CL.

Outro

Looks like a great batch of features, but I'm the most happy about the stupid backquote bug being fixed.

Up next: pre-defined key binding themes, featuring:

the beloved default.
the old-school paredit.
the special-only minimal.
and maybe one more.

Feel free to chime in, if you've got a key setup that you think other people will like. Happy hacking!

An update to my Elisp ERT / Travis CI setup

2015-03-30T00:00:00+02:00

This post might be interesting to people who use Travis CI to test their Elisp packages.

I've noticed a few days ago that my tests on Travis CI started failing randomly. Turns out that the widely used ppa:cassou/emacs has become deprecated. It still sort of works, but sometimes apt-get update just times out, and I get a build error.

Since it was the only one that I was using, I had to find another one. I went with emacs-snapshot from ppa:ubuntu-elisp.

Here's my current .travis.yml:

language: emacs-lisp
env:
  matrix:
    - emacs=emacs-snapshot

before_install:
  - sudo add-apt-repository -y ppa:ubuntu-elisp
  - sudo apt-get update -qq
  - sudo apt-get install -qq $emacs
  - curl -fsSkL --max-time 10 --retry 10 --retry-delay 10 https://raw.github.com/cask/cask/master/go | python

script:
  - make cask
  - make test

I've adopted one more change in the above code: EMACS is replaced by emacs. The reason for this is that both ansi-term and compile for legacy reasons set EMACS to strange values, like "24.4.91.2 (term:0.96)". So if you have in your Makefile:

EMACS ?= emacs

you're going to have a bad time. So I changed my Makefile to:

emacs ?= emacs

And now I can compile and test while inside Emacs with no issues. The only issue left is that I don't yet know which PPA I should use for a stable Emacs. Maybe someone has a suggestion.

recenter-positions, that's not how gravity works!

2015-03-28T00:00:00+01:00

Yesterday, I've added a new binding to swiper-map: C-l will now call swiper-recenter-top-bottom. The implementation is really easy, almost nothing to write home about:

(defun swiper-recenter-top-bottom (&optional arg)
  "Call (`recenter-top-bottom' ARG) in `swiper--window'."
  (interactive "P")
  (with-selected-window swiper--window
    (recenter-top-bottom arg)))

An interesting thing that I want to mention though is the customization of the default recenter-top-bottom behavior. This is the default one:

(setq recenter-positions '(middle top bottom))

And this is the logical one that I'm using:

(setq recenter-positions '(top middle bottom))

Try it out, and see if it makes sense to you. For me, when I've just jumped to a function definition, which usually means that the point is on the first line of the function, the first recenter position has to be top, since that will maximize the amount of the function body that's displayed on the screen.

Another use-case is when I'm reading an info or a web page. After a recenter to top, all that I have read is scrolled out of view, and I can continue from the top.

A Hydra for ivy/swiper

2015-03-26T00:00:00+01:00

Today I'll share a Hydra that I've been working on that's similar to Lit Wakefield's original idea for a helm hydra.

The Code

(defhydra hydra-ivy (:hint nil
                     :color pink)
  "
^^^^^^          ^Actions^    ^Dired^     ^Quit^
^^^^^^--------------------------------------------
^ ^ _k_ ^ ^     _._ repeat   _m_ark      _i_: cancel
_h_ ^✜^ _l_     _r_eplace    _,_ unmark  _o_: quit
^ ^ _j_ ^ ^     _u_ndo  
"
  ;; arrows
  ("h" ivy-beginning-of-buffer)
  ("j" ivy-next-line)
  ("k" ivy-previous-line)
  ("l" ivy-end-of-buffer)
  ;; actions
  ("." hydra-repeat)
  ("r" ivy-replace)
  ("u" ivy-undo)
  ;; dired
  ("m" ivy-dired-mark)
  ("," ivy-dired-unmark)
  ;; exit
  ("o" keyboard-escape-quit :exit t)
  ("i" nil))

Here's how I bind it:

(define-key ivy-minibuffer-map (kbd "C-o") 'hydra-ivy/body)

And here are the auxiliaries:

(defun ivy-dired-mark (arg)
  (interactive "p")
  (dotimes (_i arg)
    (with-ivy-window
      (dired-mark 1))
    (ivy-next-line 1)
    (ivy--exhibit)))

(defun ivy-dired-unmark (arg)
  (interactive "p")
  (dotimes (_i arg)
    (with-ivy-window
      (dired-unmark 1))
    (ivy-next-line 1)
    (ivy--exhibit)))

(defun ivy-replace ()
  (interactive)
  (let ((from (with-ivy-window
                (move-beginning-of-line nil)
                (when (re-search-forward
                       (ivy--regex ivy-text) (line-end-position) t)
                  (match-string 0)))))
    (if (null from)
        (user-error "No match")
      (let ((rep (read-string (format "Replace [%s] with: " from))))
        (with-selected-window swiper--window
          (undo-boundary)
          (replace-match rep t t))))))

(defun ivy-undo ()
  (interactive)
  (with-ivy-window
    (undo)))

The dired operations

There's actually an outstanding issue to make the hydra heads appear conditionally. This would be quite useful for the m and , bindings, since they don't work outside a dired buffer. Maybe I'll get to it on the weekend. Meanwhile, here's a screenshot for marking files in dired using swiper:

Since the input is "mar 10", swiper transforms it into the regex "(mar).*(10)". What I do next:

C-o to get into the hydra state.
99m to mark everything. Normally, it would mark 99 candidates, but since there are only 17, that means all of them.
h to go to the first candidate.
j, to to skip one candidate and unmark, then unmark some more, using this method.

If I wanted to move two candidates down at once, I could press 2j...... The . will repeat the previous command with the previous argument. You can also set the argument later, e.g. j.2.3.. etc.

The exit points

There are two:

i will bring you back to ivy, so that you can edit the input.
o will quit everything and bring you to the dired buffer.

So you could first mark Mar 10, exit with i, edit the input to Mar 17, press C-o and mark some more. Then finally exit with o.

The replace and undo operations

These two I've added the latest, so they are still a bit off. The ivy-replace option is similar to vim's r (I did vimtutor yesterday). It lets you replace the selected candidate. And u simply calls undo. Strangely, at the moment it will undo several ivy-replace operations at once, even though I call undo-boundary in ivy-replace.

Outro

I think ivy and the hydra docstring blend in together quite nicely, like old dogs and new tricks. I don't know which is which.

Swiper 0.2.0 is out

2015-03-25T00:00:00+01:00

I forgot to mark the 0.1.0 release, so I'm giving an overview of all the fixes and new features since the first commit in the release notes.

Fixes

Fix font locking in certain modes

Some major modes try to optimize the font locking (highlighting text with various faces) by only doing it for the visible portion of the text. But since swiper needs to access all lines at once, it's necessary to font lock the whole buffer. This is done in swiper-font-lock-ensure. For some modes, the buffer becomes discolored after calling swiper-font-lock-ensure. In theory, this should not happen. As a work-around, I exclude these modes from ensuring font lock:

package-menu-mode
gnus-summary-mode
gnus-article-mode
gnus-group-mode
emms-playlist-mode
erc-mode

If you see a discoloration in one of your favorite major modes while using swiper, just let me know and I'll add it to the list.

Fix face changes in the minibuffer propagating to the main buffer

This was a quite interesting bug. At that moment, I was using add-face-text-property to add faces to the copies of strings in the minibuffer. However, this function destructively modifies the properties, so the change to the properties of a string copy (obtained with concat or copy-sequence) was propagated to the properties of the original string. This was fixed by using font-lock-append-text-property instead of add-face-text-property.

`ivy-read` returns immediately for 0-1 candidates

An obvious improvement.

Clean up overlays better for `C-g`

The hidden overlays revealed during the search will be re-hidden if you cancel the search with C-g.

Ensure that candidates don't have read-only property

This issue was causing a bug while using swiper in erc-mode, since it marks all of the buffer content to read-only. So once a string with read-only property is inserted into the minibuffer, you can't delete it unless you set inhibit-read-only.

New Features

Optional initial input

If you call (swiper "fix"), you'll start searching with initial input "fix".

Restore the initial point on canceling

If you cancel the search with e.g. C-g (or DEL when there's no input), the initial point will be restored.

Inherit standard faces

To give a more standard default appearance, swiper faces inherit the default faces:

isearch-lazy-highlight-face
isearch
match
isearch again
highlight

Most themes customize these faces, so by re-using them swiper blends in better. If you want the cool (my opinion) original faces, have a look at eclipse-theme.

Reveal invisible overlays

This is quite important for searches in org-mode buffers. I tried to make it as close as possible to what isearch is doing.

Mark is saved for successful searches

This is the behavior of isearch. After you complete a search, you can go back to the search start with C-x C-SPC (pop-global-mark).

The current candidate is anchored to the current position

This means that if many candidates are matching the current input, the one which is closest to the current line (going forwards) is selected. This is important for not losing the context of what you're searching.

Don't recenter unless necessary

This is similar to the behavior of isearch: a scroll is performed only if the candidate is out of the window bounds. An alternate strategy of keeping the current candidate always centered in the window is more distracting.

Decouple helm back end

swiper command uses only ivy now. If you want to use helm, have a look at swiper-helm.

Add history handling

M-n will select the next history element, and M-p will select the previous history element.

When there is no input, both C-s and C-r will select the last history element. This is to make it similar to isearch.

When there is no input, and only once during the search, M-n will select symbol-at-point as the current input.

Truncate candidates to window width in the minibuffer

If a candidate is longer than the window width, it will be appropriately truncated with .... You can still match the invisible parts.

Warn for empty buffer

Obviously there's nothing to search for in an empty buffer.

Bring the last history candidate to front

In case of a successful search, the current input will be removed from history, and then re-added to the front.

Make `C-n` and `C-p` differ from `C-s` and `C-r`

The arrows will not recall the last history element in case the input is empty. Otherwise, C-n matches to C-s and C-p matches to C-r.

`ivy-read` now displays the number of candidates in the prompt

The prompt argument can hold a format-style expression, e.g. " [% 3d] pattern:", and the integer parameter will be updated with the current amount of matches. You can also customize ivy-count-format, that defaults to "%-4d ".

Custom amount of chars to start highlighting

Customize swiper-min-highlight for this. It defaults to 2, which means that the current buffer will be highlighted when the input has 2 chars or more. You can set it to 1 if you want, I found it slightly distracting, since there will be a lot of highlights for just one char input. Or you can set it to a larger value if you want the highlights to appear later.

Customize wrapping for `C-n` and `C-p`

This feature being on by default in helm-swoop was very distracting for me, and one of the reasons that I wrote swiper. So it's off by default, but you can set it if you want. Calling C-p on line number 0 will cycle to the last candidate etc.

Update Copyright

Since swiper was added to GNU ELPA, I had to assign the Copyright to the FSF. This also means that you also need an FSF Copyright assignment for Emacs in order to contribute more than total of 15 lines to the swiper code. It's really easy to get and is already necessary to contribute to any package that is part of Emacs.

Add `swiper-query-replace`

You can start a query replace operation starting with the current candidate with M-q. If you want to query replace in whole buffer, just do M-< M-q. And remember that ! will auto-replace all matches for the current query.

The default binding of M-q is fill-paragraph. This function is useless in the minibuffer, so I chose that binding for query-replace, which is normally bound to sub-optimal M-%. Although there are worse bindings than M-% (hold three keys at once), for instance, there's C-M-% (hold four keys at once) that calls query-replace-regexp.

Outro

Enjoy the new features, and a big thanks to all who contributed!

Transform region into ASCII art

2015-03-23T00:00:00+01:00

Here's a command that I've found laying around my config that you might find interesting:

(defun ora-figlet-region (&optional b e)
  (interactive "r")
  (shell-command-on-region b e "toilet" (current-buffer) t))

You can install the toilet shell utility from your package manager. Here's an example result:

    #"
   m"    mmm    m mm          mmm   mmmmm   mmm    mmm    mmm
   #    #" "#   #"  "        #"  #  # # #  "   #  #"  "  #   "
   #    #   #   #            #""""  # # #  m"""#  #       """m
    #   "#m#"   #            "#mm"  # # #  "mm"#  "#mm"  "mmm"
     "

If you don't mind the strange name, the output looks quite nice.

Hydra 0.12.0 is out

2015-03-22T00:00:00+01:00

With a month's time and almost 50 commits since that last one, a new version of Hydra has emerged. As usual, I'll just re-state the release notes.

Fixes

Handling of heads with duplicate cmd was improved.
Don't bind nil in outside keymaps.
Work-around golden-ratio-mode in lv-window.
C-g (hydra-keyboard-quit) should run :post.
Bind [switch-frame] to hydra-keyboard-quit.
:post is called for :timeout.

New Features

hydra-key-format-spec is a new defcustom for the keys format in the docstring. It's "%s" by default, but you can set it to e.g. "%-4s" if you like.
The key regex was extended to include most common key binding characters.
hydra-repeat is a hydra-specific repeat function. It behaves as you would expect repeat to behave.
New body option - :timeout. Use e.g. :timeout 2.0 to set the timer. After the first head is called, a timer is started to disable the hydra. Each new head call resets this timer, so the hydra won't disappear as long as you keep typing.
Lines are truncated in lv-message. This is useful for large docstring not to become misaligned when the window becomes too small.

Allow for a `%s(test)` spec in the docstring

The spec that's used for e.g. (test) is %S. So if (test) returns a string, it will be quoted. This may not be desired, hence the new feature. Example:

(defhydra hydra-marked-items (dired-mode-map "")
  "
Number of marked items: %(length (dired-get-marked-files))
Directory size: %s(shell-command-to-string \"du -hs\")
"
  ("m" dired-mark "mark"))

The pink/amaranth override is set recursively

This fixes the issue in this hydra:

(defhydra hydra-test (:color amaranth)
  "foo"
  ("fo" (message "yay"))
  ("q" nil))

Before, pressing e.g. fp would not issue a warning, since f started its own keymap. This is now fixed.

An option to specify the hint for all heads in body

When you write a large docstring, you usually pass nil as the hint for most heads. Now you can omit it, if you set :hint nil in body. Example:

(defhydra hydra-org-template (:color blue :hint nil)
  "
_c_enter  _q_uote    _L_aTeX:
_l_atex   _e_xample  _i_ndex:
_a_scii   _v_erse    _I_NCLUDE:
_s_rc     ^ ^        _H_TML:
_h_tml    ^ ^        _A_SCII:
"
  ("s" (hot-expand "<s"))
  ("e" (hot-expand "<e"))
  ("q" (hot-expand "<q"))
  ("v" (hot-expand "<v"))
  ("c" (hot-expand "<c"))
  ("l" (hot-expand "<l"))
  ("h" (hot-expand "<h"))
  ("a" (hot-expand "<a"))
  ("L" (hot-expand "<L"))
  ("i" (hot-expand "<i"))
  ("I" (hot-expand "<I"))
  ("H" (hot-expand "<H"))
  ("A" (hot-expand "<A"))
  ("<" self-insert-command "ins")
  ("o" nil "quit"))

Emulate org-mode export dispatch with hydra-ox

You can also look at that code to see how nested hydras work. Several other examples were added to hydra-examples.el.

Outro

I hope that you enjoy all the new features/fixes, and thanks to all the people that contributed to them. Happy hacking!

Some fun with Hydra

2015-03-21T00:00:00+01:00

The code from this post has very little application. But it's kind of fun, so I'll post it. Star Trek: TNG is one of my favorite shows, so I've added some TNG characters to one of the Hydra features that I'm testing.

`defhydradio` statement

(require 'hydra)
(defhydradio hydra-tng ()
  (picard "_p_ Captain Jean Luc Picard:")
  (riker "_r_ Commander William Riker:")
  (data "_d_ Lieutenant Commander Data:")
  (worf "_w_ Worf:")
  (la-forge "_f_ Geordi La Forge:")
  (troi "_t_ Deanna Troi:")
  (dr-crusher "_c_ Doctor Beverly Crusher:")
  (phaser "_h_ Set phasers to " [stun kill]))

The defhydradio macro is akin to a namespace construct that defines multiple variables that can assume only certain values (either t or nil by default), and functions to cycle those values.

`defhydradio` implementation

Here's what you may see after a macroexpand:

(progn
  (defvar hydra-tng/picard nil
    "_p_ Captain Jean Luc Picard:")
  (put (quote hydra-tng/picard)
       (quote range)
       [nil t])
  (defun hydra-tng/picard nil
    (hydra--cycle-radio (quote hydra-tng/picard)))
  (defvar hydra-tng/riker nil
    "_r_ Commander William Riker:")
  (put (quote hydra-tng/riker)
       (quote range)
       [nil t])
  (defun hydra-tng/riker nil (hydra--cycle-radio (quote hydra-tng/riker)))
  ;; ...
  (defvar hydra-tng/names
    '(hydra-tng/picard hydra-tng/riker
      hydra-tng/data hydra-tng/worf hydra-tng/la-forge
      hydra-tng/troi hydra-tng/dr-crusher hydra-tng/phaser)))

As you can see, each list passed to defhydradio:

gets a prefixed variable definition
gets a range property for the prefixed symbol
gets a prefixed function definition that cycles the variable value based on the range property
gets added to hydra-tng/names

`defhydra` statement

(defhydra hydra-tng (:foreign-keys run :hint nil)
  (concat (hydra--table hydra-tng/names 7 2
                        '("  % -30s %% -3`%s"
                          "%s %%`%s"))
          "\n\n")
  ("p" (hydra-tng/picard))
  ("r" (hydra-tng/riker))
  ("d" (hydra-tng/data))
  ("w" (hydra-tng/worf))
  ("f" (hydra-tng/la-forge))
  ("t" (hydra-tng/troi))
  ("c" (hydra-tng/dr-crusher))
  ("h" (hydra-tng/phaser))
  ("b" beam-down "beam down" :exit t)
  ("o" (hydra-reset-radios hydra-tng/names) "reset")
  ("q" nil "cancel"))

The interesting statement in place of the docstring will actually evaluate to this docstring:

"  _p_ Captain Jean Luc Picard:   % -3`hydra-tng/picard^^^^    _h_ Set phasers to  %`hydra-tng/phaser
  _r_ Commander William Riker:   % -3`hydra-tng/riker^^^^^
  _d_ Lieutenant Commander Data: % -3`hydra-tng/data^^^^^^
  _w_ Worf:                      % -3`hydra-tng/worf^^^^^^
  _f_ Geordi La Forge:           % -3`hydra-tng/la-forge^^
  _t_ Deanna Troi:               % -3`hydra-tng/troi^^^^^^
  _c_ Doctor Beverly Crusher:    % -3`hydra-tng/dr-crusher

"

The first line overflows a bit, but it's clear what it is. There's some flexibility in using hydra--table, since you can:

redefine the row-column format (e.g. from 7x2 to 5x3)
add more variables to hydra-tng/names

Note also, that since hydra-tng/names holds all the names, and all the names know their default values through range, it's possible to reset them all at once with hydra-reset-radios.

Finally, here's a simple implementation of beam-down:

(defun beam-down ()
  (interactive)
  (message
   "Beaming down: %s."
   (mapconcat
    #'identity
    (delq nil
          (mapcar
           (lambda (p) (when (symbol-value p)
                    (substring (symbol-name p) 10)))
           '(hydra-tng/picard
             hydra-tng/riker
             hydra-tng/data
             hydra-tng/worf
             hydra-tng/la-forge
             hydra-tng/troi
             hydra-tng/dr-crusher)))
    ", and ")))

(global-set-key (kbd "C-c C-,") 'hydra-tng/body)

Outro

And that's it. There actually is an application of defhydradio in hydra-ox.el. It's not fully finished, but you can already try it as an alternative to org-mode export dispatch widget, most things are working.

Emacs package management

2015-03-20T00:00:00+01:00

Lately, I've been spending some time to automate and publish my Emacs config. Being able to quickly reproduce your config has many advantages, the main one being that you no longer have to spend time to make your config reproducible.

Happily, most of my config is already published in many packages, I only have to figure out a nice layer to glue them together. Below, I'll show some automation for the packages managed by package.el.

Step 1: get the main directory

This is an important step that many other peoples' configs miss, even the ones that are designed to be distributed. You can't just assume that the config will be located in ~/.emacs.d and rely on Emacs defaults. Instead, it's nice to be able to clone the config into a random directory and launch an Emacs from there, without messing with the currently installed Emacs.

It's also useful for having multiple repositories for different versions of Emacs. ELPA packages are byte-compiled, and the byte code can be incompatible between versions (for instance, 24.3 and 24.4). Having two independent checkouts with ELPA directory auto-generated really helps in that case.

So here is the code to get the main directory and define an ELPA directory with respect to that:

(defconst emacs-d
  (file-name-directory
   (file-chase-links load-file-name))
  "The giant turtle on which the world rests.")

(setq package-user-dir
      (expand-file-name "elpa" emacs-d))

Step 2: decide what you like

Next, I initialize the package and define some of the packages that I like, omitting the dependencies that they bring. Note that the code of the whole post is stored in a separate file packages.el that is not intended to be loaded on start up, so it's fine to call package-refresh-contents here:

(package-initialize)
(setq package-archives
      '(("melpa" . "http://melpa.milkbox.net/packages/")
        ("gnu" . "http://elpa.gnu.org/packages/")))
(package-refresh-contents)

(defconst ora-packages
  '(auto-compile auto-yasnippet ace-link ace-window
    company eclipse-theme flx-ido function-args
    headlong ido-occasional ido-vertical-mode lispy
    magit smex swiper use-package guide-key
    powerline projectile slime cider worf
    org-download make-it-so ukrainian-holidays
    netherlands-holidays j-mode)
  "List of packages that I like.")

Step 3: install and upgrade

The install step is pretty straightforward: install a package unless it's already installed. I tried to do something fancier for the upgrade, but in the end it was much more simple to just call the interactive interface. The last two lines are basically equivalent to pressing Uxy interactively:

;; install required
(dolist (package ora-packages)
  (unless (package-installed-p package)
    (package-install package)))

;; upgrade installed
(save-window-excursion
  (package-list-packages t)
  (package-menu-mark-upgrades)
  (package-menu-execute t))

Step 4: make it callable

Finally, I just create a Makefile with the following contents:

emacs ?= emacs
upgrade:
    $(emacs) -batch -l packages.el

run:
    $(emacs) -Q -l init.el

up: upgrade run

Thanks to the first line, I can issue stuff like this on the shell:

emacs=emacs24 make up

This will use the emacs24 executable, instead of whatever emacs points to. Since the up target depends on upgrade and run targets, they will be executed in that order:

the upgrade will install / upgrade all packages in a non-interactive Emacs
the run target will start an interactive Emacs with already updated packages

I really like putting stuff in Makefiles, since they are very flexible, yet so easy to call. In the very same Makefile, I have a profile target from the post on profiling Emacs start up. I also wrote two packages related to Makefiles: helm-make and make-it-so. The latter one is actually very interesting and deserves its own post, I should maybe just clean it up a bit.

Outro

I'll just cite Gall's law here:

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.

I think it applies from both sides w.r.t. my Emacs config: it kind of works, but I really wish it was reproducible from the start, before making it complex.

A new Swiper demo on Youtube

2015-03-19T00:00:00+01:00

Youtube video

Today, I've fixed a few bugs in both swiper and ivy. Finally, the number of candidates display has also been added. You can see the whole thing in the one minute video demo.

Here are the bindings that I'm using:

(global-set-key "\C-r" 'swiper)
(global-set-key "\C-s" 'swiper)

Integration tests

I've also added some integration tests, if you're interested. I didn't know how to do exactly this type of testing before (when there's input from minibuffer). Turns out, it's pretty easy to do using execute-kbd-macro:

(require 'ert)

(defvar ivy-expr nil
  "Holds a test expression to evaluate with `ivy-eval'.")

(defvar ivy-result nil
  "Holds the eval result of `ivy-expr' by `ivy-eval'.")

(defun ivy-eval ()
  "Evaluate `ivy-expr'."
  (interactive)
  (setq ivy-result (eval ivy-expr)))

(global-set-key (kbd "C-c e") 'ivy-eval)

(defun ivy-with (expr keys)
  "Evaluate EXPR followed by KEYS."
  (let ((ivy-expr expr))
    (execute-kbd-macro
     (vconcat (kbd "C-c e")
              (kbd keys)))
    ivy-result))

(ert-deftest ivy-read ()
  (should (equal
           (ivy-read "pattern: " nil)
           nil))
  (should (equal
           (ivy-read "pattern: " '("42"))
           "42"))
  (should (equal
           (ivy-with '(ivy-read "pattern: " '("blue" "yellow"))
                     "C-m")
           "blue"))
  (should (equal
           (ivy-with '(ivy-read "pattern: " '("blue" "yellow"))
                     "y C-m")
           "yellow"))
  (should (equal
           (ivy-with '(ivy-read "pattern: " '("blue" "yellow"))
                     "y DEL b C-m")
           "blue"))
  (should (equal
           (ivy-with '(ivy-read "pattern: " '("blue" "yellow"))
                     "z C-m")
           nil)))

Outro

Give the package a try, if you haven't yet. You can get it from MELPA.

Find file in a Git repo with ivy

2015-03-18T00:00:00+01:00

I'm really enjoying using ivy for matching stuff.

Here is today's addition:

(defun couns-git ()
  "Find file in the current Git repository."
  (interactive)
  (let* ((default-directory (locate-dominating-file
                             default-directory ".git"))
         (cands (split-string
                 (shell-command-to-string
                  "git ls-files --full-name --")
                 "\n"))
         (file (ivy-read "Find file: " cands)))
    (when file
      (find-file file))))

This one will allow you to find a file in your Git repository. I've bound it like this:

(global-set-key (kbd "C-c f") 'couns-git)

Here's how it looks like for selecting a file in the Emacs repo:

The speed isn't an issue for 3500 candidates, although I should try to add the number of candidates display pretty soon. It's just that there isn't a good spot in the minibuffer to show that.

I've also updated ivy-next-line and ivy-previous-line to switch to the previous history element in case ivy-text is empty. This is the exact behavior of isearch, so if you bind swiper to C-s and C-r like I do, you'll find that C-s C-s and C-r C-r work as expected. Thanks to @johnmastro for the suggestion.

Here's the current state of the keymap:

(defvar ivy-minibuffer-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "C-m") 'ivy-done)
    (define-key map (kbd "C-n") 'ivy-next-line)
    (define-key map (kbd "C-p") 'ivy-previous-line)
    (define-key map (kbd "C-s") 'ivy-next-line)
    (define-key map (kbd "C-r") 'ivy-previous-line)
    (define-key map (kbd "SPC") 'self-insert-command)
    (define-key map (kbd "DEL") 'ivy-backward-delete-char)
    (define-key map (kbd "M-<") 'ivy-beginning-of-buffer)
    (define-key map (kbd "M->") 'ivy-end-of-buffer)
    (define-key map (kbd "M-n") 'ivy-next-history-element)
    (define-key map (kbd "M-p") 'ivy-previous-history-element)
    (define-key map (kbd "C-g") 'minibuffer-keyboard-quit)
    map)
  "Keymap used in the minibuffer.")

You can also try counsel for completing Elisp and couns-clj for completing Clojure. As you can see, the implementation is very simple: you just get a list of strings, and you're done.

If you want to implement some ivy completion for your favorite mode, I recommend to find the corresponding ac-source and see where it gets its list of strings.

More Info

2015-03-17T00:00:00+01:00

I really liked Marcin Borkowski's post on Info dispatch, where he describes how to open several *info* buffers for the most commonly used manuals. However, as I tried to call one of these functions today, I forgot the key binding.

Hydra to the rescue!

Here's what I've come up with:

(defun ora-open-info (topic bname)
  "Open info on TOPIC in BNAME."
  (if (get-buffer bname)
      (progn
        (switch-to-buffer bname)
        (unless (string-match topic Info-current-file)
          (Info-goto-node (format "(%s)" topic))))
    (info topic bname)))

(defhydra hydra-info-to (:hint nil :color teal)
  "
_o_rg e_l_isp _e_macs _h_yperspec"
  ("o" (ora-open-info "org" "*org info*"))
  ("l" (ora-open-info "elisp" "*elisp info*"))
  ("e" (ora-open-info "emacs" "*emacs info*"))
  ("h" (ora-open-info "gcl" "*hyperspec*")))

(define-key Info-mode-map "t" 'hydra-info-to/body)

The Plan

I already have the <f1> i key binding hard wired to my fingers. So after I'm in any Info buffer, I plan to press t and get this dispatch:

Getting the Hyperspec

I've heard people lauding HTML while dumping on Info. I'd suggest them to compare the Common Lisp Hyperspec web site to this info file extracted from there. Their contents are identical, but it's easier and more pleasant to use Info.

After I downloaded the file, I extracted it to ./etc/info/gcl.info, where . is my emacs-d. Then I just added this directory to the Info path:

(setq Info-additional-directory-list
      (list (expand-file-name "etc/info/" emacs-d)))

Outro

Reading Info is pleasant and educational. In case you're new to Info, there's Info for Info. In Info format! Just press <f1> i h.

Try J

2015-03-16T00:00:00+01:00

Intro

I imagine that if you're reading this blog, you like to tinker with Emacs. And people who like to tinker with stuff probably also like to learn new programming languages, just for fun. In that case, if you ever want to learn a non-mainstream language, I highly recommend J.

From its homepage:

J is a modern, high-level, general-purpose, high-performance programming language. J is portable and runs on Windows, Unix, Mac, both as a GUI and in a console. J systems can be installed and distributed for free.

The Appetizer

Things J has going for it that are high on my list:

GPL licensed source (although it's gibberish to read)
a REPL
short code
high performance

What attracted me to J in the first place is that it consistently has the shortest solutions (and fast-running) on Project Euler. What kept me going after the initial wow-effect, was the extremely elegant standard functions implementation dividing things into verbs, adverbs, and conjunctions.

Something impressive: a Sudoku solver

This code is taken from the ob-J page that I wrote some time ago (you can find a lot of additional info there):

#+begin_src J :exports both
i =: ,((,|:)i.9 9),,./,./i.4$3
c =: (#=[:#~.)@-.&0
t =: [:(([:*/_9:c\])"1#])i&{+"1 1(>:i.9)*/[:i&=i.&0
r =: [:,`$:@.(0:e.,)[:;(<@t)"1
s =: 9 9&$@r@,
]m =: 9 9 $"."0'200370009009200007001004002050000800008000900006000040900100500800007600400089001'
s m
#+end_src

#+RESULTS:
#+begin_example
2 0 0 3 7 0 0 0 9
0 0 9 2 0 0 0 0 7
0 0 1 0 0 4 0 0 2
0 5 0 0 0 0 8 0 0
0 0 8 0 0 0 9 0 0
0 0 6 0 0 0 0 4 0
9 0 0 1 0 0 5 0 0
8 0 0 0 0 7 6 0 0
4 0 0 0 8 9 0 0 1

2 8 4 3 7 5 1 6 9
6 3 9 2 1 8 4 5 7
5 7 1 9 6 4 3 8 2
1 5 2 4 9 6 8 7 3
3 4 8 7 5 2 9 1 6
7 9 6 8 3 1 2 4 5
9 6 7 1 4 3 5 2 8
8 1 3 5 2 7 6 9 4
4 2 5 6 8 9 7 3 1
#+end_example

It's pretty amazing that the whole implementation, not counting the example input matrix, takes only 169 characters. You can also see how functional the language is.

Something simpler: a factorial

To have a more simple example, here's how to write down incrementally the factorial of 20:

#+begin_src J
i.20
#+end_src

#+RESULTS:
: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

#+begin_src J
1 + i.20
#+end_src

#+RESULTS:
: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

#+begin_src J
*/ 1 + i.20
#+end_src

#+RESULTS:
: 2432902008176640000

The spaces are optional, I've only included them to make the code more clear.

Something visual: a sine plot

#+begin_src J
load 'plot'
plot 1 o. 0.1 * i.200
#+end_src

By simply pressing C-c C-c on this source block you get this image generated and opened in your browser:

The Emacs Tooling

As mentioned above, there's org-mode babel support for J, including session interaction. More importantly, there is j-mode. The same package also provides a REPL via jconsole.

Additionally, I wrote down a learning/assisting tool helm-j-cheatsheet. Here's one of the screenshots:

It allows to:

insert a function by English name
look up the English name of the function by symbol
open the J documentation for a function

Outro

J is a very cool language to try and I hope you give it a go. I haven't yet managed to find a nice use for it, but you could say that, just as learning LISP, learning J can make you better at other languages.

Search for things with apropos

2015-03-15T00:00:00+01:00

Until recently, I didn't even know that apropos was an actual word. I thought that it was just some gibberish that Emacs hackers invented to name a command. Turns out, it actually has a very appropriate meaning:

apropos

preposition
with reference to; concerning.

An apropos Hydra

I've just added this one to hydra-examples.el.

(defhydra hydra-apropos (:color blue
                         :hint nil)
  "
_a_propos        _c_ommand
_d_ocumentation  _l_ibrary
_v_ariable       _u_ser-option
^ ^          valu_e_"
  ("a" apropos)
  ("d" apropos-documentation)
  ("v" apropos-variable)
  ("c" apropos-command)
  ("l" apropos-library)
  ("u" apropos-user-option)
  ("e" apropos-value))

I recommend to bind it like this:

(global-set-key (kbd "C-c h") 'hydra-apropos/body)

Customary screenshot:

As you can see, there are a total of 7 apropos functions available. The most useful ones are apropos, apropos-command and apropos-variable. But apropos-value is very interesting as well: it will not match an object name with the input, but instead search for all objects whose contents match input. So, for instance, if you see something like "error 42" come up, and you don't know where it's coming from, it's likely that some variable holds the value 42. And that's when you use apropos-variable.

Apropos is like old-school googling, and I find it highly useful in finding the Emacs information that I need. I hope that you will find it useful as well. Happy hacking!

More on swiper and ivy

2015-03-14T00:00:00+01:00

I'll describe two new things in swiper and ivy that happened within the day. Although you can install them separately from MELPA, they still live in a single git repository.

`swiper` / `ivy` faces now inherit the standard ones

It's a good idea by @purcell, and I tend to agree. So now, there are six faces that inherit highlight, isearch-lazy-highlight-face, isearch and match faces between them. The advantage is that most themes re-define the above four faces as they see fit, so the swiper faces will fit in better without customization.

Still, I really enjoy the previous faces that were derived from the Swiper sprite. You can have them as part of eclipse-theme. The theme creators can just copy them verbatim to a light theme if they so choose.

By the way, it seems that not all Emacs users are aware that you can customize faces. You can do so interactively for most popular packages. For example, after M-x customize-group swiper, you get a GUI for selecting most configurable things for swiper, including the faces.

The GUI will generate the code that looks something like this:

(custom-set-faces
  '(ivy-current-match ((t (:background "#e5b7c0")))))

Elisp completion with `ivy`

The code to complete Elisp code at point is very simple:

(defun counsel ()
  "Elisp completion at point."
  (interactive)
  (let* ((bnd (bounds-of-thing-at-point 'symbol))
         (str (buffer-substring-no-properties (car bnd) (cdr bnd)))
         (candidates (all-completions str obarray))
         (ivy-height 7)
         (res (ivy-read (format "pattern (%s): " str)
                        candidates)))
    (when (stringp res)
      (delete-region (car bnd) (cdr bnd))
      (insert res))))

The only function above that isn't one of the familiar primitives is ivy-read. But even that one has a similar interface to that of completing-read or ido-completing-read. I was using helm-lisp-completion-at-point before, but counsel is much less obtrusive, while offering comparable speed and convenience:

The default minibuffer height for ivy is set to 10 via ivy-height. It's quite reasonable all-around, but for counsel I've set it to 7 via a let binding.

Swiper now has an ivy back end

2015-03-13T00:00:00+01:00

Intro

Just three days ago, I wrote swiper and introduced it in a post. And while swiper solved the problem of helm-swoop being awkward for me to use, swiper's code itself is pretty awkward, since even after using helm a dozen times in my packages, I'm still not well-versed in its internals.

And, apparently, there are people who don't like helm because it updates a lot. I don't know if it counts as a viable complaint, but I do agree that the helm update time is quite long. So I wrote down an alternative completion back end for swiper. It looks quite similar to ido-vertical-mode, although it is completely unrelated to ido. In fact, the matching algorithm currently is similar to helm-match-plugin: "for example" is transformed into "\$for\$.*\$example\$".

The Details

Currently, in the ivy version of swiper only the anchoring algorithm is missing. Anchoring is what I call the process of selecting a close candidate when the number of candidates changes. It seems that helm doesn't implement an anchoring algorithm, so both helm-swoop and swiper implement their own. I don't know how easy it would be to write down the proper generic thing, my current implementation for the helm version of swiper is quite hacky.

Just to explain to you what needs to be done. Suppose there's an input "ab" that matches 50 candidates, and the candidate number 42 is the current one. Now, if the user types one char to make the input into "abc", the number of candidates has changed to 10, and the candidate that was current previously doesn't match any more. It is up to the matcher code to decide which of the 10 candidates has to be current now. Usually it doesn't matter much, but in the case of swiper it matters since the point will be moved to the current candidate in the original window.

In any case, there's still a lot of things that have to be done for ivy, but I think that it's quite usable now. Actually, I've already added it to my bindings:

(global-set-key "\C-s" 'swiper)

Here's how it looks like:

And here's an example of completion in dired:

You need to have Emacs 24.4 in order to get a nicer highlight in the minibuffer that uses add-face-text-property instead of the old propertize.

There's a custom variable that decides the height of the minibuffer window, you can set it as you like:

(defcustom ivy-height 10
  "Number of lines for the minibuffer window."
  :type 'integer)

Outro

Give the new back end a go, see if you like it. It looks quite pretty and minimalist to me, but I'm biased since I made it.

ace-window display mode

2015-03-12T00:00:00+01:00

Intro

Today, I'll describe a quite recent addition to ace-window, which comes from the idea by @deftsp:

Why not show the ace-window dispatch keys in the mode line all the time?

Certainly, there's no reason not to have this option, and it actually makes the whole interface better, since it becomes less feedback-based:

You glance at a window that you want.
You know which key you have to press before you call ace-window
You make a single-step call instead of:
- press ace-window shortcut,
- read the dispatch char,
- press the dispatch char.

The feature is implemented as ace-window-display-mode - a minor mode that you can toggle on or off whenever you feel like it.

Here's how it looks like:

As you can see, I've made aw-keys list short on purpose, just to show you that the full path will be displayed. See, for instance, the *scratch* window: its path is gf.

Implementation

Since the implementation is quite short, I'll post it here and go over a few things that might interest people who write Elisp (on some level, please don't mock me for being obvious).

As per request of a curious reader, I've updated the code with the comments from below. Don't try this at home, excessive commenting is bad style.

;; Something that modifies the Emacs behavior should
;; preferrably be implemented as a minor mode.
;;;###autoload
(define-minor-mode ace-window-display-mode
    "Minor mode for showing the ace window key in the mode line."
  ;; And since this minor mode isn't tied to a particular
  ;; buffer, I declare it as global.
  ;;
  ;; An interesting quirk is that I have to put *something*
  ;; between the docstring and the body, otherwise it won't
  ;; work.
  :global t
  ;; Dispatch on the variable symbol of the mode -
  ;; `ace-window-display-mode`.  `define-minor-mode' will
  ;; define both a variable and function symbol.
  (if ace-window-display-mode
      (progn
        ;; Update the window parameters
        (aw-update)
        ;; Since `mode-line-format' is a buffer-local
        ;; variable, I set it with `set-default', in order
        ;; for the change to not just happen in the current
        ;; buffer.
        (set-default
         'mode-line-format
         `((ace-window-display-mode
            (:eval (window-parameter (selected-window)
                                     'ace-window-path)))
           ,@(default-value 'mode-line-format)))
        (force-mode-line-update t)
        ;; Each time a window is created or deleted, Emacs
        ;; will run the `window-configuration-change-hook' -
        ;; exactly what I need to update `mode-line-format'.
        (add-hook 'window-configuration-change-hook 'aw-update))
    (set-default
     'mode-line-format
     (assq-delete-all
      'ace-window-display-mode
      (default-value 'mode-line-format)))
    (remove-hook 'window-configuration-change-hook 'aw-update)))

(defun aw-update ()
  "Update ace-window-path window parameter for all windows."
  (avy-traverse
   (avy-tree (aw-window-list) aw-keys)
   (lambda (path leaf)
     ;; Use `set-window-parameter' to store a variable for
     ;; each window.  Buffer local variables would not work
     ;; here, since one buffer can be displayed in multiple
     ;; windows, and those would need a different key each.
     (set-window-parameter
      leaf 'ace-window-path
      (propertize
       (apply #'string (reverse path))
       'face 'aw-mode-line-face)))))

Since I'm writing something that modifies Emacs behavior when it's enabled, I first try to implement it as a minor mode. And since this minor mode isn't tied to a particular buffer, I declare it as global.

An interesting quirk is that I have to put something between the docstring and the body, otherwise it won't work. In this case, I put :global t.

Next, follows that standard dispatch on the variable symbol of the mode - ace-window-display-mode. The define-minor-mode macro will make both variable and function definition for the symbol it's given:

the variable is used to check if the mode is on.
the function is used to turn the mode on / off.

Note the use of assq-delete-all: this is for when some other package modifies the mode-line-format after ace-window does. In that case, ace-window's entry wouldn't be the first one any more.

Since mode-line-format is a buffer-local variable, I set it with set-default, in order for the change to not just happen in the current buffer.

Each time a window is created or deleted, Emacs will run the window-configuration-change-hook - exactly what I need to update mode-line-format.

One final trick is to use set-window-parameter to store a variable for each window. Buffer local variables would not work here, since one buffer can be displayed in multiple windows, and those would need a different key each.

I really like how the avy-tree / avy-traverse interface ended up as: the same functions are used for selecting window and setting mode-line-format.

Outro

I hope that you enjoy the update, and keep those interesting ideas coming!

Some git / magit / github tricks

2015-03-11T00:00:00+01:00

Of course, I mean illusions not tricks.

Illusion 1: jump to a magit repository

This is just a copy-paste of the code from this post by Iqbal Ansari.

(setq magit-repo-dirs
      (mapcar
       (lambda (dir)
         (substring dir 0 -1))
       (cl-remove-if-not
        (lambda (project)
          (unless (file-remote-p project)
            (file-directory-p (concat project "/.git/"))))
        (projectile-relevant-known-projects))))

Basically it's just taking projectile's record of known projects, and then filtering it by whether that project has .git in its root.

To get a selection of repositories, call with C-u M-x magit-status. And don't forget to choose ido completion:

(setq magit-completing-read-function 'magit-ido-completing-read)

And here's how I use this in a dispatch:

(defhydra hydra-helm (:color blue)
  "helm"
  ("f" projectile-find-file "file")
  ("w" helm-org-wiki "wiki")
  ("g" (let ((current-prefix-arg 4))
         (call-interactively #'magit-status))
       "git")
  ("l" helm-locate "locate")
  ("q" nil "quit"))
(global-set-key "κ" 'hydra-helm/body)

If you're wondering what the letter in global-set-key is, it's the Greek letter kappa (see the post on my Xmodmap setup).

Illusion 2: quickly get Github pull requests on your system

I learned this from some HN post that I can't find now. Basically, you have to open your .git/config file and find the following contents:

[remote "origin"]
    url = git@github.com:abo-abo/hydra.git
    fetch = +refs/heads/*:refs/remotes/origin/*

Then, modify it by adding one line (same for all repositories):

[remote "origin"]
    url = git@github.com:abo-abo/hydra.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/pull/origin/*

Now, if you issue:

git fetch --all

You can operate on your pull requests like so:

git merge refs/pull/origin/20

Here, 20 is the issue number. And after merging I finally get access to magit and ediff and all that jazz to see what the change is actually about. Before I learned this, I had to manually add remotes with magit-add-remote. And even before that, I was just clicking the merge button after thoughtfully browsing the diff in Firefox. Trust me, ediff is orders of magnitude better.

Illusion 3: edit a Github wiki in Emacs

Of course, I was always editing it in Emacs with It's All Text Firefox plugin. But when I wanted to add an image, I actually read the manual and found out that you can simply clone the wiki:

git clone https://github.com/abo-abo/hydra.wiki.git

Or with the ssh style, in order to not type the user name and password on pushing:

git clone git@github.com:abo-abo/hydra.wiki.git

By the way, today I've made a very large overhaul of hydra's README.md. So if you wanted to start writing your own hydras, but were hesitant because of the lack of documentation, now is the time to start.

If you figure out something that you think is worth documenting, you can immediately leave it on the wiki. By the way, here's the syntax for including an image, if you were wondering:

![hydra-helm](images/hydra-helm-unite.png)

You upload a file simply by adding it to the repository. Look Ma, no Imgur!

This is actually an issue that I ran into, when I was less experienced. I included some one megabyte gifs in the lispy repository to refer to them in README.md. Just a few of them resulted in a very uncomfortable cloning time, which is an issue for Travis CI and, you know, humans. Finally, I had to resort to bfg-repo-cleaner to remove the gifs from the repo history. It could all be avoided if I just posted all images on the wiki and linked to them in README.md.

Outro

I hope that you find these illusions useful to make you a better Emacs magician. Happy hacking!

Introducing Swiper

2015-03-10T00:00:00+01:00

I like the idea of helm-swoop, but it somehow has minor annoyances that stop me from using it, like automatic helm-input, and especially the circular candidates. Or maybe it's just NIH talking. Anyway, I'm rolling my own, and it's called swiper.

Swiper in action

Here's how it looks like:

As you can see, the search string "dec fun pro" is transformed into a regex "\$dec\$.*\$fun\$.*\$pro\$", and each group in the matches is highlighted with a different face. This is quite similar to the way re-builder does it. In fact it's possible to use swiper as a poor man's re-builder (since it matches only single lines).

I'm doing my own matching this time, as the part-swapping behavior of helm-match-plugin is more annoying than useful.

Also note that:

The whole *swiper* buffer is fully syntax highlighted.
The appropriate parts of the matches are highlighted as well.

Swiper in a `dired` buffer

Here's another screenshot:

It appears that helm is ignoring the display of file attributes, since they have a sort of invisible property set. I kind of like this behavior.

See how the faces are recycled

I've defined only 4 faces currently (foxes aren't unicorns, the palette is quite limited), so they loop about if you have many groups:

Yup, the technology is there. Although a powerline theme for the helm mode line is still missing.

lispy point history

2015-03-09T00:00:00+01:00

It was kind of disappointing to summarize in the last post that there weren't many new features for lispy 0.24.0. So I thought long and hard and came up with something quite obvious: since lispy offers commands to quickly manipulate point and mark, it should offer one to quickly restore them.

Here's the bulk of the new code:

(defvar lispy-pos-ring (make-ring 200)
  "Ring for point and mark position history.")
(ring-insert lispy-pos-ring 1)

(defun lispy--remember ()
  "Store the current point and mark in history."
  (if (region-active-p)
      (let ((bnd (lispy--bounds-dwim)))
        (unless (equal bnd (ring-ref lispy-pos-ring 0))
          (ring-insert lispy-pos-ring bnd)))
    (unless (eq (point) (ring-ref lispy-pos-ring 0))
    (ring-insert lispy-pos-ring (point)))))

(defun lispy-back ()
  "Move point to a previous position"
  (interactive)
  (if (zerop (ring-length lispy-pos-ring))
      (user-error "At beginning of point history")
    (let ((pt (ring-remove lispy-pos-ring 0)))
      (if (consp pt)
          (lispy--mark pt)
        (deactivate-mark)
        (goto-char pt)))))

Here, I'm using lispy-pos-ring made with make-ring to store the last 200 point and mark positions. In Elisp, a ring is basically a stack backed by a vector. When the vector space overflows, the older stuff is overwritten.

In this ring I store each time either the point, or a cons of the point and mark if the region is active. This way possible to restore the region even if it was deactivated several movement commands ago.

I've put lispy--remember into the most used navigation commands:

j - lispy-down
k - lispy-up
h - lispy-left
l - lispy-right
f - lispy-flow
i - lispy-mark-car (when the region is active)
a - lispy-ace-paren

And lispy-back is now bound to b. The previous binding of b - lispy-store-region-and-buffer is now bound to xB (quite close to B - the binding for lispy-ediff-regions).

I really like the new command, it's especially useful to reverse h and l. Previously, they could be reversed with f, but that can get annoying if you have to press it many times. This results in a much more relaxed editing - I know that whatever I press, I can restore the point position quickly if needed.

This feature is added to the already present list of safeguards:

j and k are guaranteed not to exit the parent list.
> and < are guaranteed not to exit the parent list.
C reverses itself.

Here's a recipe to copy the third item of the current list and move the point back: 4mnb. You can use it to copy a function's docstring if you're in Elisp. You'll need 3mnb for Clojure, since it weirdly has the docstring before the arguments. I think it's pretty cool: by typing 3mnb I'm basically calling (kill-new (caddr (current-sexp))) on my own code.

lispy 0.24.0 is out

2015-03-08T00:00:00+01:00

The last release was a month ago, and there have been 70 commits to master since then. If you're not familiar with lispy, see my intro post for version 0.21.0. I'll just copy the release notes here, while adding a few things.

Fixes

DEL behaves properly after a string and one space.
C-k works better for expressions preceded with "#".
3 should not add a space when there is one already.
# will not add a space after a comma.
C-j works better in comments after a quote.
lispy--eval-elisp-form first arg is now named lispy-form instead of form. It was impossible to evaluate an unrelated form variable with the previous behavior.
F again works properly when jumping to a jar (e.g. to defn) from Clojure source.
C-k won't call delete-region in some obscure branches.

Enhancements

P (lispy-paste) will add a newline when called from start of line. This way, nP becomes equivalent to c (lispy-clone). Of course, it's more flexible: you can do e.g. nkP.
xb (lispy-bind-variable) now works on regions as well. Use it to bind the current sexp or region as a let-bound variable: it will put you in iedit. When you're done with iedit, press M-m (lispy-mark-symbol) to exit iedit. If you need to move the let binding around, use a combination of C (lispy-convolute) and h (lispy-left).
g will ignore loaddefs.el for Elisp.
M-m works better in unbalanced buffers, which should be an rare thing.
add defhydra to lispy-tag-arity: now g will recognize defhydra statements.
The tag logic was improved to do less parsing.
lispy-outline was updated to match the standard ^;;; outline regex. Try pressing I in e.g. org.el, it's quite beautiful.
All lispy-eval functions will preserve the match data.
> will delete the extra whitespace while slurping.
Added undercover/Coveralls test coverage report.
H (lispy-ace-symbol-replace) is now a Hydra: type h to delete more, type u to undo.
Q (lispy-ace-char) now uses avy to jump. This change allows to cover this function with a test.

New features

`p` can now iterate `dolist` variables in Elisp.

(defun range (a b)
  (message "called range")
  (number-sequence a b))
(dolist |(i (range 1 3))
  (message "i=%d" i))

Pressing p with point where | is, will

call range and set i to 1
set i to 2
set i to 3
set i to nil
call range and set i to 1

This is another step toward edebug-less debugging, adding to special behavior for let, cond and labels. Remember that you can drop out of edebug with Z (lispy-edebug-stop). This function will take the current function arguments that edebug provides, store them in top-level, and exit edebug. This is really cool for setting up entry conditions for a function that you want to debug, or even a function with an empty body that you want to write. Why am I so eager to exit edebug? Because it puts the code in read-only mode, which is quite restrictive.

Incompatible changes

lispy-helm-columns is now a list '(60 80). The first number is the width of the tag name column, the second number is the width of both tag name and tag file. The tag name column is left-aligned, while the file column is right-aligned.
j and k should now move to outline when at beginning of comment. The previous behavior was to look for the first sexp in the direction. You can still do that with f.
I (lispy-shiftab) is now a two-way cycle, instead of three-way, like org-mode. The contents can be obtained with C-u I or C-u C-TAB.

Outro

It seems that lispy is winding down feature-wise, which is a good thing, because I'm almost out of keys - there's only Y and U left.

Possible next steps would be to improve the test coverage (currently 48%) and the documentation. Perhaps I'll try to implement some automation for generating the function reference, or learn some texinfo and write an actual manual, see how ox-texinfo holds up.

I hope that you'll grow to enjoy lispy as much as I do. Happy hacking!

org-mode block templates in Hydra

2015-03-07T00:00:00+01:00

Here's a new Hydra for you:

(defhydra hydra-org-template (:color blue :hint nil)
  "
_c_enter  _q_uote    _L_aTeX:
_l_atex   _e_xample  _i_ndex:
_a_scii   _v_erse    _I_NCLUDE:
_s_rc     ^ ^        _H_TML:
_h_tml    ^ ^        _A_SCII:
"
  ("s" (hot-expand "<s"))
  ("e" (hot-expand "<e"))
  ("q" (hot-expand "<q"))
  ("v" (hot-expand "<v"))
  ("c" (hot-expand "<c"))
  ("l" (hot-expand "<l"))
  ("h" (hot-expand "<h"))
  ("a" (hot-expand "<a"))
  ("L" (hot-expand "<L"))
  ("i" (hot-expand "<i"))
  ("I" (hot-expand "<I"))
  ("H" (hot-expand "<H"))
  ("A" (hot-expand "<A"))
  ("<" self-insert-command "ins")
  ("o" nil "quit"))

(defun hot-expand (str)
  "Expand org template."
  (insert str)
  (org-try-structure-completion))

I bind it for myself like this:

(define-key org-mode-map "<"
  (lambda () (interactive)
     (if (looking-back "^")
         (hydra-org-template/body)
       (self-insert-command 1))))

This means that when I press < from the start of the line, a Hydra will be called instead of inserting <, otherwise < will be inserted.

As the default insert method for org-mode blocks is already pretty convenient, this Hydra is more of an illustration than anything, especially of the new :hint nil feature.

Just to remind you, each head has four placeholders:

key binding
body
hint
plist

When a Hydra is active, it will show its doc in the echo area in the bottom of the frame. This doc is composed of two parts: the body doc and the heads' doc. The body doc you specify yourself, the heads' doc is built by concatenating the key binding and the hint for each head into a (single) line.

If you don't specify a hint for a head, it's assumed to be ""; this head's binding will still be in the heads' doc. If you don't want a head's binding to be in the heads' doc, set the hint to nil. This is commonly done because a head is already documented in the body doc. It can sometimes become tedious to set all the hints to nil, for instance in the Hydra above, I would need to do it 13 times. Hence the :hint nil shortcut.

Here's how it looks like:

I'm not a Scrabble pro: clash for word score 10 is my result, although a longer word would break the nice column layout. The first two columns contain begin/end templates, while the third one contains the one-line templates.

Select the previous window with ace-window

2015-03-06T00:00:00+01:00

It's strange that I haven't implemented this feature before, as it's quite a common usage pattern:

You select a window with ace-window.
You do some stuff there.
You want to return the previous window.

`aw-flip-window`

In the step 3, you have to go though the whole aw-keys dispatch, only to select a window which can be pre-determined. Not any more, if you call aw-flip-window:

(defun aw-flip-window ()
  "Switch to the window you were previously in."
  (interactive)
  (aw-switch-to-window (aw--pop-window)))

So now, you could have a grid of 10 windows, select one of them with ace-window, and switch indefinitely between it and the previous window with ace-flip-window, while ignoring the other 8.

`aw-ignored-buffers`

Remember that if you have some window that you never want to switch to with ace-window, you can add it to aw-ignored-buffers:

(defcustom aw-ignored-buffers '("*Calc Trail*" "*LV*")
  "List of buffers to ignore when selecting window."
  :type '(repeat string))

It's not a big deal, but it's convenient at least for this scenario:

I start with one active window.
M-x calc; now I have three windows.
I can toggle back and forth between calc and the main window with ace-window without having to type aw-keys, since *Calc Trail* is ignored, so that makes only two total windows.

Selecting last window during the `ace-window` dispatch

This is a really cool feature, in my opinion: for all three actions - aw-select-window, aw-swap-window, and aw-delete-window, you can select the previous window as a target with the same key n. This is, of course, customizable:

(defcustom aw-flip-keys '("n")
  "Keys which should select the last window."
  :set (lambda (sym val)
         (set sym val)
         (setq aw--flip-keys
               (mapcar (lambda (x) (aref (kbd x) 0)) val))))

So you could have a whole list of bindings that select the previous window during the aw-keys dispatch. This is cool because there's no visual feedback necessary, so this binding can be easily added to the muscle memory. The bindings don't necessarily need to be single keys, anything with one chord, e.g. C-f, is acceptable.

Here's how I've set it up for myself:

(global-set-key "ν" 'ace-window)
(csetq aw-flip-keys '("n" "ν"))

This means that:

I can select the previous window with νν - a double call to ace-window.
I can swap with the previous window with ψνν, ψ calls universal-argument for me.
I can delete the previous window with ψψνν.

Outro

Thanks to @luciferasm for the idea, I hope you'll enjoy the new feature.

Testing your .emacs sanity

2015-03-05T00:00:00+01:00

Here's a little snippet that came up as a Stack Overflow answer once:

(defun ora-test-emacs ()
  (interactive)
  (require 'async)
  (async-start
   (lambda () (shell-command-to-string
          "emacs --batch --eval \"
(condition-case e
    (progn
      (load \\\"~/.emacs\\\")
      (message \\\"-OK-\\\"))
  (error
   (message \\\"ERROR!\\\")
   (signal (car e) (cdr e))))\""))
   `(lambda (output)
      (if (string-match "-OK-" output)
          (when ,(called-interactively-p 'any)
            (message "All is well"))
        (switch-to-buffer-other-window "*startup error*")
        (delete-region (point-min) (point-max))
        (insert output)
        (search-backward "ERROR!")))))

This function will quietly run a batch Emacs with your current config to see if it errors out or not.

in case that there were no start up errors, it will echo "All is well"
when there's an error, it will pop to a *startup error* buffer with the error description

The nice thing about this is that in case of an error you have a functional Emacs to fix that error, since fixing errors with emacs -Q is quite painful.

Another approach could be to just start a new Emacs instance, and close the window in case there isn't an error. So all that the code above does is automate closing the window (sort of, since the window never opens). Still, I think it's pretty cool. And you could attach it to the after-save-hook of your .emacs, or a timer.

You could even configure Emacs to send you an email in case it notices that there will be an error on the next start up. Or add the test to before-save-hook and abort the save in case it results in an error. That's some HAL 9000 level stuff right there:

I'm sorry Dave, I'm afraid I can't do that.

Eclipse theme

2015-03-04T00:00:00+01:00

I started using Emacs around 2010-2011 when I needed an environment for C++ and LaTeX. The default color theme was horrendous (it still is), and I don't fancy myself a designer, so I just copied a color theme of the thing that I was using previously: Eclipse.

This theme modifies almost nothing except the font lock faces, and looks reasonable while called with -nw, although I don't see why anyone wouldn't want to take advantage of what graphical Emacs has to offer.

Here's a sampler:

It's shown together with my fork of powerline. I'll try to merge it as a theme eventually, I'm delaying it because powerline isn't very easy to understand/modify.

Eclipse theme should be on MELPA soon, I hope you'll enjoy it. I've tried probably 30 themes on MELPA, but I just can't part with eclipse-theme. I'm guessing that it's a feeling that most theme creators share.

ace-window full path

2015-03-03T00:00:00+01:00

I just closed a really helpful issue for ace-window. Turns out that there's a plugin for vim called Easymotion that's very similar to ace-jump-mode. And that plugin doesn't highlight the leading chars one by one, but instead gives them all at once. Which is a pretty good idea, since it's more convenient to read the whole path at once and type it in at once rather than:

read one char
type one char
read one more char
type one more char
... (maybe more steps)

To turn on the new behavior:

(setq aw-leading-char-style 'path)

Although this will only have an effect once you have more than 10 windows. But this method really improves the functions from avy-jump.el. I've added some more commands and renamed the old ones since yesterday.

avy-jump demos

`avi-goto-char-2`

Here's how I like to bind avi-goto-char-2:

(global-set-key (kbd "C-'") 'avi-goto-char-2)

And here's the result of C-' bu:

As you can see, nothing is overwritten by the overlay - it's appended after the search chars. In the screenshot above, I have avi-background at nil; you can set it to t if you want a gray background.

`avi-goto-char`

After binding avi-goto-char:

(global-set-key (kbd "π") 'avi-goto-char)

Here's the result of π b:

`avi-goto-line`

After binding avi-goto-line:

(global-set-key (kbd "M-g f") 'avi-goto-line)

Here's the result of M-g f:

I've also added:

avi-copy-line
avi-move-line
avi-copy-region

These functions use the method of avi-goto-line to copy/move stuff. It might be useful for line-based text.

`avi-goto-word-0`

Here's the simple definition and the binding:

(defun avi-goto-word-0 ()
  "Jump to a word start in current window."
  (interactive)
  (let* ((avi-keys (number-sequence ?a ?z))
         (candidates (avi--regex-candidates "\\b\\sw")))
    (avi--goto
     (avi--process candidates #'avi--overlay-pre))))
(global-set-key (kbd "M-g e") 'avi-goto-word-0)

There might be quite a lot of candidates for this one, but there's no call to read-char. Here's what happens after M-g e:

`avi-goto-word-1`

Here's a version of it that reads one char:

(defun avi-goto-word-1 ()
  "Jump to a word start in current window.
Read one char with which the word should start."
  (interactive)
  (let ((candidates (avi--regex-candidates
                     (concat
                      "\\b"
                      (string (read-char "char: "))))))
    (avi--goto
     (avi--process candidates #'avi--overlay-pre))))
(global-set-key (kbd "M-g w") 'avi-goto-word-1)

Here's what happens after M-g w b:

Outro

Give the new functions a go and see if you like them. New ideas are welcome, especially pertaining to ripping off vim plugins. I did the vimtutor once, but I have no idea how vim plugins work. But it turns out that I like Easymotion.

ace-window without ace

2015-03-02T00:00:00+01:00

Today, ace-window is dropping the dependency on ace-jump-mode. Most of the dependency was already dropped in 0.7.0, when I had to fix ace-window to work better with defhydra.

The change will not be user-visible, unless you relied on some customizations of ace-jump-mode to transfer to ace-window. You'll be able to transfer your customizations to similarly named variables.

The reason for the move is that, due to the implementation of ace-jump-mode, it's hard to wrap its calls, since the function exits before any of the red chars are selected by the user. Also, ace-jump-mode uses its own defstructs for candidates while I'd rather have plain lists, but that's a minor issue.

New back end: avy.el

I tried to pinpoint the most generic algorithm that ace-jump-mode implements and wrote it down in avy. Here's the core of the implementation:

(defun avy-subdiv (n b)
  "Distribute N in B terms in a balanced way."
  (let* ((p (1- (floor (log n b))))
         (x1 (expt b p))
         (x2 (* b x1))
         (delta (- n x2))
         (n2 (/ delta (- x2 x1)))
         (n1 (- b n2 1)))
    (append
     (make-list n1 x1)
     (list
      (- n (* n1 x1) (* n2 x2)))
     (make-list n2 x2))))

(defun avy-tree (lst keys)
  "Coerce LST into a balanced tree.
The degree of the tree is the length of KEYS.
KEYS are placed appropriately on internal nodes."
  (let ((len (length keys)))
    (cl-labels
        ((rd (ls)
           (let ((ln (length ls)))
             (if (< ln len)
                 (cl-pairlis
                  keys
                  (mapcar (lambda (x) (cons 'leaf x)) ls))
               (let ((ks (copy-sequence keys))
                     res)
                 (dolist (s (avy-subdiv ln len))
                   (push (cons (pop ks)
                               (if (eq s 1)
                                   (cons 'leaf (pop ls))
                                 (rd (avy-multipop ls s))))
                         res))
                 (nreverse res))))))
      (rd lst))))

The first function, avy-subdiv, tries to split a number in terms of the base in a way that the most leaves have the lowest level:

(avy-subdiv 42 5)
;;=> (5 5 5 5 22)

(avy-subdiv 42 4)
;;=> (4 6 16 16)

(avy-subdiv 42 3)
;;=> (9 9 24)

(avy-subdiv 42 2)
;;=> (16 26)

And here's an example of what avy-tree produces:

(avy-tree
 '("Acid green" "Aero blue" "Almond" "Amaranth"
   "Amber" "Amethyst" "Apple green" "Aqua"
   "Aquamarine" "Auburn" "Aureolin" "Azure"
   "Beige" "Black" "Bronze" "Blue" "Burgundy" "Candy apple red")
 '(1 2 3 4))
;;=>
((1 (1 leaf . "Acid green")
    (2 leaf . "Aero blue")
    (3 leaf . "Almond")
    (4 leaf . "Amaranth"))
 (2 (1 leaf . "Amber")
    (2 leaf . "Amethyst")
    (3 leaf . "Apple green")
    (4 leaf . "Aqua"))
 (3 (1 leaf . "Aquamarine")
    (2 leaf . "Auburn")
    (3 leaf . "Aureolin")
    (4 leaf . "Azure"))
 (4 (1 leaf . "Beige")
    (2 leaf . "Black")
    (3 leaf . "Bronze")
    (4 (1 leaf . "Blue")
       (2 leaf . "Burgundy")
       (3 leaf . "Candy apple red"))))

I think the library turned out to be pretty clean, since it knows nothing of points, buffers or overlays, and imposes no restrictions on the type of leaf items and keys.

Some cool `avy`-based commands

I'll list them together with the code, so it's easier to see what they do. The basic customizable variable is this one:

(defcustom avy-keys '(?a ?s ?d ?f ?g ?h ?j ?k ?l)
  "Keys for jumping.")

Note that, while ace-jump-mode has 52 selection chars by default, I prefer to have only the 8 chars on the home row. This means that I'll usually have to go around one level deeper, but the characters are easy to find and press.

`avy-jump-double-char`

(defun avy-jump-double-char ()
  "Read two chars and jump to them in current window."
  (interactive)
  (avy--process (avy--regex-candidates
                 (string
                  (read-char "char 1: ")
                  (read-char "char 2: "))
                 (selected-window))
                #'avy--goto))

This one will read two chars and then offer avy-selection for the matches. This is a pretty sensible approach for a pool of 8 keys, since usually 3 chars total will be necessary, with the first two being in natural succession.

Here's a screenshot of me typing in a natural two-char sequence "do":

As you see, with 8 keys, 8 candidates will have depth 1, and another 8 candidates will have depth 2. The sorting preference is for the first candidates to have lower depth.

`avy-jump-line`

(defun avy-jump-line ()
  "Jump to a line start in current buffer."
  (interactive)
  (let ((we (window-end))
        candidates)
    (save-excursion
      (goto-char (window-start))
      (while (< (point) we)
        (push (cons (point) (selected-window))
              candidates)
        (forward-line 1)))
    (avy--process (nreverse candidates)
                  #'avy--goto
                  t)))

This one is quite nice, since I always have less than 8*8=64 lines in any window. Here's how it looks like:

I removed the gray background, since the leading chars are always in an expected position.

`avy-jump-isearch`

Saving the most clever one for last:

(defun avy-jump-isearch ()
  "Jump to one of the current isearch candidates."
  (interactive)
  (let ((candidates
         (mapcar (lambda (x) (cons (1+ (car x))
                              (cdr x)))
                 (avy--regex-candidates isearch-string))))
    (avy--process candidates #'avy--goto t)
    (isearch-done)))
(define-key isearch-mode-map "'" 'avy-jump-isearch)

I don't mind not being able to isearch-forward-regexp for a single quote without using C-q (quoted-insert). In return, I get the ability to very quickly jump to a search candidate on screen. I like this command the most. In case when there's only one match, it's a faster way to call isearch-done (than C-m). Here's the result of C-s sen ':

Outro

I've used the new functionality for a few days already, so it shouldn't be fragile. If the newest MELPA version bugs out for you, you can fall back to version 0.7.1 on MELPA Stable and post an issue. Finally, I hope that some people will take advantage of avy.el simplicity and come up with some cool new commands to share with me. Happy hacking!

Hydra-repeat

2015-02-28T00:00:00+01:00

Did you know that you can repeat the most recent Emacs command with repeat:

Repeat most recently executed command. If REPEAT-ARG is non-nil (interactively, with a prefix argument), supply a prefix argument to that command. Otherwise, give the command the same prefix argument it was given before, if any.

The default binding to repeat is C-x z. You can then continue with just z: C-x zzzzzzzz.

Unfortunately, since defhydra defines new command names based on the ones that you give it, passing repeat as one of the heads will not work. So I've added hydra-repeat that's supposed to work in the same way.

So now, I can define a Hydra like this:

(defhydra hydra-vi ()
  "vi"
  ("h" backward-char)
  ("j" next-line)
  ("k" previous-line)
  ("l" forward-char)
  ("." hydra-repeat))
(global-set-key (kbd "C-v") 'hydra-vi/body)

And if I press C-v 4l.., it will result in movement forward (forward-char) by 4 chars 3 times:

first time from 4l
other two times, with the same prefix 4, from ..

Customizing ace-window leading char

2015-02-27T00:00:00+01:00

With a recent change, it's now possible to customize ace-window like this:

(custom-set-faces
 '(aw-leading-char-face
   ((t (:inherit ace-jump-face-foreground :height 3.0)))))

Here's how it will look like:

It's slightly annoying that the buffer contents have to shift to accommodate for a larger character, but there's no way around it. Besides, you can customize the face features other than height, like foreground and background colors etc.

Note that in the screenshot, I'm using my usual ace-window setup, i.e. home row keys and no background:

(use-package ace-window
    :init
    (setq aw-keys '(?a ?s ?d ?f ?g ?h ?j ?k ?l))
    (setq aw-background nil))

Compilation-style check-declare-file

2015-02-26T00:00:00+01:00

As a follow-up to my older post on Elisp linting options, I've made check-declare-file and check-declare-directory give out warnings similar to those that e.g. byte-compile-file gives:

each warning now has a location in a file-line-column format
you can click on the link to jump to the warning location
first-error / next-error / previous-error work as well
the warning line blinks momentarily with each jump

Here's how it looks like:

You can already use this feature if you're on Emacs trunk, otherwise you'll have to wait for 25.1 to come out.

There's also a new custom variable that you can set to get a more strict check:

(setq check-declare-ext-errors t)

Unless you set it, the standard behavior is to issue a "skipping external file" message when checking a statement like the one above. The reason is that the external package might not be loaded or something. As long as I'm checking, I prefer to check everything, so there's no reason not to have check-declare-ext-errors always true.

A trick to actually load `slime-repl`

Here's the Makefile target for check-declare:

check-declare:
    $(CASKEMACS) -batch $(LOAD) -l check-declare.elt

And here are the contents of check-declare.elt:

(setq check-declare-ext-errors t)
(setq files '("lispy.el"
              "lispy-inline.el"
              "le-clojure.el"
              "le-scheme.el"
              "le-lisp.el"))
(add-to-list 'load-path
             (concat (file-name-directory
                      (locate-library "slime"))
                     "contrib/"))
(require 'slime-repl)
(apply #'check-declare-files files)

As you see, I first find where slime.el is located using locate-library, and then add the contrib sub-directory to the load-path. After this, it's finally possible to (require 'slime-repl).

Rectangle-mode Hydra

2015-02-25T00:00:00+01:00

Today, I'll show a very useful hydra that I found yesterday on the hydra wiki. The idea is by @zhaojiangbin, I've made some minor changes to get the arrows to work the way that I like, and made all keys into plain letters.

The code

(defun ora-ex-point-mark ()
  (interactive)
  (if rectangle-mark-mode
      (exchange-point-and-mark)
    (let ((mk (mark)))
      (rectangle-mark-mode 1)
      (goto-char mk))))

(defhydra hydra-rectangle (:body-pre (rectangle-mark-mode 1)
                           :color pink
                           :post (deactivate-mark))
  "
  ^_k_^     _d_elete    _s_tring     |\\     ‗,,,--,,‗
_h_   _l_   _o_k        _y_ank       /,`.-'`'   .‗  \-;;,‗
  ^_j_^     _n_ew-copy  _r_eset     |,4-  ) )‗   .;.(  `'-'
^^^^        _e_xchange  _u_ndo     '---''(‗/.‗)-'(‗\‗)
^^^^        ^ ^         _p_aste
"
  ("h" backward-char nil)
  ("l" forward-char nil)
  ("k" previous-line nil)
  ("j" next-line nil)
  ("e" ora-ex-point-mark nil)
  ("n" copy-rectangle-as-kill nil)
  ("d" delete-rectangle nil)
  ("r" (if (region-active-p)
           (deactivate-mark)
         (rectangle-mark-mode 1)) nil)
  ("y" yank-rectangle nil)
  ("u" undo nil)
  ("s" string-rectangle nil)
  ("p" kill-rectangle nil)
  ("o" nil nil))

(global-set-key (kbd "C-x SPC") 'hydra-rectangle/body)

There was a lot of screen estate left over, so I added some ASCII-art. I wanted something related to syrup, or at least pancakes, but instead I found a cat. Apparently, it's very easy to find pictures of cats on the internet. Who knew.

Here's how it looks like in-action:

The pink variation is pretty useful here, since it doesn't get in the way of e.g. DEL or C-n or C-e or inserting spaces.

I've been using it today for editing some table data in org-mode, and it feels pretty efficient.

Some explanations

What does what:

d deletes rectangle; it's similar to C-d.
n copies rectangle; it's similar to M-w.
o exits; it's very easy to press.
e exchanges the point and mark; it's also quite useful to re-activate the region if you disabled it with n or r.
s fills the selected rectangle with a string.
y yanks the rectangle that you saved before with n.
r deactivates or activates the rectangle at point.
u calls undo.
p kills the rectangle; it's similar to C-w.

Profile your Emacs start-up time

2015-02-24T00:00:00+01:00

I bet I could compete for the shortest ~/.emacs ever:

(load "~/Dropbox/source/site-lisp/init")

However, it being one line doesn't make it start up any faster. Here's what I have in my Makefile beside init.el:

profile:
    emacs -Q -l git/profile-dotemacs/profile-dotemacs.el \
    --eval "(setq profile-dotemacs-file \
        (setq load-file-name \"$(abspath init.el)\"))" \
    -f profile-dotemacs

The package that I'm using, profile-dotemacs.el comes from David Engster, one of the major contributors to CEDET, so you know it's got to be good. Once you launch it as I showed above, it will give you the times that various sections took to load in an overlay.

On very sunny days I can almost get Emacs to start under one second, although when I checked just now, it turned out to be 1.20s. I value short start up time very highly, since due to my messing with Elisp, the Emacs global state can become so messed up that it's a lot faster to just restart it, rather than spend 10 minutes surgically restoring the state. And, of course, it's a bonus for using Emacs on a laptop, which I do at home.

I've used two methods to shorten the boot time, I'll describe them below.

`use-package` `:idle` option

This one is a big time saver, since org-mode just takes so long to load:

(use-package org
    :defer t
    :idle (require 'oleh/org))

I'm cautious not to abuse :idle, since if it happens that I start Emacs and start frantically typing all over the place, Emacs will never get to be idle and the :idle statements won't load. So I only use it for org and one or two other things.

autoloading stuff

Here's some helper code for this:

(defun update-all-autoloads ()
  (interactive)
  (cd emacs-d)
  (let ((generated-autoload-file
         (expand-file-name "loaddefs.el")))
    (when (not (file-exists-p generated-autoload-file))
      (with-current-buffer (find-file-noselect
                            generated-autoload-file)
        (insert ";;")
        (save-buffer)))
    (mapcar #'update-directory-autoloads
            '("" "oleh" "oleh/modes"))))

Here, emacs-d is the directory of my init.el. The directory modes contains 44 Elisp files for each major mode or package that I customize.

For instance, here are the contents of Info.el:

(define-key Info-mode-map "j" 'ora-para-down)
(define-key Info-mode-map "k" 'ora-para-up)
(define-key Info-mode-map "v" 'recenter-top-bottom)
(define-key Info-mode-map "h" 'backward-char)
(define-key Info-mode-map "l" 'forward-char)
(define-key Info-mode-map "w" 'forward-word)
(define-key Info-mode-map "b" 'backward-word)
(define-key Info-mode-map "a" 'beginning-of-line)
(define-key Info-mode-map "e" 'end-of-line)
(define-key Info-mode-map "A" 'beginning-of-buffer)
(define-key Info-mode-map "E" 'end-of-buffer)

;;;###autoload
(defun oleh-Info-hook ())

This is one of the simpler ones, I think it would take around a week of posts to cover what I have in magit.el. The file Info.el never gets loaded until I open a buffer in Info-mode. Here's what gets loaded every time:

(load (concat emacs-d "loaddefs.el") nil t)
;; ...
(add-hook 'Info-mode-hook 'oleh-Info-hook)

My loaddefs.el is just over 1000 lines and is automatically generated by update-all-autoloads. And here are the lines in loaddefs.el responsible for loading Info.el:

(autoload 'oleh-Info-hook "oleh/modes/Info" "\


\(fn)" nil nil)

So the statements above are cheap to load. Actually, the largest chunk of my start up time, 28 percent, is taken by:

(require 'eclipse-theme)

I don't know why it takes so long to call custom-theme-set-faces, it's a mystery.

Hydra 0.11.0 is out

2015-02-23T00:00:00+01:00

As usual, I'll just re-state the release notes and add some more notes in the end.

Fixes

Emacs 24.3 (and maybe earlier versions) compatibility added
(hydra-cleanup): Should not delete buffer first when window is dedicated.
(lv-message): Should not deactivate mark.
quit signals are intercepted, so that proper clean-up is done.
no defuns with the same name will be generated in case some heads' cmd parts coincide

New Features

Pink body color

When body color is pink, and hydra intercepts a binding which isn't a head, instead of quitting the hydra and executing the binding (default red behavior), it will execute the binding and not quit the hydra. This type of hydra is very similar to define-minor-mode.

So now, pink and amaranth are body colors that are a flavor of the default red that, instead of quitting when a non-head binding is intercepted, respectively run the binding or issue a warning.

Teal body color

Teal color behaves similarly to amaranth (issues a warning when intercepting foreign bindings), but the default behavior for each head is to quit.

The following evaluates to true:

(equal
 (macroexpand
  '(defhydra hydra-test (:color amaranth)
    ("a" fun-a)
    ("b" fun-b :color blue)
    ("c" fun-c :color blue)
    ("d" fun-d :color blue)
    ("e" fun-e :color blue)
    ("f" fun-f :color blue)))
 (macroexpand
  '(defhydra hydra-test (:color teal)
    ("a" fun-a :color red)
    ("b" fun-b)
    ("c" fun-c)
    ("d" fun-d)
    ("e" fun-e)
    ("f" fun-f))))

So if you want to write less, use teal color in this case.

Alternative color-less syntax

The color syntax is working quite well, since I was able to keep an almost full backward-compatibility: once you pinpoint a color it will have that behavior, all the new behaviors will be released under a new color.

Some might prefer an alternative set of switches rather than colors. New compat switches are:

- ":exit nil" for ":color red"; You don't have to specify either
  option in the body, since they are the default behavior that was
  available on Hydra release
- ":exit t" for ":color blue"
- ":foreign-keys warn" for ":color amaranth"
- ":foreign-keys warn :exit t" for ":color teal"
- ":foreign-keys run" for ":color pink"

The property :exit can be inherited and overridden in the same way as :color red or blue.

The following evaluates to true:

(equal
 (macroexpand
  '(defhydra hydra-test ()
    ("a" fun-a)
    ("b" fun-b :color blue)
    ("c" fun-c :color blue)
    ("d" fun-d :color blue)
    ("e" fun-e :color blue)
    ("f" fun-f :color blue)))
 (macroexpand
  '(defhydra hydra-test (:color blue)
    ("a" fun-a :color red)
    ("b" fun-b)
    ("c" fun-c)
    ("d" fun-d)
    ("e" fun-e)
    ("f" fun-f))))

The following two are exactly the same as the two above:

(equal
 (macroexpand
  '(defhydra hydra-test ()
    ("a" fun-a)
    ("b" fun-b :exit t)
    ("c" fun-c :exit t)
    ("d" fun-d :exit t)
    ("e" fun-e :exit t)
    ("f" fun-f :exit t)))
 (macroexpand
  '(defhydra hydra-test (:exit t)
    ("a" fun-a :exit nil)
    ("b" fun-b)
    ("c" fun-c)
    ("d" fun-d)
    ("e" fun-e)
    ("f" fun-f))))

Ruby-style string interpolation in docstrings

Here's an example:

(defhydra hydra-marked-items (dired-mode-map "")
  "
Number of marked items: %(length (dired-get-marked-files))
Auto-revert mode is:    %`auto-revert-mode
"
      ("m" dired-mark "mark"))

To enable this behavior, the docstring has to start with a newline (which will be stripped). This makes sense, since you usually want to align extensive docstrings, like I did this one. The escape syntax for variables is such that you can auto-complete them with company-mode. Both variables and sexps can use format style width specifiers. See the documentation of format for more details.

Examples 7-9 added to hydra-examples.el

These examples explain Ruby-style interpolation.

Updated faces

I've updated each face to match their color by default. Remember, that you can customize each face interactively with M-x customize-group hydra.

Alternative grey-scale or custom faces

If you don't want colors for some reason, you can customize hydra-fontify-head-function to your taste.

As an example:

(setq hydra-fontify-head-function
      #'hydra-fontify-head-greyscale)

This function is already defined in hydra.el, but you could define a similar one on your own:

(defun hydra-fontify-head-greyscale (head body)
  "Produce a pretty string from HEAD and BODY.
HEAD's binding is returned as a string wrapped with [] or {}."
  (let ((color (hydra--head-color head body)))
    (format
     (if (eq color 'blue)
         "[%s]"
       "(%s)") (car head))))

New switch :body-pre

This sexp or function will be prepended to the prefix/body function. Here's an example of use:

(defvar hydra-vi/init-pos nil)
(defhydra hydra-vi (:body-pre (setq hydra-vi/init-pos (point))
                    :color pink)
  "vi"
  ;; arrows
  ("h" backward-char)
  ("j" next-line)
  ("k" previous-line)
  ("l" forward-char)
  ;; exit points
  ("q" (goto-char hydra-vi/init-pos) "ins" :exit t)
  ("C-n" (forward-line 1) nil :exit t)
  ("C-p" (forward-line -1) nil :exit t))

Here, upon entering the hydra, the point position will be saved. And upon quitting, it will be restored.

Outro

I hope that you're enjoying the new updates as much as I do. Since the last release, there are two new blog posts about using hydra that I'm aware of: by Howard Abrams and John Kitchin.

Additionally, @hura, @kaushalmodi, and @glucas have made some additions to the Hydra wiki. Anyone is welcome to share their useful hydras there. Thanks a lot and happy hacking!

Saving match data in-between Elisp evals

2015-02-22T00:00:00+01:00

This is a new feature I've added recently to lispy that's useful when debugging regex-related code.

The gist of it is that the match data is a single global object in Emacs. So if you call string-match with your C-x C-e, there's no guarantee that e.g. match-beginning will return the proper thing with another C-x C-e, since any package running in your Emacs could mess with the match data (packages that use timers or post-command hooks etc.).

After getting annoyed by this a few times, I've finally added a fail-safe to e (lispy-eval) and p (lispy-eval-other-window). Here's how it looks like:

(defvar lispy-eval-match-data nil)

(defun lispy--eval-elisp-form (form lexical)
  "Eval FORM and return its value.
If LEXICAL is t, evaluate using lexical scoping.
Restore and save `lispy-eval-match-data' appropriately,
so that no other packages disturb the match data."
  (let (val)
    (fset '\, #'identity)
    (set-match-data lispy-eval-match-data)
    (setq val (eval form lexical))
    (setq lispy-eval-match-data (match-data))
    (fset '\, nil)
    val))

There's also a little dance of ignoring comma operators in the rare case when I want to eval inside a backquoted list. The two functions that you can take away from this exercise are match-data and set-match-data which appropriately return and store a list of integers. Keeping the string separate from the regex match is a neat way to improve performance.

Embedding sexps in Hydra docstrings

2015-02-21T00:00:00+01:00

In yesterday's post I showed how to embed variable values into the docstring, among other things. Today, I've extended this approach to work with s-expressions. Here's how it looks like:

(defhydra hydra-marked-items (dired-mode-map "")
      "
Number of marked items: %(length (dired-get-marked-files))
"
      ("m" dired-mark "mark"))

This piece of code will remind you how many files you've marked so far each time you press m. By the way, this is the 64th post on the blog; I found out by pressing tm in dired buffer or the _posts directory. Also, I don't think that I've showed passing "" as the keyboard prefix parameter before. Apparently, it works and just translates to this:

(define-key dired-mode-map
    "m" 'hydra-marked-items/dired-mark)

Here's how it looks like:

There's no need for a quitting key, it will auto-vanish when you press anything other than m.

Hydra for Buffer-menu

2015-02-20T00:00:00+01:00

Here's a little code I've made today for Buffer-menu-mode:

(defhydra hydra-buffer-menu (:color pink)
  "
  Mark               Unmark             Actions            Search
-------------------------------------------------------------------------
_m_: mark          _u_: unmark        _x_: execute       _R_: re-isearch
_s_: save          _U_: unmark up     _b_: bury          _I_: isearch
_d_: delete                           _g_: refresh       _O_: multi-occur
_D_: delete up                        _T_: files only: %`Buffer-menu-files-only
_~_: modified
"
  ("m" Buffer-menu-mark nil)
  ("u" Buffer-menu-unmark nil)
  ("U" Buffer-menu-backup-unmark nil)
  ("d" Buffer-menu-delete nil)
  ("D" Buffer-menu-delete-backwards nil)
  ("s" Buffer-menu-save nil)
  ("~" Buffer-menu-not-modified nil)
  ("x" Buffer-menu-execute nil)
  ("b" Buffer-menu-bury nil)
  ("g" revert-buffer nil)
  ("T" Buffer-menu-toggle-files-only nil)
  ("O" Buffer-menu-multi-occur nil :color blue)
  ("I" Buffer-menu-isearch-buffers nil :color blue)
  ("R" Buffer-menu-isearch-buffers-regexp nil :color blue)
  ("c" nil "cancel")
  ("v" Buffer-menu-select "select" :color blue)
  ("o" Buffer-menu-other-window "other-window" :color blue)
  ("q" quit-window "quit" :color blue))

(define-key Buffer-menu-mode-map "." 'hydra-buffer-menu/body)

You can change the color on the top to your taste: either red or pink or amaranth will work. For extensive Hydras I tend to pick pink, since I don't want to quit by accident, while still keeping the non-head bindings. For small ones, red is better. Here's how the result looks like:

You can install the cow with:

apt-get moo

I didn't list it in the source, since Jekyll would wrap the long lines. The source is already in hydra-examples.el. You only have to:

(require 'hydra-examples)
(define-key Buffer-menu-mode-map "." 'hydra-buffer-menu/body)

I've been hearing some opinions lately that the growing number of Hydra options makes it intimidating or unclear. I hope that's not the majority's feeling and that the gentle repetitiveness of this example proves otherwise.

On the other hand, I've started reading "The Reasoned Schemer" this week. Now that's intimidating.

Two new Hydra colors - pink and teal

2015-02-19T00:00:00+01:00

Two new colors are being added up to a total of five: red, blue, amaranth, pink and teal. I should carefully restate what they do to avoid confusion.

The three rules of Hydratics

~~1. A hydra may not injure a human being or, through inaction, allow a human being to come to harm.~~

Seriously though, see below.

Rule 1: Hydra heads are either red or blue

Once you're in a Hydra state:

calling a red head will call the command and continue the state
calling a blue head will call the command and stop the state

They may have a reddish or a bluish face that isn't exactly red or blue, but that's what they are underneath. I hope you get what I mean.

Rule 2: red or blue is inherited from the body color

This is merely a convenience, you can still explicitly override each head to be blue or red:

if the body is red, amaranth or pink, the heads inherit red
if the body is blue or teal, the heads inherit blue

Rule 3:

When you call a binding which isn't a head:

amaranth, teal and pink Hydras will intercept it
red and blue Hydras will quit and let Emacs execute your binding

Finally, on intercepting a non-head, amaranth and teal will issue a warning and do nothing without quitting. And pink will try to call the intercepted command without quitting. Currently only non-prefix bindings can be called, since I haven't figured out how to do it for prefixes.

A nice table to sum things up

Thanks to @kaushalmodi for pointing me in this direction:

|----------+-----------+-----------------------+-----------------|
| Body     | Head      | Executing NON-HEADS   | Executing HEADS |
| Color    | Inherited |                       |                 |
|          | Color     |                       |                 |
|----------+-----------+-----------------------+-----------------|
| amaranth | red       | Disallow and Continue | Continue        |
| teal     | blue      | Disallow and Continue | Quit            |
| pink     | red       | Allow and Continue    | Continue        |
| red      | red       | Allow and Quit        | Continue        |
| blue     | blue      | Allow and Quit        | Quit            |
|----------+-----------+-----------------------+-----------------|

The extra-awesome Ruby-style Hydra docstrings

Turns out learning Ruby wasn't a complete waste of time, at least I learned about string interpolation. And now I'm sticking it into Elisp packages, first tiny, and now hydra.

How it works:

(defhydra hydra-toggle (:color pink)
  "
_a_ abbrev-mode:       %`abbrev-mode
_d_ debug-on-error:    %`debug-on-error
_f_ auto-fill-mode:    %`auto-fill-function
_g_ golden-ratio-mode: %`golden-ratio-mode
_t_ truncate-lines:    %`truncate-lines
_w_ whitespace-mode:   %`whitespace-mode

"
  ("a" abbrev-mode nil)
  ("d" toggle-debug-on-error nil)
  ("f" auto-fill-mode nil)
  ("g" golden-ratio-mode nil)
  ("t" toggle-truncate-lines nil)
  ("w" whitespace-mode nil)
  ("q" nil "cancel"))

(global-set-key (kbd "C-c C-v") 'hydra-toggle/body)

Here, using e.g. "_a_" translates to "a" with proper face. More interestingly, e.g.

"foobar %`abbrev-mode"

translates roughly to

(format "foobar %S" abbrev-mode)

This means that you actually see the state of the mode that you're changing. The escape syntax was chosen with another intent in mind: because of the backquote, if you have company-mode on, you can complete the symbols while in string.

See how it looks like in action:

Small note on pink Hydras

It's useful for instance it the above example, when I don't care about self-inserting, but I still want to do navigation. Basically pink Hydra is the closest thing to an actual minor mode. Thanks to @angelic-sedition for the idea.

Small note on teal Hydras

It provides an interface similar to magit dispatch: pressing appropriate keys does things and pressing the wrong keys issues a warning. The only difference between teal and amaranth is the color inheritance, otherwise they behave exactly the same. This means that if you want a non-quitting Hydra that will end up with more blue heads, start with teal, otherwise, start with amaranth. Thanks to @ffevotte for the idea.

Outro

It feels like things are finally falling into place with this package. I hope that you like the new changes and find new cool uses for the added abilities. Happy hacking!

Reverting nonsense

2015-02-18T00:00:00+01:00

It happens to me frequently when making a demo, or just experimenting around that I want to revert the buffer to the last saved state. Obviously such a command exists in Emacs, and it's unsurprisingly called revert-buffer:

Replace current buffer text with the text of the visited file on disk. This undoes all changes since the file was visited or saved.

But the poor old revert-buffer isn't bound by default in Emacs. The perfect binding for it is C-x C-r:

(global-set-key
 (kbd "C-x C-r")
 (lambda () (interactive) (revert-buffer nil t)))

I believe the lambda is used to get the "no questions asked" treatment. Anyway, by default Emacs binds C-x C-r to find-file-read-only, which really is a trash-tier command.

Why is find-file-read-only useless?

Because C-x C-q is bound to read-only-mode - a really good command (made even better with wdired and wgrep). So find-file-read-only is just C-x C-f C-x C-q. And I don't ever recall needing to use that, since v (dired-view-file) is almost equivalent if not better.

As a bonus, C-x C-r is mnemonic for "revert".

Auto-reverting

While on the topic, let me mention auto-revert-mode. I have this in my config:

(global-auto-revert-mode 1)

This way, if any opened and saved file was modified outside of Emacs, it will be updated in a short while. I was able to use this to a great advantage when writing the SVG picture for the Xmodmap post:

I opened the SVG in the default image mode in one Emacs instance
and opened the same document in XML mode in another (mode is toggled with C-c C-c)

With that setup, I was able to see the picture update as I was inputting the XML. Here's some Elisp for XML generation, if you're interested

(defun make-row (row-str ix iy fill)
  (mapconcat
   (lambda (x)
     (format
      "<g><text x=\"%d\" y=\"%d\" style=\"font-size:10px;fill:%s;font-family:Deja Vu Sans Mono\">%s</text></g>"
      (+ ix (* x 30))
      iy
      fill
      (let ((y (elt row-str x)))
        (if (stringp y)
            y
          (make-string 1 y)))))
   (number-sequence 0 (1- (length row-str)))
   "\n"))

(make-row
 "QWERTYUIOP"
 95 140
 "#2b2828")
;; =>

The last statement would generate: Q W E R T Y U I O P.

Hydra 0.10.0 is out

2015-02-17T00:00:00+01:00

As usual, I'll just re-state the release notes, while maybe adding a bit of flavor.

New features

Define Hydra heads that don't show up in the hint at all

This can be done by setting the head's hint explicitly to nil, instead of the usual string. For instance, if you always tend to bind the arrows to hjkl, there's no point to show a hint for them.

Use a dedicated window for Hydra hints

Since version 0.10.0, setting hydra-lv to t (the default setting) will make it use a dedicated window right above the Echo Area for hints. This has the advantage that you can immediately see any message output from the functions that you call, since Hydra no longer uses message to display the hint. You can still have the old behavior by setting hydra-lv to nil.

How it looks like:

Here, an error was triggered by previous-line and the message is displayed without interrupting the hint.

Allow duplicate functions in heads

Duplicate functions will be concatenated in the hint. This was already covered in yesterday's post

Add option to font-lock `defhydra`

If you want to nicely font-lock your defhydra statements, just add this to your config:

(require 'hydra)
(hydra-add-font-lock)

Additionally, defhydra is now to be indented as a defun, so it will be indented like this:

(defhydra hydra-goto-line (global-map "M-g"
                           :pre (linum-mode 1)
                           :post (linum-mode -1)
                           :color blue)
  ("g" goto-line "line")
  ("c" goto-char "char"))

Note that the indentation of the body argument is as if it was data and not code, i.e. the proper one. As you see, I even added defhydra to the blog's Pygments list for Elisp.

Incompatible changes

The macro hydra-create, as well as the variables that were supposed to be used with it (hydra-example-text-scale, hydra-example-move-window-splitter, hydra-example-goto-error, hydra-example-windmove) were removed. All the functionality is still there in hydra-examples.el with the better defhydra macro.

Outro

I hope that you like the new changes. And if you're byte-compiling your code that uses defhydra, don't forget to re-compile. Also, the latest version of ace-window will ignore *LV* buffer while switching, as it did for *Calc Trail* before.

Binding one function multiple times in Hydra

2015-02-16T00:00:00+01:00

Here's a recent feature that's now available in hydra:

(defhydra hydra-zoom (global-map "<f2>")
  "zoom"
  ("g" text-scale-increase "in")
  ("l" text-scale-decrease "out")
  ("0" (text-scale-set 0) "reset")
  ("1" (text-scale-set 0) :bind nil)
  ("2" (text-scale-set 0) :bind nil :color blue))

Here, the entry points are <f2> g, <f2> l, and <f2> 0, the others aren't bound in the global map. You can also have the same function in both red and blue versions. Here's how the hint will look like:

The multiply-defined functions will be neatly grouped together.

If you remember, (text-scale-set 0) uses a sexp syntax for a Hydra head: it will be wrapped in (lambda () (interactive) ...) automatically.

Doing sudo stuff with tramp

2015-02-15T00:00:00+01:00

Somehow, I accumulated a few files owned by root that should have been owned by me. Below, I'll describe a solution to get rid of them based on dired and tramp.

Step one: open the directory with sudo privileges

I'll obviously need the sudo privilege to change the owner of a file owned by root. Might as well start with that.

Thankfully, I do have a shortcut:

(defun sudired ()
  (interactive)
  (require 'tramp)
  (let ((dir (expand-file-name default-directory)))
    (if (string-match "^/sudo:" dir)
        (user-error "Already in sudo")
      (dired (concat "/sudo::" dir)))))
(define-key dired-mode-map "!" 'sudired)

The function above will open the current directory in sudo mode. I decided to bind it to !, since the default & seems strictly better than !. The function will ask you for the password once. Afterwards, you can open other directories without having to enter the password.

Step two: `find-dired`

So now, while in sudo mode of the directory in question:

Call M-x find-dired. It's not bound by default, and I don't bind it myself since it's quite situational (I do bind find-name-dired to F in dired-mode though).
It prompts you for the directory. I just press RET, since the default one is what I need.
Next, it prompts for find args. These are the arguments to the UNIX command find. Here, I need to pass -user root.
The command has finished and I can see the results. I can select some of them by pressing m (dired-mark) a few times, or mark them all at once with t (dired-toggle-marks).
Finally, call O (dired-do-chown) on the marked files and enter oleh.

Done. I'm sure that the admin types can cook up some find-exec-chown combo to do the same thing, but the find-dired approach is both simpler and more flexible, since I can confirm and edit the list of files being changed.

Semimap - .Xmodmap with semicolon as an additional modifier

2015-02-14T00:00:00+01:00

Today, I'll share my keyboard layout, based on QWERTY, that facilitates all tech-related activities, especially Emacs. I've been using a version of this for about three years now, and only a single key has been changed in the last two years. Without further ado, here it is:

The most visible change

I've made ; stop inserting ; and instead act as Mode_switch: a modifier similar to control or meta.

I'm pressing ;-j to enter ;
I'm pressing ;-d to enter :

So I'm giving up the ability to press ; with a single key, and remapping : from one two-key combination to another two-key combination.

In return, I'm getting a QWERTY with all these wonderful shortcuts.

The RSI-savers

The general ones are:

RET on ;-v (symmetric with C-m)
DEL on ;-o

If you're writing a bunch of C++, _ on ;-s is very good.

Likewise, - on ;-a is great for LISP.

For LaTeX, \ on ;-w is good since I switched from a keyboard that had it near z to a keyboard that has it near RET.

I'm guessing ~ on ;-t isn't bad for shell, but I don't use it that much.

The basic remaps

These are just char-for-char remaps. They are composable, for instance I have dired-jump on C-:, which means that I'm pressing C-;-d.

Some math symbols are mnemonic: e-equal, l-lesser, g-greater. If you're using lispy, it might become more clear for you why I've put lispy-slurp on > and lispy-barf on <. Although pressing these keys with a shift isn't the worst thing, having them on the home row is pretty cool.

The pairs

Here are the translations meant for pairs: q - θ, f - φ, r - ρ, c - σ. These are meant for Emacs and .inputrc. In both cases, e.g. φ should insert () and go backward one char. Here's my .inputrc:

set input-meta on
set output-meta on
set convert-meta off
"θ":""\C-b""
"ω":"'\C-b'"
"\e\C-l":"\C-e | less\C-m"
"υ":">\C-b<"
"σ":"}\C-b{"
"φ":")\C-b("
"ρ":"]\C-b["

set completion-ignore-case on

With this .inputrc, it's like I have some kind of electric mode in my bash. In Emacs, the pairs are bound in a straightforward way:

(defun ins-brackets ()
  (interactive)
  (cond ((eq major-mode 'term-mode)
         (term-send-raw-string "[]")
         (term-send-raw-string "^B"))
        ((region-active-p)
         (lispy--surround-region "[" "]"))
        (t
         (insert "[]")
         (backward-char))))
(global-set-key "ρ" 'ins-brackets)

For LISP, I use lispy-specific bindings:

(define-key lispy-mode-map (kbd "φ") 'lispy-parens)
(define-key lispy-mode-map (kbd "σ") 'lispy-braces)
(define-key lispy-mode-map (kbd "ρ") 'lispy-brackets)
(define-key lispy-mode-map (kbd "θ") 'lispy-quotes)
(define-key lispy-mode-map (kbd "χ") 'lispy-right)

The rest of the Greek chars

These are bound to various Emacs functions. In fact, I initially started with all Greek chars, and bound e.g.:

(global-set-key (kbd "ε") "=")

When these remap-type bindings became mature, I've put them directly into .Xmodmap, which gave the advantage of being able to compose the keys.

These bindings are as good and usable as the control plus lower case chars. Use them wisely and you can get a very ergonomic setup. Some ideas:

switching buffers on ;-h
switching windows on ;-n
jumping to bookmarks on ;-m

The shifted digits

I find it much easier to press e.g. ;-4 to insert $, rather than S-4. I also restored the justice of 0 coming before 1 by mapping ;-` to 0.

Outro

I hope that you'll find some use and enjoyment in these ramappings, if you're not afraid to experiment a little. The cost of losing the semicolon is pretty minor, the bigger issue is in finding the unmodified QWERTY extremely sluggish after using this approach.

Elisp linting options

2015-02-13T00:00:00+01:00

I discovered today that I was using declare-function in a wrong way. So I'll share how to use it properly.

`declare-function`

I was just using it to shut up the byte compiler's "not known to be defined" warning. Turns out that it can also be used to check if the functions actually exist in the file to which they point to. You can use check-declare-file to check one file, or check-declare-directory to recursively check the whole directory.

Here's an example output:

Warning (check-declare): helm-info.el said `Info-goto-node' was defined in info.el.gz: arglist mismatch
Warning (check-declare): helm-info.el said `Info-find-node' was defined in info.el.gz: arglist mismatch
Warning (check-declare): helm-plugin.el said `Info-goto-node' was defined in info.el.gz: arglist mismatch
Warning (check-declare): helm-plugin.el said `Info-find-node' was defined in info.el.gz: arglist mismatch
Warning (check-declare): helm-emms.el said `with-current-emms-playlist' was defined in emms.el: function not found
Warning (check-declare): projectile.el said `ggtags-ensure-project' was defined in ggtags.el: file not found
Warning (check-declare): projectile.el said `ggtags-update-tags' was defined in ggtags.el: file not found
Warning (check-declare): async-bytecomp.el said `package-desc-reqs' was defined in package.el.gz: function not found

My mistake was assuming that the FILE argument of declare-function was somehow related to require. But of course it had to be simply the name of the file that contains the said function. If the referenced file is in an external package, e.g. (declare-function cider-repl-return "ext:cider-repl") can be used.

`checkdoc`

This one is actually very useful once you embrace it. It will tsk-tsk you until all your functions are documented. And since you're already writing a docstring, might as well make it good. Sometimes this leads me to removing a function that's called only once, just so that I don't have to document it.

`byte-compile-file`

Leaving the obvious for last. This will speed up the code in addition to checking for errors. In dired you can use:

several m (dired-mark) followed by B (dired-do-byte-compile).
a single *% (dired-mark-files-regexp) el$ followed by B.

I even have a compile target in lispy's Makefile:

compile:
    $(CASK) exec $(EMACS) -batch $(LOAD) -l lispy-test.el -l compile.elt

Here are the contents of compile.elt:

(require 'check-declare)
(setq check-declare-ext-errors t)
(setq files '("lispy.el"
              "lispy-inline.el"
              "le-clojure.el"
              "le-scheme.el"
              "le-lisp.el"))
(mapc #'byte-compile-file files)
(ert t)
(apply #'check-declare-files files)

Occasionally ido

2015-02-12T00:00:00+01:00

As I was refactoring my .emacs, I found a silly wrapper around describe-function that uses ido-completing-read. I think I was aware at the time that ido-ubiquitous could simply make describe-function use ido-completing-read. The problem was that it also affected the completing-read in functions that became headlong-bookmark-jump from headlong (see the corresponding post if you missed it).

A bit of code to make things right

(defun ido-occasional-completing-read
    (prompt collection
     &optional predicate require-match initial-input
       hist def inherit-input-method)
  "Use `ido-completing-read' if the collection isn't too large.
Fall back to `completing-read' otherwise."
  (let ((filtered-collection
         (all-completions "" collection predicate)))
    (if (<= (length filtered-collection) 30000)
        (ido-completing-read
         prompt filtered-collection nil
         require-match initial-input hist
         def nil)
      (completing-read
       prompt collection predicate
       require-match initial-input hist
       def inherit-input-method))))

;;;###autoload
(defmacro with-ido-completion (fun)
  "Wrap FUN in another interactive function with ido completion."
  `(defun ,(intern (concat (symbol-name fun) "/with-ido")) ()
     ,(format "Forward to `%S' with ido completion." fun)
     (interactive)
     (let ((completing-read-function
            'ido-occasional-completing-read))
       (call-interactively #',fun))))

The only thing that ido-occasional-completing-read does is to pre-filter collection with predicate and pass it on to ido-completing-read. And with-ido-completion is just a convenience wrapper.

Example

(global-set-key (kbd "<f1> f")
                (with-ido-completion describe-function))
(global-set-key (kbd "<f1> v")
                (with-ido-completion describe-variable))
(global-set-key (kbd "<f2> i")
                (with-ido-completion info-lookup-symbol))

Here, with-ido-completion will generate e.g. describe-function/with-ido, which will subsequently be bound to <f1> f. The good-old describe-function is left unaffected.

Note, that if I turn on helm-mode at this point, it will override describe-function with its own completion, but it will not touch describe-function/with-ido which I bound. This can be useful e.g. if I want to use helm-mode (or icy-mode or icomplete-mode) for some completion, but not all.

You can find the package at ido-occasional.

Elisp newbie-style

2015-02-11T00:00:00+01:00

I've been cleaning up my .emacs lately, with the intention to put my whole config on Github. Today, I'll show you a useful function for describing the current buffer's key bindings. The function will generate something like this (with all letters, of course):

;; (global-set-key (kbd "a") 'self-insert-command)
;; ...
;; (global-set-key (kbd "C-b") 'backward-char)
;; ...
;; (global-set-key (kbd "M-c") 'subword-capitalize)
;; ...
;; (global-set-key (kbd "C-M-d") 'down-list)
;; ...
;; (global-set-key (kbd "η") 'save-and-switch-buffer)
;; ...
;; (global-set-key (kbd "C-θ") 'ins-single-quotes)
;; ...
;; (global-set-key (kbd "M-ι") 'nil)
;; ...
;; (global-set-key (kbd "C-M-κ") 'nil)

First, I'll show you how I wrote it down as a newbie, and then today's corrections with some remarks.

Old style

Please don't try this at home:

;;;###autoload
(defun keys-latin ()
  (loop for c from ?a to ?z
     collect (string c)))

;;;###autoload
(defun keys-greek ()
  (loop for c from ?α to ?ω
     collect (string c)))

(require 'dash)
;;;###autoload
(defun keys-describe-prefix (letters prefix)
  (->> letters
    (mapcar (lambda (letter) (concat prefix letter)))
    (mapcar (lambda (key)
              (cons key
                    (prin1-to-string (key-binding (kbd key))))))
    (mapcar (lambda (binding)
              (concat
               ";; (global-set-key (kbd \""
               (car binding)
               "\") '"
               (cdr binding)
               ")\n")))
    (apply #'concat)))

;;;###autoload
(defun keys-describe-prefixes ()
  (interactive)
  (with-output-to-temp-buffer "*Bindings*"
    (mapcar
     (lambda (f-letters)
       (mapcar (lambda (prefix)
                 (princ (keys-describe-prefix f-letters prefix))
                 (princ "\n\n"))
               '("" "C-" "M-" "C-M-")))
     (list (keys-latin) (keys-greek)))))

Corrections

Redundant autoloads

Since the entry point of the whole thing is keys-describe-prefixes, only it needs to be autoloaded. Once an autoloaded function is called, it will load the whole buffer. So if e.g. keys-latin is not being used anywhere else outside this file, it doesn't need an autoload.

Redundant functions

keys-latin and keys-greek are actually very small and not used anywhere else. It might be better to just inline them into keys-describe-prefixes.

Redundant libraries

Here, dash is required just for the ->> macro, which can actually be obtained from a core library subr-x as thread-last.

But even then, it's just better to unwind the whole thing. After that, it becomes clear that the three consecutive mapcars could be folded into a single mapcar with the help of a let binding.

After the fold, it starts to look silly, since I'm consing just to take a car and cdr later:

(defun keys-describe-prefix (letters prefix)
  (apply #'concat
         (mapcar
          (lambda (letter)
            (let* ((key (concat prefix letter))
                   (binding
                    (cons key
                          (prin1-to-string
                           (key-binding (kbd key))))))
              (concat
               ";; (global-set-key (kbd \""
               (car binding)
               "\") '"
               (cdr binding)
               ")\n")))
          letters)))

Here's a simplification, removing binding:

(defun keys-describe-prefix (letters prefix)
  (apply #'concat
         (mapcar
          (lambda (letter)
            (let ((key (concat prefix letter)))
              (concat
               ";; (global-set-key (kbd \""
               key
               "\") '"
               (prin1-to-string
                (key-binding (kbd key)))
               ")\n")))
          letters)))

I guess that I didn't know about format function back then, and the fact that "%S" key is equivalent to prin1-to-string:

(defun keys-describe-prefix (letters prefix)
  (apply #'concat
         (mapcar
          (lambda (letter)
            (let ((key (concat prefix letter)))
              (format ";; (global-set-key (kbd \"%s\") '%S)\n"
                      key
                      (key-binding (kbd key)))))
          letters)))

Next, the combination (apply #'concat (mapcar ...)) is already implemented in C as mapconcat:

(defun keys-describe-prefix (letters prefix)
  (mapconcat
   (lambda (letter)
     (let ((key (concat prefix letter)))
       (format ";; (global-set-key (kbd \"%s\") '%S)"
               key
               (key-binding (kbd key)))))
   letters
   "\n"))

In the end, keys-describe-prefix turned out to be so small that I could just inline it into keys-describe-prefixes.

Final version

Note that here I also replaced mapcar with dolist:

;;;###autoload
(defun keys-describe-prefixes ()
  (interactive)
  (with-output-to-temp-buffer "*Bindings*"
    (dolist (letter-group (list
                           (cl-loop for c from ?a to ?z
                                    collect (string c))
                           (cl-loop for c from ?α to ?ω
                                    collect (string c))))
      (dolist (prefix '("" "C-" "M-" "C-M-"))
        (princ (mapconcat
                (lambda (letter)
                  (let ((key (concat prefix letter)))
                    (format ";; (global-set-key (kbd \"%s\") '%S)"
                            key
                            (key-binding (kbd key)))))
                letter-group
                "\n"))
        (princ "\n\n")))))

I hope that this sort of analysis can be useful for people starting to learn Elisp. And if you have corrections for the final version, do let me know, I don't mind being schooled, as long as I get better in the end.

The output of keys-describe-prefixes can be used to learn some bindings that you didn't know about, and also as a template to redefine some bindings that you don't need.

Easy ido improvement

2015-02-10T00:00:00+01:00

Heh, I guess I was so busy at work that I missed the opportunity to make an especially good post for the 50-post landmark. At least according to M-= (count-words-region) in my _posts' dired buffer, this is the 53rd post.

`ido-backspace`

This echoes to my very second post, easy helm improvement, which was about implementing a similar function for helm. So here it is:

(ido-mode)
(require 'delsel)
(defun ido-backspace ()
  "Forward to `backward-delete-char'.
On error (read-only), quit without selecting."
  (interactive)
  (condition-case nil
      (backward-delete-char 1)
    (error
     (minibuffer-keyboard-quit))))
(define-key ido-common-completion-map (kbd "DEL") 'ido-backspace)

With this setup, when e.g. calling ido-switch-buffer, you can cancel with DEL. This, of course, will also work for smex and some other packages that allow for ido completion:

(setq magit-completing-read-function #'magit-ido-completing-read)
(setq lispy-completion-method 'ido)

Note that the define-key part of the code takes an advantage of a recent patch to ido that's available in the trunk. You can find the old way of binding keys for ido in an earlier post, tilde in ido-find-file. That post actually played a small role in speeding up the patch, for which we should thank @tarsius.

Note that this behavior will not affect ido-find-file, since it has its own map.

ido-vertical - like ido, but vertical!

2015-02-09T00:00:00+01:00

Intro

As I was releasing lispy 0.23.0, which added an option for methods of jumping to semantic tags other than helm, I've discovered ido-vertical-mode. I also made some changes to it, so now it looks like this:

The changes are:

the current text is highlighted in all matches
the current number of total matches is displayed in the first line
I also customized the face for the first match and the only match (you can't see that one here)

Helm is still the big gun when it comes to completing lists with hundreds of candidates, but with the above changes, ido-vertical-mode comes close to what I need when jumping to tags. The only thing missing now is that the selected candidate is always on the first line, even when I press C-n, which isn't very intuitive.

Stuff related to `lispy` release

Other completion methods available in `lispy-goto`

Depending on the modes you have enabled, you can complete with:

helm
ido
ido-vertical-mode
icomplete-mode
icy-mode
no mode, just plain completion

`lispy-eval-other-window` now uses `ace-window`

This function bound to p is very convenient for debugging Elisp: it allows you to eval the current sexp in the context of other window. This is very powerful: you can run and debug your function as you write it, statement by statement. Previously, this setup was viable only in a two-window split, because using other-window, it wasn't predictable in which window the eval would take place. Now, if there are more than two windows, aw-select will select the window for the eval. This selection will be remembered, so you don't have to select for the following evals, unless the window configuration changes.

Outro

There are more changes that you can find in the release notes if you're interested. You can find the new ido-vertical stuff in my fork, until it gets merged.

Hydra 0.9.0 is out

2015-02-08T00:00:00+01:00

I'll just list the new features from the release notes here.

Keyboard quit

hydra-keyboard-quit set to "C-g" means that it's possible to quit an amaranth Hydra with C-g. You can customize this variable.

`:pre` and `:post` refinement

:post and :pre keys in the body PLIST can be either a single sexp or a function name. The function doesn't need to be interactive.

Support for local Hydra heads via `:bind` property

Example:

(defhydra hydra-next-error (global-map "C-x")
  "next-error"
  ("`" next-error "next")
  ("j" next-error "next" :bind nil)
  ("k" previous-error "previous" :bind nil))

What it does:

binds C-x ` to next-error.
does not bind C-x j and C-x k
you can still do C-x `jjkk

Thanks, @ffevotte.

Support for `:bind` property in Hydra body

The body, like the heads will recognize the :bind property in PLIST. The heads will inherit it, just like they do with :color. The :bind property can be nil or a lambda of global-set-key format.

Example:

(defhydra hydra-goto (global-map "M-g"
                      :bind
                      (lambda (key cmd)
                        (bind-key key cmd)))
  ("g" goto-line "goto-line" :bind global-set-key)
  ("c" goto-char "goto-char"))

Here, bind-key will be used to bind goto-char to M-g c, since c head has inherited body's :bind property. Note that since bind-key is a macro, it was necessary to wrap it in a lambda.

However, global-set-key will be used to bind goto-line to M-g g, this :bind property was overridden in the g head.

Since this commit, it's not possible to pass a lambda instead of the whole BODY argument, as was advertised before. Just put it on :bind now.

`hydra/body` will pass the initial `current-prefix-arg` along

Example:

(global-set-key
 (kbd "C-z")
 (defhydra hydra-vi ()
   "vi"
   ("l" forward-char)
   ("q" nil "quit")))

Now, C-u C-z l will result in (forward-char 4). All the other l will normally call (forward-char 1), unless an additional prefix is given. The previous behavior allowed only for C-z C-u l to get (forward-char 4).

Allow a sexp as head's CMD parameter

Example:

(defhydra hydra-launcher (:color blue)
   "Launch"
   ("h" man "man")
   ("r" (browse-url "http://www.reddit.com/r/emacs/") "reddit")
   ("w" (browse-url "http://www.emacswiki.org/") "emacswiki")
   ("s" shell "shell")
   ("q" nil "cancel"))
(global-set-key (kbd "C-c r") 'hydra-launcher/body)

Here, r and w heads are using this feature. Here's what will be generated, if you're interested:

(defun hydra-launcher/lambda-w nil
  "Create a hydra with no body and the heads:

\"h\":    `man',
\"r\":    `(browse-url \"http://www.reddit.com/r/emacs/\")',
\"w\":    `(browse-url \"http://www.emacswiki.org/\")',
\"s\":    `shell',
\"q\":    `nil'

The body can be accessed via `hydra-launcher/body'.

Call the head: `(browse-url \"http://www.emacswiki.org/\")'."
  (interactive)
  (hydra-disable)
  (catch (quote hydra-disable)
    (call-interactively
     (function
      (lambda nil
       (interactive)
       (browse-url "http://www.emacswiki.org/"))))))

Obsolete declarations

hydra-create and all old examples in hydra-examples.el are now obsolete. You can still use them for a short while, but they will be removed soon.

You should take the time to switch from hydra-create to defhydra. All the old examples are provided in the new style in hydra-examples.el. However, they will not be evaluated through (require 'hydra-examples) unless you (setq hydra-examples-verbatim t) beforehand. This is because I have no idea what kind of bindings will work for you, you should decide yourself. But I am providing you with a template. The number of examples has also grown to six.

A new Hydra demo on Youtube

2015-02-07T00:00:00+01:00

This will be a short post sharing two pieces of information.

A Hydra demo is on Youtube

Here is the link, and here is the current window-switching code:

(global-set-key
 (kbd "C-M-o")
 (defhydra hydra-window (:color amaranth)
   "window"
   ("h" windmove-left)
   ("j" windmove-down)
   ("k" windmove-up)
   ("l" windmove-right)
   ("v" (lambda ()
          (interactive)
          (split-window-right)
          (windmove-right))
        "vert")
   ("x" (lambda ()
          (interactive)
          (split-window-below)
          (windmove-down))
        "horz")
   ("t" transpose-frame "'")
   ("o" delete-other-windows "one" :color blue)
   ("a" ace-window "ace")
   ("s" ace-swap-window "swap")
   ("d" ace-delete-window "del")
   ("i" ace-maximize-window "ace-one" :color blue)
   ("b" ido-switch-buffer "buf")
   ("m" headlong-bookmark-jump "bmk")
   ("q" nil "cancel")))

`ace-window 0.7.0` is out

You can see the release notes here. There's not a whole lot of user-visible changes, but a large portion of the code was re-written to facilitate the use of the API. I hope that no new bugs were introduced with this change, you can still fall back to 0.6.1 and send me an issue if something broke. There's a benefit in the long run, just see how simple the code has become:

(defun ace-maximize-window ()
  "Ace maximize window."
  (interactive)
  (select-window
   (aw-select " Ace - Maximize Window"))
  (delete-other-windows))

Here, aw-select just returns a selected window, and nothing else. Very easy to use.

The Elisp Synergy

2015-02-06T00:00:00+01:00

After having written a few Emacs packages, it happens sometimes when I'm reading questions on Emacs Stack Exchange, I think to myself that either:

I've done this before in package X

or:

This feature would fit nicely in package Y

On very rare occasions it happens that a question matches two packages at once. Here is such a question:

Is there a yasnippet producing a prepopulated doxygen comment?

For the following C++ function:
bool importantStuff(double a, double b);
It should output the following snippet, perhaps without the tags:
/**
* <Insert description of importantStuff>
*
* @param a <Insert description of a>
* @param b <Insert description of b>
* @return <Insert description of the return value>
*/

Well, I've got a package called function-args for C++ that uses CEDET to:

display tool-tips with function arguments
jump to a semantic tag in current file
do a bit of completion
do a bit of generation (like inherited function signatures)

And the expansion part can be handled by auto-yasnippet, which I've covered in an earlier post.

The code

I think it might be useful to look at the code, since it's small and shows how to use CEDET's and auto-yasnippet's API:

(defun moo-doxygen ()
  "Generate a doxygen yasnippet and expand it with `aya-expand'.
The point should be on the top-level function name."
  (interactive)
  (move-beginning-of-line nil)
  (let ((tag (semantic-current-tag)))
    (unless (semantic-tag-of-class-p tag 'function)
      (error "Expected function, got %S" tag))
    (let* ((name (semantic-tag-name tag))
           (attrs (semantic-tag-attributes tag))
           (args (plist-get attrs :arguments))
           (ord 1))
      (setq aya-current
            (format
             "/**
* $1
*
%s
* @return $%d
*/
"
             (mapconcat
              (lambda (x)
                (format "* @param %s $%d"
                        (car x) (incf ord)))
              args
              "\n")
             (incf ord)))
      (aya-expand))))

The bonus

If you're interested in Doxygen, here's a bit of code that I found laying around. It will prettify e.g. <tt>Numerical Recipies</tt> to Numerical Recipies in the comments. This code uses a similar approach to the one used in my posts about prettifying Elisp regex, and ElTeX.

(defface font-lock-doxygen-face
    '((nil (:foreground "SaddleBrown" :background "#f7f7f7") ))
    "Special face to highlight doxygen tags such as <tt>...</tt>
and <code>...</code>."
    :group 'font-lock-highlighting-faces)

(font-lock-add-keywords
 'c++-mode
 '(("\\(<\\(?:code\\|tt\\)>\"?\\)\\([^<]*?\\)\\(\"?</\\(?:code\\|tt\\)>\\)"
    (0 (prog1 ()
         (let* ((expr (match-string-no-properties 2))
                (expr-len (length expr)))
           (if (eq 1 expr-len)
               (compose-region (match-beginning 0)
                               (match-end 0)
                               (aref expr 0))
             (compose-region (match-beginning 1)
                             (1+ (match-end 1))
                             (aref expr 0))
             (compose-region (1- (match-beginning 3))
                             (match-end 3)
                             (aref expr (1- expr-len)))))))
    (0 'font-lock-doxygen-face t))))

Outro

I hope that the code listed here will be useful to someone other than me. It's a nice highlight of how a language can be made much cooler by just having a package manager that allows to quickly glue various things together. I mean, what would happen to JavaScript without npm (besides stopping people requiring Angular just to use arrays)?

C++, on the other hand, is too cool to care about such things as package managers and modules and stuff. But we're stuck with it for performance reasons, so might as well try to make the experience more bearable by adding some niceties to c++-mode.

Introducing amaranth Hydras

2015-02-05T00:00:00+01:00

An amaranth planted in a garden near a Rose-Tree, thus addressed it: "What a lovely flower is the Rose, a favorite alike with Gods and with men. I envy you your beauty and your perfume." The Rose replied, "I indeed, dear Amaranth, flourish but for a brief season! If no cruel hand pluck me from my stem, yet I must perish by an early doom. But thou art immortal and dost never fade, but bloomest for ever in renewed youth."

Prompted by the "Avoid exiting the hydra on hitting a wrong key" issue, I decided to add a new body color for Hydra. Turns out that there exists a color that represents immortality, and it's called amaranth. It's also very pretty.

So what amaranth Hydras do basically, is make it impossible to quit them. Of course, it would be totally lame if there wasn't at least one way to quit them. And what better to utilize for this purpose, than the good-old quitters - the blue Hydra heads.

An Example code

(global-set-key
 (kbd "C-z")
 (defhydra hydra-vi
     (:pre
      (set-cursor-color "#e52b50")
      :post
      (set-cursor-color "#ffffff")
      :color amaranth)
   "vi"
   ("l" forward-char)
   ("h" backward-char)
   ("j" next-line)
   ("k" previous-line)
   ("m" set-mark-command "mark")
   ("a" move-beginning-of-line "beg")
   ("e" move-end-of-line "end")
   ("d" delete-region "del" :color blue)
   ("y" kill-ring-save "yank" :color blue)
   ("q" nil "quit")))

This Hydra has only three exit points:

q, which does nothing
y, which copies the active region
d, which deletes the active region

In addition to the usual arrows on hjkl, a and e move to beginning and end of line respectively.

Outro

I hope that you like the new idea, also thanks to @vkazanov for the push in this direction. Things should be backwards-compatible, so this feature costs you nothing if you're not using it. See the release notes for 0.8.0.

One more thanks goes to Sridhar Ratnakumar for this suggestion that lead to an improvement in auto-yasnippet. Thanks to this improvement, I was able to quickly wrap words like this:

<font color="#FF007F">Rose</font>

New in Hydra - :pre and :post clauses

2015-02-04T00:00:00+01:00

Only three commits happened since 0.6.1, but already 0.7.0 has to be released, since the behavior has changed slightly.

The ultimate window switching setup, revised

The code from the last post had to be changed. Note that only ace-window-related heads are affected, since ace-window uses set-transient-map as well. This was necessary to fix issue #15 (unable to use goto-line in a Hydra, since it requires input).

(global-set-key
 (kbd "C-M-o")
 (defhydra hydra-window ()
   "window"
   ("h" windmove-left)
   ("j" windmove-down)
   ("k" windmove-up)
   ("l" windmove-right)
   ("a" (lambda ()
          (interactive)
          (ace-window 1)
          (add-hook 'ace-window-end-once-hook
                    'hydra-window/body)
          (throw 'hydra-disable t))
        "ace")
   ("v" (lambda ()
          (interactive)
          (split-window-right)
          (windmove-right))
        "vert")
   ("x" (lambda ()
          (interactive)
          (split-window-below)
          (windmove-down))
        "horz")
   ("s" (lambda ()
          (interactive)
          (ace-window 4)
          (add-hook 'ace-window-end-once-hook
                    'hydra-window/body)
          (throw 'hydra-disable t))
        "swap")
   ("t" transpose-frame "'")
   ("d" (lambda ()
          (interactive)
          (ace-window 16)
          (add-hook 'ace-window-end-once-hook
                    'hydra-window/body)
          (throw 'hydra-disable t))
        "del")
   ("o" delete-other-windows "one" :color blue)
   ("i" ace-maximize-window "ace-one" :color blue)
   ("q" nil "cancel")))

You can also see an awesome addition sneak in, with transpose-frame on t.

Technical note

If you look closely at the code, you'll see the ace-window-related lambdas throwing the hydra-disable symbol. If the Hydra code catches that symbol, it will not call set-transient-map again, effectively making the head that threw the symbol blue. In this example, though, ace-window-related functions are still red, since the Hydra is resumed by calling hydra-window/body in ace-window-end-once-hook.

This is a trick that I have to play because of how ace-jump-mode works. Hopefully, it won't be needed for other commands. But still, it's a simple trick that you can use if you want to have a head quit conditionally, or something.

`goto-line` ad infinum

(defhydra hydra-test (global-map "M-g")
  ("g" goto-line "goto-line"))

With the Hydra above, it's possible to:

M-g g 10 RET to go to line 10
g 20 RET to go to line 20
g 50 RET to go to line 50 etc.

Change the cursor color when a Hydra is active

Here's how the new :pre and :post statements work:

(global-set-key
 (kbd "C-z")
 (defhydra hydra-vi
     (:pre
      (set-cursor-color "#40e0d0")
      :post
      (set-cursor-color "#ffffff"))
   "vi"
   ("l" forward-char)
   ("h" backward-char)
   ("j" next-line)
   ("k" previous-line)
   ("q" nil "quit")))

In this example, the cursor color will change for the duration of the Hydra. Both :pre and :post should match to a single Elisp statement; you can use progn to tie a bunch of statements together if you want.

A more evil `helm`

Lit Wakefield has a nice article on using hydra and helm together. Do check it out, I'll certainly steal some of his code.

Outro

I hope that you don't have an objection to Hydra being developed at a fast pace with many features popping up. I try my best to keep things backwards compatible, but I really want to quickly fix the areas where the code is lacking. Thanks to all the people contributing issues, especially @atykhonov and @nandryshak for the last two, which are the core of this version bump.

One Hydra Two Hydra Red Hydra Blue Hydra

2015-02-03T00:00:00+01:00

Hydra evolution picks up the pace with hydra 0.6.1. This version adds prefix arguments to all Hydras.

Some Examples

Look ma, no modifiers!

Now it's possible to write this:

(global-set-key
 (kbd "C-z")
 (defhydra hydra-vi ()
   "vi"
   ("l" forward-char)
   ("h" backward-char)
   ("j" next-line)
   ("k" previous-line)))

And now C-z 5j7l will move 5 lines down and 7 characters left, still with the option to press h, j, k, l some more.

Additionally C-z C-u C-u C-u k will move 64 lines up, since C-u multiplies its argument by 4 each time.

The good-old zoom

If you remember, this was the original Hydra:

(defhydra hydra-zoom (global-map "<f2>")
  "zoom"
  ("g" text-scale-increase "in")
  ("l" text-scale-decrease "out"))

Now, <f2> g 4g 2l will zoom in 5 times, and zoom out 2 times for a total of +3 zoom.

The good-old move-splitter

(defhydra hydra-splitter (global-map "C-M-s")
  "splitter"
  ("h" hydra-move-splitter-left)
  ("j" hydra-move-splitter-down)
  ("k" hydra-move-splitter-up)
  ("l" hydra-move-splitter-right))

This Hydra can benefit from numeric arguments as well: C-M-s l 40l will quickly make the right window a lot smaller.

If I wanted to type C-M-s 40 l, I would have to use this definition instead:

(global-set-key
 (kbd "C-M-s")
 (defhydra hydra-splitter ()
   "splitter"
   ("h" hydra-move-splitter-left)
   ("j" hydra-move-splitter-down)
   ("k" hydra-move-splitter-up)
   ("l" hydra-move-splitter-right)))

For that case, I would get the hint immediately after C-M-s and would be able to give the numeric argument immediately, but I wouldn't be able to bind anything else on C-M-s as a prefix, e.g.:

(global-set-key (kbd "C-M-s z") 'recenter-top-bottom)

The code above would give the error "Key sequence C-M-s z starts with non-prefix key C-M-s". So you can pick the method that you prefer, the choice is there.

The ultimate window switching setup

(global-set-key
 (kbd "C-M-o")
 (defhydra hydra-window ()
   "window"
   ("h" windmove-left)
   ("j" windmove-down)
   ("k" windmove-up)
   ("l" windmove-right)
   ("a" (lambda ()
          (interactive)
          (ace-window 1)
          (add-hook 'ace-window-end-once-hook
                    'hydra-window/body))
        "ace")
   ("v" (lambda ()
          (interactive)
          (split-window-right)
          (windmove-right))
        "vert")
   ("x" (lambda ()
          (interactive)
          (split-window-below)
          (windmove-down))
        "horz")
   ("s" (lambda ()
          (interactive)
          (ace-window 4)
          (add-hook 'ace-window-end-once-hook
                    'hydra-window/body))
        "swap")
   ("d" (lambda ()
          (interactive)
          (ace-window 16)
          (add-hook 'ace-window-end-once-hook
                    'hydra-window/body))
        "del")
   ("o" delete-other-windows "1" :color blue)
   ("i" ace-maximize-window "a1" :color blue)
   ("q" nil "cancel")))

The credit for this monster goes to bcarell, I just refined his approach with making ace-window not quit the hydra-window Hydra. This setup needs the latest ace-window.

Here's the result of C-M-o xvxv starting from a single window:

From here, I can quickly maximize the current window with o while simultaneously quitting the Hydra; i will maximize a window as well, but it will select it with ace-window, instead of maximizing the current one.

Note that, since numerical arguments are working now, 4a is the same as s (swap) and 16a or C-u C-u a is the same as d (delete).

Colorful Hydras

2015-02-02T00:00:00+01:00

This post advertises the release of hydra.el 0.5.0. The package was introduced in an earlier post and received some positive feedback. Currently, it's available in both GNU ELPA (slightly behind) and MELPA (always current).

The newfound utility

As I originally released the Hydra, I was asked if it was similar to this approach described on Endless Parentheses. I said that it's not, since Hydra commands are meant to be repeatable instead of being called just once.

Now, after I've designated the repeatable heads with red color and the one-off heads with blue color, Hydra can reproduce the mentioned approach. Here's how it looks like:

(global-set-key
 (kbd "C-c C-v")
 (defhydra hydra-toggle (:color blue)
   "toggle"
   ("a" abbrev-mode "abbrev")
   ("d" toggle-debug-on-error "debug")
   ("f" auto-fill-mode "fill")
   ("t" toggle-truncate-lines "truncate")
   ("w" whitespace-mode "whitespace")
   ("q" nil "cancel")))

And this is what I see in the echo area after pressing C-c C-v:

At this point:

q will cancel without doing anything. I think it's more convenient than doing the equivalent C-g with the global-set-key approach.
a, d, f, t, and a will call the appropriate function. The advantage of blue Hydra heads over global-set-key is that you immediately get the hint: this can be useful for rarely used commands.
as with the old red Hydra heads, pressing anything other than a, d, f, t, a, or q will vanquish the Hydra and call the key binding that you just pressed. This is different from the global-set-key approach, which would e.g. error to your C-c C-v C-n with "C-c C-v C-n is undefined", unlike the Hydra, which would call C-n (next-line).

The full `defhydra` syntax

Note that defhydra looks intentionally like a defun, so that it's easier to remember how it works. Here's a more verbose Hydra that's largely equivalent to the one above:

(defhydra hydra-toggle (global-map "C-c" :color red)
   "toggle"
   ("a" abbrev-mode "abbrev" :color blue)
   ("d" toggle-debug-on-error "debug" :color blue)
   ("f" auto-fill-mode "fill" :color blue)
   ("t" toggle-truncate-lines "truncate" :color blue)
   ("w" whitespace-mode "whitespace" :color blue)
   ("v" recenter-top-bottom "recenter" :color red)
   ("q" nil "cancel" :color blue))
(global-set-key (kbd "C-c C-v") 'hydra-toggle/body)

First argument: Hydra name

This argument decides the prefix to all the functions that will be generated. In this case the following functions will be generated:

hydra-toggle/abbrev-mode
hydra-toggle/toggle-debug-on-error
hydra-toggle/auto-fill-mode
hydra-toggle/toggle-truncate-lines
hydra-toggle/whitespace-mode
hydra-toggle/recenter-top-bottom
hydra-toggle/nil
hydra-toggle/body

The final function calls the Hydra's body, displaying the hint in the echo area and setting the transient map. It's the return result of defhydra, that's why it was possible to pass it to global-set-key in the first example.

Second argument: Hydra body

The Hydra body consists of:

a map used for binding, like global-map or c++-mode-map or projectile-mode-map
the body prefix: it's a string passable to kbd that will be used in conjunction with heads' prefixes to bind the functions
an optional plist, which currently recognizes only the :color key, which in turn can be either red (the old behavior) or blue.

It's possible to omit the map and the body prefix simultaneously (it doesn't make sense to omit one but not the other), or just pass () if you want to get a red Hydra body that you can bind yourself.

Third argument: Hydra hint

This string will be used in the echo area to distinguish the current Hydra. This is optional, it case you don't provide it, it will default to "hydra".

Fourth argument: Hydra heads

Each Hydra head is a list of:

the key extension
the function
optional hint
optional plist.

Again, the plist recognizes only :color currently. The color is inherited from the body, if you don't specify it. In turn, the body color is red if you don't specify it.

The code above:

binds C-c a, C-c d etc with the usual global-set-key approach.
binds C-c C-v a, C-c C-v d with the new approach, which shows you the hint right after C-c C-v and allows you to cancel easier.
binds C-c v to be repeatable, i.e. you can press C-c v v v. Same with C-c C-v v v v.

Some more ideas for blue Hydras

Here's one for some helm-related functions, don't ask how projectile-find-file ended up here:

(global-set-key
 "κ"
 (defhydra hydra-helm (:color blue)
   "helm"
   ("f" projectile-find-file "file")
   ("w" helm-org-wiki "wiki")
   ("r" helm-recentf "recent")
   ("s" helm-swoop "swoop")
   ("q" nil "quit")))

Here's one more for gnus; I'm just getting the hang of it, so some hints are useful:

(defhydra hydra-gnus-reply (:color blue)
  "reply"
  ("o" gnus-summary-reply-with-original "one")
  ("O" gnus-summary-reply)
  ("a" gnus-summary-wide-reply-with-original "all")
  ("A" gnus-summary-wide-reply)
  ("u" gnus-summary-very-wide-reply-with-original "universe")
  ("U" gnus-summary-very-wide-reply)
  ("q" nil "quit"))
(define-key gnus-summary-mode-map "r" 'hydra-gnus-reply/body)

I omit the hint for the commands that do the same as the previous one, just without citing.

Outro

I hope that you enjoy the update and let me know when you invent some efficient blue or red-and-blue Hydras. Happy hacking!

Blogging about blogging

2015-02-01T00:00:00+01:00

In Emacs, of course. As I mentioned before, this blog is run using Jekyll and a fork of the lanyon theme.

It started out pretty convenient: thanks to jekyll serve I would see the live updates at http://localhost:4000/ as I was editing the markdown. But after a few posts, I've experienced a drastic decrease in refresh time: it went from under a second to 15 seconds. Below, I'll show how I've managed to speed it back up.

No posts - no problem

Thanks to (require 'dired-x) I can jump from the current post to the posts directory with C-x C-j. It even puts the point on the current file. Now:

m to mark to current file
t to invert the mark, making the current file unmarked and all others marked
D to delete all marked files. No need to worry, since they are all version-controlled (except the original one, which isn't being deleted), dired even asks you for confirmation, so I hit y.

Now, that there is only one post in the whole blog, jekyll serve is much faster at refreshing.

Even faster `jekyll serve`

Which brings me to the next point. Since I'm calling it so much, might as well wrap it in some Elisp. Elisp is like frosting - it makes everything better:

(defun jekyll-serve ()
  (interactive)
  (let* ((default-directory
          (if (string-match "_posts/$" default-directory)
              (directory-parent default-directory)
            default-directory))
         (buffer (if (get-buffer "*jekyll*")
                     (switch-to-buffer "*jekyll*")
                   (ansi-term "/bin/bash" "jekyll")))
         (proc (get-buffer-process buffer)))
    (term-send-string proc "jekyll serve\n")
    (sit-for 3)
    (browse-url "localhost:4000")))

This function, when called from the current post or the current blog, will:

open a new ansi-term called *jekyll*
issue a jekyll serve command to it
wait for 3 seconds for Jekyll to start
open localhost:4000 in Firefox

One post isn't a blog

Here's how to quickly bring back the deleted posts.

Fire up magit; I have magit-status bound to μm.
Stage the current post with s (magit-stage-item).
Start the commit with C (magit-commit-add-log). I'm using my own modification of magit-commit-add-log that arranges the whitespace in a nice way, when aimed at a file instead of a hunk.
I get _posts/2015-02-01-blogging-about-blogging.md: string auto-generated by C.
I just amend it to look like _posts/2015-02-01-blogging-about-blogging.md: add and finalize the commit with C-c C-c (git-commit-commit).
Now I have around 40 files marked as deleted, but not staged. I create a stash with zz and name it foo or something. Then delete the stash with magit-discard-item, which I like to bind to d to be similar to dired. Now it's as if these files were never deleted.

Whoa, now that I look at it, it's a lot of steps. But somehow dired and magit are very similar to Super Mario Bros: it takes long to explain what you're doing, but as you play it, it's very simple and natural.

abel.el - abbrevs for Elisp

2015-01-31T00:00:00+01:00

This is a follow-up to an older post about abbrevs.

I did try to make Elisp abbrevs work, but after a few times of getting is expanded to indent-sexp in strings or comments, I just could take it no longer.

Luckily and timely, Artur Malabarba revealed his speed-of-thought-lisp. This package does many things, but the main idea that I liked was that the abbrevs should only expand when in the function position, i.e. the abbrev is:

right after opening parenthesis
not in a comment
not in a string
not in the arguments list

With that idea, I've "refactored" my old abbrevs into Abel. It's a minor mode add-on for abbrev-mode. When you activate it, around a hundred abbrevs are added to your abbrev list for emacs-lisp-mode. When you deactivate it, these abbrevs are disabled, and your original abbrev list is restored. It even overrides the mode-line description to Abbrev -> Abel while it's active, thanks to diminish.

So while you should try sotl, which provides many other things, keep abel in mind: it's a simple upgrade to abbrev-mode that binds no bindings and asks no questions.

Here's the current list:

(defcustom abel-abbrevs
  '(
    ;; basics
    ("a" "and")
    ("bp" "boundp")
    ("c" "concat")
    ("fp" "fboundp")
    ("ii" "interactive")
    ("i" "insert")
    ("l" "lambda")
    ("m" "message")
    ("n" "not")
    ("f" "format")
    ("u" "unless")
    ("up" "unwind-protect")
    ("w" "when")
    ("wl" "while")
    ("r" "require")
    ("ci" "call-interactively")
    ("cc" "condition-case")
    ("pg" "plist-get")
    ("sa" "save-excursion")
    ("sr" "save-restriction")
    ("smd" "save-match-data")
    ;; defines
    ("de" "declare-function")
    ("df" "defface")
    ("da" "defmacro")
    ("du" "defcustom")
    ("dv" "defvar")
    ;; everything with char
    ("bc" "backward-char")
    ("scb" "skip-chars-backward")
    ("scf" "skip-chars-forward")
    ("gc" "goto-char")
    ("fc" "forward-char")
    ("dc" "delete-char")
    ("ca" "char-after")
    ;; everything with region
    ("ra" "region-active-p")
    ("rb" "region-beginning")
    ("re" "region-end")
    ("ntr" "narrow-to-region")
    ("dr" "delete-region")
    ("ir" "indent-region")
    ;; error related
    ("ie" "ignore-errors")
    ("e" "error")
    ;; regex match related
    ("la" "looking-at")
    ("lb" "looking-back")
    ("mb" "match-beginning")
    ("me" "match-end")
    ("ms" "match-string")
    ("msn" "match-string-no-properties")
    ("rm" "replace-match")
    ("ro" "regexp-opt")
    ("rq" "regexp-quote")
    ("rr" "replace-regexp-in-string")
    ("rsb" "re-search-backward")
    ("rsf" "re-search-forward")
    ("sf" "search-forward")
    ("sm" "string-match")
    ;; words
    ("fw" "forward-word")
    ("bw" "backward-word")
    ;; lines
    ("eol" "end-of-line")
    ("fl" "forward-line")
    ("lbp" "line-beginning-position")
    ("lep" "line-end-position")
    ("nai" "newline-and-indent")
    ;; buffer
    ("bfn" "buffer-file-name")
    ("bn" "buffer-name")
    ("bs" "buffer-substring")
    ("bsn" "buffer-substring-no-properties")
    ("cb" "current-buffer")
    ("wcb" "with-current-buffer")
    ("wtb" "with-temp-buffer")
    ("efn" "expand-file-name")
    ("ff" "find-file")
    ("ffn" "find-file-noselect")
    ;; window
    ("ow" "other-window")
    ("sw" "selected-window")
    ;; string
    ("ssn" "substring-no-properties")
    ("ss" "substring")
    ("si" "split-string")
    ("se" "string=")
    ("sl" "string<")
    ("sp" "stringp")
    ;; point
    ("pi" "point-min")
    ("pa" "point-max")
    ("p" "point")
    ;; key
    ("gk" "global-set-key")
    ("dk" "define-key")
    ;; rest
    ("ah" "add-hook")
    ("atl" "add-to-list")
    ("bod" "beginning-of-defun")
    ("bol" "beginning-of-line")
    ("dm" "deactivate-mark")
    ("fs" "forward-sexp")
    ("jos" "just-one-space")
    ("kn" "kill-new")
    ("lp" "load-path")
    ("mm" "major-mode")
    ("sic" "self-insert-command")
    ("sn" "symbol-name")
    ("tap" "thing-at-point")
    ("tc" "this-command")
    ("ul" "up-list"))
  "List of (ABBREV EXPANSION) used by `abel'."
  :set (lambda (symbol value)
         "Update abbrevs accoring to `abel-abbrevs'."
         (set symbol value)
         (mapc #'abel-define value))
  :group 'abel)

Re-introducing auto-yasnippet

2015-01-30T00:00:00+01:00

I wonder, when the code isn't touched in a long time, is it good (no need for changes) or bad (became obsolete)? Let's find out. I'll explain here auto-yasnippet, my second package in MELPA out of more than a dozen currently that saw almost no changes since the initial commit two years ago, and see if you like it.

Short description of `yasnippet`

YASnippet is a template system for Emacs. It allows you to type an abbreviation and automatically expand it into function templates. Bundled language templates include: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML, CSS and more.

Snippet step-by-step

Here's one of the snippets that I use for emacs-lisp-mode:

# -*- mode: snippet -*-
# name: function
# key: d
# --
(defun $1 ($2)
$0)

The name of the snippet, function is more like a comment than anything else.
On the other hand, key is very important: it's what I have to insert in the buffer to get the expansion with M-x yas-expand.
Everything after # -- is the snippet body.
This particular snippet has two fields, in places of $1 and $2.
$0 is where the point will be when the snippet expansion is finished

As I expand, pressing TAB will move from field to field until the expansion is finished.

Snippets are mode-local

Here's the corresponding snippet for clojure-mode:

# -*- mode: snippet -*-
# name: defn
# key: d
# --
(defn $1 [$2]
$0)

As you see, the key here is the same; you're allowed to overload them based on the current major-mode.

Even after quite a few posts, I still keep forgetting Jekyll's syntax for the post header. This is my reminder:

# -*- mode: snippet -*-
# name: post
# key: post
# --
---
layout: post
title: $0
---

Mirrors in snippets

This simple snippet introduces a powerful concept, and an important yasnippet feature that auto-yasnippet uses:

# -*- mode: snippet -*-
#name : class ... { ... }
# --
class $1$2
{
public:
 $1($0)
};

This is a snippet for a class declaration in c++-mode; $1, the name of the class, is mirrored in the name of the constructor. This way, you don't have to enter it twice.

What `auto-yasnippet` does

All the snippets listed above are pre-configured, persistent and very rarely changed. They are like plain functions in the source code. Each of them needs their own file and so on.

What auto-yasnippet provides are throw-away lambdas, that don't need a file and aren't persistent.

Basic install of `auto-yasnippet`

To get a usable install, you just need to bind aya-create, which is similar in spirit to M-w (kill-ring-save):

(global-set-key (kbd "H-w") 'aya-create)

and aya-expand, which is similar to C-y (yank):

(global-set-key (kbd "H-y") 'aya-expand)

I also like to bind:

(global-set-key (kbd "C-o") 'aya-open-line)

I'm using C-o to do all of these:

expand-abbrev
yas-expand and yas-next-field-or-maybe-expand
open-line

Example 1: JavaScript

Let's say that you have this code and want to generate more like it:

field1 = document.getElementById("field1");

Let's even assume that you know how auto-yasnippet works and wrote down a slightly modified code beforehand:

field~1 = document.getElementById("field~1");

Here, ~ are meant to represent yasnippet's mirrors, they will be consistent across every expansion. Now you type H-w (aya-create), which works on the current line when there's no region. Your code becomes the initial one without ~, and aya-current variable now holds:

aya-current
;; => "field$1 = document.getElementById(\"field$1\");"

By typing e.g. H-y 2 C-o RET, H-y 3 C-o RET, H-y Final C-o RET you get:

field2 = document.getElementById("field2");
field3 = document.getElementById("field3");
fieldFinal = document.getElementById("fieldFinal");

Note again, that there would be little point to saving this snippet in a file, since the situation where you need to use it may not come up again.

Example 2: Java

Here's the starting code, with fields and mirrors already in place (note one mirror named ~On, one field named ~on and one field named ~true):

class Light~On implements Runnable {
  public Light~On() {}
  public void run() {
    System.out.println("Turning ~on lights");
    light = ~true;
  }
}

Since the code spans multiple lines, as is often the case with Java, you need to mark it with a region before H-w.

Here's the final result:

class LightOn implements Runnable {
  public LightOn() {}
  public void run() {
    System.out.println("Turning on lights");
    light = true;
  }
}
class LightOff implements Runnable {
  public LightOff() {}
  public void run() {
    System.out.println("Turning off lights");
    light = false;
  }
}

No need for AbstractLightFactoryAdapterProvider when we can just copy-paste stuff with auto-yasnippet. In fact, I should probably emphasize that when describing auto-yasnippet: it's just an advanced copy-paste tool.

Example 3: C++

Suppose that I want to generate curl from the grad. I can start with this template:

const Point<3> curl(grad[~2][~1] - grad[~1][~2],

Here, I need less than a line, so region needs to be marked again. The result:

    const Point<3> curl(grad[2][1] - grad[1][2],
                        grad[0][2] - grad[2][0],
                        grad[1][0] - grad[0][1]);

Note how annoying it would be to triple check that the indices match. This time, I just had to check the first line.

Example 4: taking `~` out of the equation

This works only for one-line snippets with a single mirror parameter. In the JavaScript example, you can leave a $ instead of each occurrence of $1, and with the point in place of the last occurrence you call H-w (aya-create). Here, | represents the point:

field$ = document.getElementById("|");

The final result is the same:

field1 = document.getElementById("field1");
field2 = document.getElementById("field2");
field3 = document.getElementById("field3");
fieldFinal = document.getElementById("fieldFinal");

Outro

I hope that this package will lessen your suffering when dealing with verbose programming languages and repetitive text, and that a day will come when repetition is no longer needed and auto-yasnippet will become obsolete.

Combining ace-window and windmove with hydra

2015-01-29T00:00:00+01:00

I was inspired by Sacha Chua's recent post explaining her window bindings, that combine both ace-window and windmove. So I wrote down an update to Hydra in order to get a similar setup.

Sacha's code

Here it is:

(key-chord-define-global
 "yy"
 (sacha/def-rep-command
  '(nil
    ("<left>" . windmove-left)
    ("<right>" . windmove-right)
    ("<down>" . windmove-down)
    ("<up>" . windmove-up)
    ("y" . other-window)
    ("h" . ace-window)
    ("s" . (lambda () (interactive) (ace-window 4)))
    ("d" . (lambda () (interactive) (ace-window 16))))))

My code

Here's what I've come up with, thanks to the newest code in hydra:

(defun hydra-universal-argument (arg)
  (interactive "P")
  (setq prefix-arg (if (consp arg)
                       (list (* 4 (car arg)))
                     (if (eq arg '-)
                         (list -4)
                       '(4)))))

(defhydra hydra-window (global-map "C-M-o")
  "window"
  ("h" windmove-left "left")
  ("j" windmove-down "down")
  ("k" windmove-up "up")
  ("l" windmove-right "right")
  ("a" ace-window "ace")
  ("u" hydra-universal-argument "universal")
  ("s" (lambda () (interactive) (ace-window 4)) "swap")
  ("d" (lambda () (interactive) (ace-window 16)) "delete")
  ("o"))

(key-chord-define-global "yy" 'hydra-window/body)

The new code should already be available in MELPA. I'll update the code in GNU ELPA soon, when I make sure that there were no bugs introduced by the change.

If anyone wants to see how the defhydra macro expands, you can check out hydra-test.el. I just added a Travis CI setup, so if you're interested in starting to test your Elisp code, you can have a very simple example.

How the defined Hydra works

With this setup:

to swap two windows (i.e. call C-u ace-window), I can do any of:
- C-M-o s
- C-M-o ua
- yys
- yyua
to delete one window (i.e. call C-u C-u ace-window), any of:
- C-M-o d
- C-M-o uua
- yyd
- yyuua
to move one window down, two windows right, and one window up:
- C-M-o jllk
- yyjllk

Although every other shortcut except the Hydra heads will vanquish the Hydra, sometimes I have nothing on my mind that needs doing. For that case, as you can see above, I enter o in its own list without a function, so that o will dismiss the Hydra without doing anything.

A few notes on Elisp indentation

2015-01-28T00:00:00+01:00

I sure do like to keep my Elisp code nice and indented. But sometimes the indentation engine just won't listen.

lisp-indent-function

By default, the indentation is handled as if:

(setq lisp-indent-function 'lisp-indent-function)

At least in one case, it looks horrible:

(cl-labels ((square (x)
                    (* x x)))
  (mapcar #'square '(0 1 2 3 4 5)))
;; => (0 1 4 9 16 25)

That's why I have:

(setq lisp-indent-function 'common-lisp-indent-function)

which leads to this indentation:

(cl-labels ((square (x)
              (* x x)))
  (mapcar #'square '(0 1 2 3 4 5)))
;; => (0 1 4 9 16 25)

Ah, much better. The indentation does change a bit in other places as a result of this. To my experience, it can be fixed on a case-by-case basis by declaring the indent level for the offending function or macro.

Declaring indent level

Here's how it looks like

(defmacro lispy-save-excursion (&rest body)
  "More intuitive (`save-excursion' BODY)."
  (declare (indent 0))
  `(let ((out (save-excursion
                ,@body)))
     (when (bolp)
       (back-to-indentation))
     out))

By default, functions behave as if their indent was declared to nil. Zero here means that we expect zero arguments on the same line, so that this indentation follows:

(lispy-save-excursion
  (lispy--out-forward arg)
  (backward-list)
  (indent-sexp))

The indentation above is just like the one that the original save-excursion has. Note that if I hadn't declared the indent, it would look like this:

(lispy-save-excursion
 (lispy--out-forward arg)
 (backward-list)
 (indent-sexp))

The impact is much larger for statements that require an indent of 1:

Compare the proper thing:

(lispy-dotimes arg
  (when (= (point) (point-max))
    (error "Reached end of buffer"))
  (forward-list))

to this horror:

(lispy-dotimes arg
               (when (= (point) (point-max))
                 (error "Reached end of buffer"))
               (forward-list))

Outro

I've shown two things you can try if you find your Elisp indentation annoying. If you know of more, let me know.

My "refactoring" workflow

2015-01-27T00:00:00+01:00

Well, "refactoring" is for the Java people, I simply rename things. Just today, I had to do a big rename operation related to the release of lispy 0.22.0. Below, I'll share some functions and packages that I used for that.

My Github setup

Here's it (tree -da -L 1) is:

.
├── .cask
├── gh-pages
├── .git
└── images

I've cloned my gh-pages branch into its own git repository inside the original lispy repository. This way, I can rename functions in the code and the documentation simultaneously.

Declaring functions obsolete in Elisp

It can be done like this:

(define-obsolete-function-alias 'lispy-out-forward
    'lispy-right "0.21.0")
(define-obsolete-function-alias 'lispy-out-backward
    'lispy-left "0.21.0")
(define-obsolete-function-alias 'lispy-out-forward-nostring
    'lispy-right-nostring "0.21.0")

After version "0.21.0" hits, any time you call lispy-left by its now obsolete alias lispy-out-backward, you'll get a message:

`lispy-out-forward' is an obsolete command (as of 0.21.0); use `lispy-right' instead.

So now, since I'm releasing version "0.22.0", I can remove even the alias declarations. I gave people one week of warnings to adjust (just rename to the new name) any of their code that's calling the currently obsolete functions.

Renaming obsolete functions in the documentation

Taking advantage of the repository setup, I can:

Step 1: call `rgrep`

rgrep is a fine function, I wonder why it's not bound by default; I bind it to C-<, taking advantage of my weird key mappings (I'm actually pressing the C-;-l physical keys).

It requires 3 inputs:

Symbol to search for: I call it with the point positioned on the symbol that I want to rename in the code, in the middle of the define-obsolete-function-alias tag, so rgrep picks up the symbol name as the default and I just type RET to select it.
File pattern: *.el, the current file extension is the default. I type * RET, since I want to match the org and html files as well.
Base directory: this directory will be will be recursively searched for files that match the file pattern; the default ~/git/lispy/ is fine here, RET.

Step 2: call `wgrep`

wgrep is a fine package, I wonder why it's not more popular. Since it's so similar to wdired (one of the best things since sliced bread, btw), I like to bind the starter to C-x C-q and the finisher to C-c C-c as well:

(eval-after-load 'grep
  '(define-key grep-mode-map
    (kbd "C-x C-q") 'wgrep-change-to-wgrep-mode))

(eval-after-load 'wgrep
  '(define-key grep-mode-map
    (kbd "C-c C-c") 'wgrep-finish-edit))

Step 3: call `iedit`

iedit is an amazing package, it's crazy-good. Here's how I bind it, since once iedit-mode is on, you can move to the next occurrence with C-i:

(global-set-key (kbd "C-M-i") 'iedit-mode)

In order to change really every occurrence in the buffer, I need to mark the thing that I want to change, before C-M-i. Otherwise, iedit will automatically add symbol bounds (a nice feature, actually), so that e.g. =lispy-out-forward= will not match lispy-out-forward.

Finally, I interactively, char-by-char, rename e.g. lispy-out-forward to lispy-right. The experience is similar to the popular multiple-cursors, which I also like to use, just for different purposes.

Step 4: exiting

When I'm done:

I exit iedit-mode with C-M-i.
I exit wgrep with C-c C-c
I save all affected files if I want, since they aren't saved yet and it's still possible to revert everything.

Outro

Woah, that's a lot of steps!

True, but do note that all three tools can be used on their own for various other tasks. See for instance my other "refactoring" demo, that uses iedit-mode to unbind a let-bound variable in Elisp (should also work for Common Lisp, since the syntax is the same).

There's beauty and utility in having such composable tools. A lot of the time, it's better than to just have one "Rename" button. For instance, when only one buffer is involved, the rgrep-wgrep step can be skipped and I can rename stuff with iedit-mode only.

Or, when the playground for renaming is less than a buffer, I can:

C-x nd - narrow-to-defun or C-x nn - narrow-to-region (both are equivalent to N in lispy)
iedit-mode
C-x nw - widen (W in lispy)

occur-dwim (Do What I Mean)

2015-01-26T00:00:00+01:00

I'd like to share a little snippet that I like to use instead of a plain M-s o (occur).

smarter-than-the-average-occur

(defun occur-dwim ()
  "Call `occur' with a sane default."
  (interactive)
  (push (if (region-active-p)
            (buffer-substring-no-properties
             (region-beginning)
             (region-end))
          (let ((sym (thing-at-point 'symbol)))
            (when (stringp sym)
              (regexp-quote sym))))
        regexp-history)
  (call-interactively 'occur))

It will offer as the default candidate:

the current region, if it's active
the current symbol, otherwise

It's pretty good, since I actually want the default candidate in 95% of the cases. Some other functions, such as rgrep are smart like this out-of-the-box.

A Hydra that goes nicely with `occur`

Since occur, like some other functions (grep, rgrep, compile), works with next-error, it's possible to use this Hydra to navigate the occur matches:

(hydra-create "M-g"
  '(("h" first-error "first")
    ("j" next-error "next")
    ("k" previous-error "prev")))

Hydra was introduced in an earlier post, and is available in GNU ELPA.

What goes around comes around

I usually do a quick internet search to see where I got the code that I'm posting here, reason being that it's nice to list the source, as well as there could be more advanced stuff out there on the same topic.

I saw a few results for "occur-dwim" so I thought that I just copy-pasted it from somewhere. Slight disappointment turned into a small sense of pride, when I found that the source of the copy-pastes was my old Stack Overflow answer:)

Exploring Emacs packages

2015-01-25T00:00:00+01:00

Currently, MELPA hosts over 2250 packages. That's quite a large number, although it's still feasible to try most of the popular ones. In comparison,

apt-cache pkgnames | wc

gives me the number 50250. I don't recall calling apt-cache pkgnames ever before, while I call package-list-packages all the time. I suppose that this will have to change when the number of packages grows further.

I usually explore packages just as they show up as new in package-list-packages. I'll share the two tools that I use for exploring them.

Smex

Smex is an M-x enhancement for Emacs. In addition to executing commands faster, it gives you an option to jump to the current command's definition with M-..

Here's how I bind smex:

(require 'smex)
(global-set-key "\C-t" 'smex)
(defun smex-prepare-ido-bindings ()
  (define-key ido-completion-map
      (kbd "C-,") 'smex-describe-function)
  (define-key ido-completion-map
      (kbd "C-w") 'smex-where-is)
  (define-key ido-completion-map
      (kbd "C-.") 'smex-find-function)
  (define-key ido-completion-map
      (kbd "C-a") 'move-beginning-of-line)
  ;; (define-key ido-completion-map "\C-i" 'smex-helm)
  ;; (define-key ido-completion-map " " 'smex-helm)
  )

I don't feel bad at all for unbinding transpose-chars, C-t is such a prime binding, that only the best commands can deserve it. And since I touch-type, it's easier for me to hit M-DEL and retype the word when I notice a mistake, than to carefully navigate to the mistake location and call transpose-chars with surgical precision. On the other hand, the number of Emacs packages is only going to grow, so it becomes less and less feasible to bind everything. Instead, seldom used stuff can be called though smex. For instance, I don't bind markdown-toc or speed-type and call them via C-t instead.

Back to the point, C-t ... C-. (smex-find-function) allows me to quickly jump to the source of the package that I want to explore.

Semantic tags

Once I'm in the source code, I can quickly get an overview with g (lispy-goto) from lispy. It uses CEDET's semantic module to get a list of tags in current directory with helm for completion. In my opinion, it's much prettier than helm's own helm-semantic. It also explores more tags for Emacs Lisp, for instance it will capture use-package and global-set-key tags.

A new cute feature that I added recently is a different background for user-visible functions, i.e. the ones that are callable by M-x or smex. Here's how it looks like, for the speed-type package (interactive functions have a purple background):

If the image text looks too small, you can right click / view image in your browser. Here, I can see at a glance, that there are three commands that I can call. I can also see a few variables, two of them don't include --, so they're probably customizable.

Do things after selecting window

2015-01-24T00:00:00+01:00

I saw this question today at Stack Overflow - Emacs: How to enable toolbar mode and menubar mode only under a certain mode?. Myself, I never use the menubar or the toolbar. But maybe it's just because it's useless in the modes to which I'm used to. What if there was an option to have the menu bar on just for a few select modes? For instance, if I decided that I want to learn Haskell tomorrow, I wouldn't mind to have the menu bar on for a while, especially if there was some useful stuff there in the menu.

The Code

I'm not aware of a convenient hook for this job; I tried after-change-major-mode-hook, and it doesn't work when switching windows. The universal post-command-hook would be totally lame for this task.

Then it occurred to me, that select-window has to be called eventually in most circumstances. Even ace-window calls select-window.

This is what I came up with so far:

(defvar menubar-last
  (make-ring 20))
(ring-insert menubar-last "dummy")

(defadvice select-window (after select-window-menubar activate)
  (unless (equal (buffer-name) (ring-ref menubar-last 0))
    (ring-insert menubar-last (buffer-name))
    (let ((yes-or-no
           (if (memq major-mode '(r-mode lisp-interaction-mode))
               1 -1)))
      (menu-bar-mode yes-or-no)
      (tool-bar-mode yes-or-no))))

The Ring trickery

It's necessary at least for magit. Doing, for instance, ll operation switches windows many times. So I added a check that the current buffer isn't selected twice.

In Emacs, a ring is like a stack with a limited length: you push onto the head, and if the stack becomes too large, the stuff gets removed from the tail. Perfect for debugging this code, since I don't care what happened 20 window switches ago, I'm only interested in the most recent state. One small annoyance is that the following code will throw, if the ring is empty:

(ring-ref menubar-last 0)

I would prefer if it just returned nil instead. Hence the trick of initializing menubar-last with a dummy item. Note that this annoyance propagates to other areas: (current-kill 0) will throw if you haven't yet copied text since Emacs started.

Outro

I'm not sure if this code is more annoying than useful, but, at least, I learned something new while writing it, and I hope you did too. If you know of a better way to accomplish the original task, please do share.

ElTeX - generate full LaTeX documents from Emacs Lisp

2015-01-23T00:00:00+01:00

OK. Please stop laughing. It's a thing now.

Seriously though, it's my little project of writing a major mode for Emacs. I've written many minor modes, but this is my first major one. Granted, it's only a small derivation of emacs-lisp-mode.

How the ElTeX looks like

Here's how a sample document outline looks like:

Here, homogenization, smoluchowski-equation, and model-description-geometry are simply Elisp functions that should produce a string on call. They are defined here.

On calling M-x eltex-compile, the corresponding LaTeX document will be written to the file to which eltex-filename points to.

How the corresponding LaTeX looks like

Here's an excerpt of what will be generated:

\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage{amsthm}
\usepackage{enumerate}
\usepackage{amsfonts}
\usepackage{xcolor}
\usepackage[style=numeric,natbib=true,backend=bibtex]{biblatex}
\addbibresource{analysis.bib}
\begin{document}

\section{Introduction}

\subsection{Homogenization}

How the original ElTeX looks like in `emacs-lisp-mode`

(setq eltex-filename "~/tpaper/tpaper.tex")
(require 'eltex-macros)

;;* Document
(documentclass
 "article"
 (usepackage
  '("amsmath" "fleqn")
  "amsthm"
  "enumerate"
  "amsfonts"
  "xcolor"
  '("biblatex" "style=numeric,natbib=true,backend=bibtex"))
 (bibliography "analysis")
 (document
  (section "Introduction"
           (homogenization)
           (smoluchowski-equation))
  (section "Notations and Assumptions"
           (model-description-geometry))
  "\\printbibliography"))

Why this?

Well, why not? At one point I was frustrated with LaTeX not allowing me to define mathematically rich entities. I did hack up a few TeX macros for this eventually, but it was very awkward.

So I thought that I could make Emacs Lisp generate simple LaTeX in a similar way that C generates machine code. No more intricate LaTeX macros, only plain LaTeX, generated from (intricate) Elisp.

This is still very much in a toy stage, I don't currently use it for anything serious. Still, in case you're interested in defining derived major modes, you can look at my implementation, it's only 25 lines. The interesting thing about it, if you noticed, is that it replaces all double quoted strings visually with single quoted strings, so that they don't jump out as much.

More examples

Here's how the typesetting of some mathematical logic looks like:

And here's the corresponding LaTeX:

Note how simple the resulting LaTeX is, considering how many variables were used to generate it. Now, I can update anything in the with Elisp binding, and the corresponding LaTeX will be appropriately regenerated, error-free.

Adding a bit of Clojure's sugar to Elisp

2015-01-22T00:00:00+01:00

I just wanted to highlight my latest submission to emacs-devel.

The patch

The attached patch, together with the macro short-lambda will add a shorthand for defining lambdas in Emacs Lisp.

Here's an excerpt from the Clojure reader docs

Anonymous function literal (#())

#(...) => (fn [args] (...))

where args are determined by the presence of argument literals taking the form %, %n or %&. % is a synonym for %1, %n designates the nth arg (1-based), and %& designates a rest arg. This is not a replacement for fn - idiomatic used would be for very short one-off mapping/filter fns and the like.

#() forms cannot be nested.

What the patch does

It makes it possible to write this in Elisp:

(mapc #(put % 'disabled nil)
      '(upcase-region downcase-region narrow-to-region))

You can also do this and other things that you would expect, if you're familiar with Clojure:

(cl-mapcar #(concat %1 " are " %2)
           '("roses" "violets")
           '("red" "blue"))
;; => ("roses are red" "violets are blue")

Or you could replace this snippet from org-mode's code:

(mapcar (lambda (x)
          (and (member (car x) matchers) (nth 1 x)))
        org-latex-regexps)

with this sugar-coated code:

(mapcar #(and (member (car %) matchers) (nth 1 %))
        org-latex-regexps)

Outro

I hope that this gets accepted, although there are some conservative people that protest against this change. Let me know if you would like to have this option for your Elisp setups. And remember that you can try out the patch if you're familiar with building Emacs from source.

Even more dired key bindings

2015-01-21T00:00:00+01:00

I've posted about dired quite a few times now. Below, I'll do a short review of the old bindings and add a few remaining recipes from my dired.el.

Old stuff

Binding r to dired-start-process is covered here.
Binding e to ediff-files is mentioned here.
Binding z to dired-get-size is covered here.
Binding ` to dired-open-term is covered here.

Jump to a file with `ido`

(define-key dired-mode-map "i" 'ido-find-file)

I use this one quite frequently: i is somehow mnemonic to C-i, which means completion. Remember that you can select the current candidate with C-m and the current text (usually to create a new file) with C-j.

Move up and down

(define-key dired-mode-map "j" 'dired-next-line)
(define-key dired-mode-map "k" 'dired-previous-line)

As I've mentioned before, this is my standard recipe for all modes that don't self-insert.

Flag garbage files

(define-key dired-mode-map (kbd "%^") 'dired-flag-garbage-files)

Huh, I always thought this was the default binding. I have no idea where this came from, but I use this plus x to get rid of the garbage produced by a LaTeX run:

(setq dired-garbage-files-regexp
      "\\.idx\\|\\.run\\.xml$\\|\\.bbl$\\|\\.bcf$\\|.blg$\\|-blx.bib$\\|.nav$\\|.snm$\\|.out$\\|.synctex.gz$\\|\\(?:\\.\\(?:aux\\|bak\\|dvi\\|log\\|orig\\|rej\\|toc\\|pyg\\)\\)\\'")

Emacs' adaptation of `find`

(define-key dired-mode-map "F" 'find-name-dired)

This little function is essential if you want to do perform some operation on all files in the current directory and its sub directories that match a pattern. Basically the same thing that you would do with the UNIX find, just better.

Ignore unimportant files

(define-key dired-mode-map (kbd "M-o") 'dired-omit-mode)

This will toggle the display of unimportant files, like:

(setq dired-omit-files "\\(?:.*\\.\\(?:aux\\|log\\|synctex\\.gz\\|run\\.xml\\|bcf\\|am\\|in\\)\\'\\)\\|^\\.\\|-blx\\.bib")

Move to the parent directory

(define-key dired-mode-map "a"
    (lambda ()
      (interactive)
      (find-alternate-file "..")))

There probably is a default function that does this. I've been using this one for years, probably because it reuses the current dired buffer of opening the parent directory.

Outro

Phew, that's a lot of bindings. I don't necessarily encourage you to use the same bindings as me; I just want to bring your attention to some of these functions, so that you can work them into your workflow. If you notice that I'm using some obsolete stuff, do let me know, I'm always looking to improve.

Behold The Mighty Hydra!

2015-01-20T00:00:00+01:00

I managed to spike a lot of interest for sticky key bindings in my earlier post, Zoom in/out with style. So now, I've refactored this method into a convenient library hydra.el.

The Concept

This package can be used to tie related functions into a family of short bindings with a common prefix - a Hydra.

Once you summon the Hydra through the prefixed binding (the body + any one head), all heads can be called in succession with only a short extension.

The Hydra is vanquished once Hercules, any binding that isn't the Hydra's head, arrives. Note that Hercules, besides vanquishing the Hydra, will still serve his orignal purpose, calling his proper command. This makes the Hydra very seamless, it's like a minor mode that disables itself auto-magically.

An Example

This code will accomplish the task of the previous post:

(require 'hydra)
(hydra-create "<f2>"
  '(("g" text-scale-increase)
    ("l" text-scale-decrease)))

Now, <f2> is the Hydra's body: you need to press it only once, together with one of the heads (g or l), to summon the Hydra.

Afterwards, you can call the heads in succession without the body prefix, i.e. <f2> g g g l will work. To vanquish the Hydra, just call up Hercules: any key binding that's not g or l, e.g. C-f or whatever you wanted to do.

Note that you can still assign an unrelated binding to e.g. <f2> f: the Hydra does not take over <f2>, only over <f2> l and <f2> g.

The Infrastructure

hydra-create will create new interactive functions for you with the proper docstrings:

hydra-<f2>-text-scale-increase is an interactive Lisp function.

It is bound to <f2> g.

(hydra-<f2>-text-scale-increase)

Create a hydra with a "<f2>" body and the heads:

"g": text-scale-increase,
"l": text-scale-decrease.

Call the head: text-scale-increase.

An exciting new Hydra: move window splitter

Zooming is old news, Hydra bundles a new application:

(require 'hydra-examples)
(hydra-create "C-M-o" hydra-example-move-window-splitter)

or in the expanded form (equivalent):

(hydra-create "C-M-o"
  '(("h" hydra-move-splitter-left)
    ("j" hydra-move-splitter-down)
    ("k" hydra-move-splitter-up)
    ("l" hydra-move-splitter-right)))

This will allow you to move the window splitter, after you issue C-x 2 or C-x 3 one or more times, with e.g. C-M-o h h j k j l k l h. You can, of course, customize both the body and the heads of this Hydra to your preferences.

The docstrings for this Hydra look more impressive, too:

hydra-C-M-o-move-splitter-up is an interactive Lisp function.

It is bound to C-M-o k.

(hydra-C-M-o-move-splitter-up)

Create a hydra with a "C-M-o" body and the heads:

"h": hydra-move-splitter-left,
"j": hydra-move-splitter-down,
"k": hydra-move-splitter-up,
"l": hydra-move-splitter-right.

Call the head: hydra-move-splitter-up.

Outro

I hope that you enjoy the new library and let me know when you invent some novel and efficient Hydras. Happy hacking!

lispy 0.21.0 is out

2015-01-19T00:00:00+01:00

The last release was more than a month ago, and there have been more than 130 commits to master since then. Somehow, I've been dragging my feet with this release: the (3 pages of) release notes were in the draft stage for 10 days now, while I kept committing on top of them.

Introduction

This project is my vision of efficient LISP editing. According to Github, I started it more than a year ago, although the initial commit already contained around 1000 lines of code. After a year, it's more than 100 interactive commands in 5000 lines of code and 1000 lines of tests.

Initially, I started the project because, while I wanted to learn Paredit to get more efficient, I did not want to learn Paredit's cumbersome bindings. Having established a skeleton that allows to call Paredit-like commands with plain letters, over time, I've tacked on anything LISP-related here. In this way, it's very similar to org-mode, which starts with an outline and TODO skeleton, and then adds everything else in the world on top of that. Heck, I actually tacked on org-mode's outline features on top of lispy: when at an outline, i is equivalent to org-mode's TAB, and I is equivalent to S-tab.

Among the other packages with which lispy integrates/cooperates/coexists are: edebug, ediff, eldoc, ert, outline, semantic, semantic/db, ace-jump-mode, iedit, delsel, helm, multiple-cursors, fancy-narrow, projectile, god-mode, auto-complete, company.

Main idea behind `lispy`

The idea is to have plain letters, like h or r, call commands instead of self-inserting, but only if the point position is such that you wouldn't want to self-insert anyway. When this situation occurs, I like to say "the point is special"; this shortcut is all over the code and the docs.

This is a bit similar to vi's normal/insert states, but instead of "holding" the current state in your head, it's visible through just the point position. And instead of having just the Esc/i combination to toggle normal/insert state, you can do it with any command that moves point, e.g. C-f, or C-a, or even any custom command that you write. lispy does provide [, ], and C-3 key bindings for getting into special, but you are free to use any other binding or command that you want.

For instance, starting from this code and point position (which is already special):

(when (= arg 0)
  (setq arg 2000))

you can move to the when statement with h (lispy-right):

(when (= arg 0)
  (setq arg 2000))

or you can remove the when statement altogether with r (lispy-raise):

(setq arg 2000)

or you can:

evaluate (setq arg 2000) statement with e (lispy-eval); the result will be displayed in the echo area; works for multiple LISP dialects
evaluate and insert with E (lispy-eval-and-insert); the actual value 2000 will be inserted below the expression
evaluate and replace with xr (lispy-eval-and-replace); the expression will be replaced with 2000
copy the statement to the kill ring with n (lispy-new-copy)
delete the statement with C-d (lispy-delete)
insert a copy of the statement below with c (lispy-clone)
insert 3 copies of the statement below with 3c (digit-argument, lispy-clone)
move the statement on the previous line with DEL (lispy-delete-backward)
mark the statement with m (lispy-mark-list)
mark only arg with 2m (digit-argument, lispy-mark-list)
get help for setq with xh (lispy-describe)
get help for arg with 2mxh (digit-argument, lispy-mark-list, lispy-describe)
copy 2000 to kill ring with 3mn (digit-argument, lispy-mark-list, lispy-new-copy)
move the statement outside of when with oh (lispy-other, lispy-left)
swap (= arg 0) with (setq arg 2000) with w (lispy-move-up)
move it back with s (lispy-move-down)
put the whole when expression on one line with hO (lispy-left, lispy-oneline)
narrow the buffer to current sexp with N (lispy-narrow)
widen the buffer with W (lispy-widen)
a lot of other things, there are 52 plain letters, after all

Note that in the following code, the point is not special:

(when (= arg 0)
  (setq arg 2000))

so if you would type h, it would not call lispy-left, but would insert "h" instead, yielding whhen.

to get the point into special before (when, you can use either C-a or [ or C-M-a
to get the point into special after arg 0), you can use either C-e or ]
to get the point into special after 2000)), you can use C-3

Evolution of special

Initially, the special state was only for the point before an open paren or after a close paren, since you almost never-ever want to insert characters at those positions. Over time, other point states were added to special:

region is active (supersedes expand-region for LISP dialects)
the point is at the start of a comment
the point is at the start of an outline

Region selection is especially important, since it is super-useful for manipulating (move, copy, eval, get-help, goto-definition) symbols inside lists. Since these symbols aren't delimited with parens, the only way to get to them with special is though region selection.

Happily, region selection will fix the largest source of Paredit unbalanced paren errors: while using lispy region-manipulating commands, you can't copy an unbalanced expression, and thus you can't yank an unbalanced expression. You just have to use m and M-m instead of C-SPC; and h, j, k, l, i, >, and < instead of e.g. C-f and M-f.

Since there are only 26 lower-case letters and 26 upper-case letters, the state of the command bindings in lispy quickly turned into survival of the fittest:

the commands that were used the most got the priority bindings of lower case letters on the home row
the second tier got the other lower-case bindings
the third tier of commands were put on upper-case letters and on x + lower-case letters
the fourth tier of commands are not bound at all, and I'm considering to obsolete some of them, just to keep things simpler.

ADD: the Annoyance-Driven Development

The other part of evolving and refining the commands, consisted of noticing small annoyances for when some generic command wasn't working as intended, or it was working in a sub-optimal way in a certain situation. After this, I would fix the command and put a test on it, to make sure that the annoyance does not surface in the future.

Notes on LISP dialects

My priority is Elisp, since that's what I'm using to implement lispy, but the following dialects are also supported:

Clojure, via CIDER
Common Lisp, via SLIME
Scheme, via Geiser

To be supported, all a LISP dialect needs is just to use ( or { or [ as the opening delimiter; and ) or } or ] as the closing delimiter, no actual adaptations in the lispy code are necessary.

The only thing that needs to be implemented on a per-dialect basis is the language-specific eval:

e (lispy-eval)
E (lispy-eval-and-insert)
xr (lispy-eval-and-replace)
xj (lispy-debug-step-in)

Also, though the jump-to-definition functionality could be implemented via CEDET, environments like SLIME can do it much better, so F (lispy-follow) and M-. (lispy-goto-symbol) use the appropriate environment's facilities. Somehow, I still haven't managed to implement this for Geiser.

Drinking from the `lispy` fire hose

I'll get you started with the most basic and composable commands below. You can find the rest in the function reference or by just calling xv (lispy-view-test) on should statements of lispy-test.el:

In the screenshot above, I start with the code and point position on the top. Then, after typing miji, I should end up with the state below: the point and mark position have moved. In this particular situation, I could follow-up with e to see the value of auto-mode-alist. Here's how to decipher miji:

m - lispy-mark-list: marks current expression
i - lispy-tab (mnemonic for indent or inner): marks the car of current expression
j - lispy-down (vi shortcut to move down): moves the point and mark down by one sexp, selecting the quoted expression
i - lispy-tab: selects the car of the quoted expression, i.e. auto-mode-alist

As you see from the screenshot, I have show-paren-mode always on. It's even on in the tests visualization!

The most basic `lispy` commands: the arrows

h is left
j is down
k is up
l is right

The directions are literal only if you have your code properly indented, with newlines after each sexp. Otherwise, it may be the case that j moves literally right, instead of down; still, it's down figuratively.

arrows like digits

All of them take digit arguments, so that e.g. 5j is equivalent to jjjjj.

h and j maintain the guarantee of not exiting the current list, so you can use e.g. 99j to move to the last element, if your list length is smaller than 99.

arrows like regions

When the region is active, the arrows move the mark appropriately with the point. You can activate and deactivate the region by repeatedly pressing m.

You can also mark a symbol with M-m (lispy-mark-symbol). There's no need to be in special for this command to work. I call these type of bindings global, while the bindings that only work in special I call local.

arrows like outlines

When located at the outline, j will call outline-next-visible-heading, and k will call outline-previous-visible-heading. l will move to the first list of the outline, while h will jump between the top-level sexp and the containing outline.

switching to a different side of the expression

Arrows can't do this easily; this can instead be done with d (lispy-different). Works for lists and regions.

Moving the code instead of moving around the code

The most basic commands are:

w is lispy-move-up
s is lispy-move-down

These will "hold on" to the current expression while moving it in the appropriate direction. There's no need to worry to mess up with them, since they cancel each other out perfectly.

Note that, just like with the arrows, if you don't have an opening or closing delimiter to "grab", you can mark a symbol M-m to be in special and use w / s.

Modified arrows can move too

o will modify the arrow keys temporarily, just for one command, with a minor mode. You can think of it as making the arrows move the point and the sexp in the usual direction, instead of moving just the point.

ol: move current sexp outside of the parent list, forwards
oh: move current sexp outside of the parent list, backwards
oj: move current sexp inside the next list, making it the first element
ok: move current sexp inside the preceding list, making it the last element

Extending or shrinking the current list or region

> (lispy-slurp) grows the current list or region in the current direction by one sexp
< (lispy-barf) shrinks the current list or region in the current direction by one sexp

Similarly to j and k, these commands maintain the guarantee of not exiting the parent list, so you can slurp until the end of the list with e.g. 99>.

Outro

This project is very far from being final, I'm expecting to reach 0.99.0 before getting to 1.0.0. The reason is that the package aims to build intuition to the point of automation. For each small step in that direction, every small bug is two steps back, since it breaks the process of building intuition. So every possible situation needs to be tested and bugs fixed until the package is finally ironed out.

While I do appreciate the stars, actually trying to do things with lispy and raising issues would help me a great deal more. For instance, if you raise an issue like

How can I generate a function call right after the function definition?

I would say to just use 2mcol(:

mark the function name with 2m
clone region with c
move region outside the function body with ol
wrap the region with parens while deactivating it with (

And this would be a sort of FAQ question / recipe already done there.

Or you could raise an issue like:

Why doesn't F work for Racket?

I would say it's because I haven't implemented it yet, since it was tricky. But I'll get to it, now that I see that there's some interest in lispy from Racket users.

Sprucing up org-download

2015-01-18T00:00:00+01:00

My interest in org-download was renewed today with this thread on org-mode's mailing list.

org-download allows you to drag-and-drop an image from e.g. Firefox or your own file system to an org-mode buffer. When I originally wrote it, I was taking a Chemistry course on edX, which included homework and exams with a lot of images. Doing the homework in a literate style with org-mode, I wanted the problems to be completely self-contained, and for that I needed to save all the images from the website, preferably quickly, to an org-mode buffer. With a few hacks and some advice and contributions from more experienced hackers, org-download came to be.

Today's commits

The main contribution from today's commits was adding the code that un-aliases images that point to HTML. I see a lot of these from the people that I'm following on my Twitter, @_abo_abo. Here's the code:

(defcustom org-download-img-regex-list
  '("<img +src=\"" "<img +\\(class=\"[^\"]+\"\\)? *src=\"")
  "This regex is used to unalias links that look like images.
The html to which the links points will be searched for these
regexes, one by one, until one succeeds.  The found image address
will be used."
  :group 'org-download)

and in (org-download-image link):

(unless (image-type-from-file-name link)
    (with-current-buffer
        (url-retrieve-synchronously link t)
      (let ((regexes org-download-img-regex-list)
            lnk)
        (while (and (not lnk) regexes)
          (goto-char (point-min))
          (when (re-search-forward (pop regexes) nil t)
            (backward-char)
            (setq lnk (read (current-buffer)))))
        (if lnk
            (setq link lnk)
          (error "link %s does not point to an image" link)))))

Here, image-type-from-file-name is a built-in from image.el that decides if link looks like an image file or not.

As you can see, since I intend to use link right after to be transformed right now, I'm using url-retrieve-synchronously, instead of the asynchronous url-retrieve. The other one is used by default to download the actual image.

Note the use of the while / pop combination for traversing a list. I've seen it used in some places in the Emacs core, and I think it's pretty neat.

Arranging the regular expressions into a list is necessary to give priority to some regexes. For instance, the first element of org-download-img-regex-list should match e.g. an actual referred image on Twitter, while the second element will match at least a profile picture in the case when there is no referred image.

Visual demo

I think that I might have over-engineered the custom options of org-download a bit. Just to keep you motivated enough to figure them out, here's a link to a Youtube demo of the fast clickety-clicking (the mouse usage), that comes after some clackety-clacking (the customization).

Setting up Ediff

2015-01-17T00:00:00+01:00

Once you make Ediff bearable, it becomes wonderful. At least this was my experience. It's a very good tool, but some of the defaults look very poor to me.

Customizing the `customize`

First of all, I'll list a macro that I've started to use for setting custom variables:

(defmacro csetq (variable value)
  `(funcall (or (get ',variable 'custom-set)
                'set-default)
            ',variable ,value))

This macro I've put together myself after searching though the code base and not finding something similar; custom-set-variables comes close to what I want, or maybe custom-initialize-changed. Basically all I want is a setq that is aware of the custom-set property of a variable. If you know such a macro, please let me know.

Changing some Ediff options

Now, that I've explained the custom setter (by the way, using custom-set-variables is absolutely equivalent to csetq), here are my changes:

Don't use the weird setup with the control panel in a separate frame. I can manage windows in Emacs much better than my desktop (Unity or Gnome Shell) can manage the Emacs frames.
```
(csetq ediff-window-setup-function 'ediff-setup-windows-plain)
```
Split the windows horizontally instead of vertically. This way, it's much easier to follow the changes.
```
(csetq ediff-split-window-function 'split-window-horizontally)
```
Ignore white space. I don't write a lot of Python, so I don't care about the white space in the diffs. At the same time, I re-format any LISP code that I edit to my liking, and I want to see only the important changes in the diff, and not the whitespace nonsense.
```
(csetq ediff-diff-options "-w")
```

Changing some Ediff key bindings

This is just the standard stuff that I like to do for each mode that does not self-insert: assign j to move down, and k to move up.

(defun ora-ediff-hook ()
  (ediff-setup-keymap)
  (define-key ediff-mode-map "j" 'ediff-next-difference)
  (define-key ediff-mode-map "k" 'ediff-previous-difference))

(add-hook 'ediff-mode-hook 'ora-ediff-hook)

Restoring the windows after Ediff quits

When you quit an Ediff session with q, it just leaves the two diff windows around, instead of restoring the window configuration from when Ediff was started. Here's the (slightly hacky) code to restore the old window configuration:

(winner-mode)
(add-hook 'ediff-after-quit-hook-internal 'winner-undo)

List of ways that I use to invoke Ediff

from `magit`

In 80% of the cases, I call Ediff with e (magit-ediff) from magit-status-mode. This gives me a better overview of the changes, especially when I want to revert stuff with either a (ediff-copy-A-to-B) or b (ediff-copy-B-to-A). Probably with a, since magit seems to consistently put the @{index} file into the A diff window, and the current file into the B window.

So if I'm looking at a diff (to which I navigated with j/k), I can revert it with a. At this point, the diff region in the current file will become equal to that of the index file. But it will not be saved yet. If I want to save the current file in the B window, I can do it with wb (ediff-save-buffer). After a revert, it's also useful to call !(ediff-update-diffs), which will remove the zero-length diffs and update the diff-count in the mode-line.

other methods

ediff-buffers will diff two (different) buffers. If you happen to have only two windows open with the appropriate buffers, you get them as defaults and can choose them quickly with RET RET.
ediff-files is similar, but works on files instead. I like to just mark the appropriate files in dired with m, then they also get auto-selected by ediff-files.
ediff-current-file is useful to see the unsaved changes to the current file. I rarely use it, since I have a compulsion to save every file every chance I get. There is little hope to recover from this addiction, unless someone implements an analogue of guru-mode that annoys you when you try to save a file. Actually, it's not a bad idea - C-x C-s:

Oleh, you have saved this file 40 times in the last hour; the last save was 0 minutes 34 seconds ago; since then, you've changed 27 bytes of information. Are you sure you want to save [y/N]?

Save before compile

2015-01-16T00:00:00+01:00

Here's a very simplistic function that I was using for a while:

(defun save-and-compile ()
  (interactive)
  (save-buffer)
  (compile "make -j4")
  (pop-to-buffer next-error-last-buffer))

It will save the current buffer, run compile and switch to compilation buffer.

Compilation customization

Turns out that there's no need to save, since I get away with this:

(setq compilation-ask-about-save nil)

The documentation says:

Non-nil means M-x compile asks which buffers to save before compiling. Otherwise, it saves all modified buffers without asking.

Select compilation target

A year ago, I wrote a package that looks for a Makefile in the current directory, parses the available targets and allows you to choose one with helm. It's called helm-make. It's almost the same as M-x compile (which also has completion for targets), and it wraps around compile, but I just find it to be more convenient.

This package is as simple as it sounds, the only customization that you can do is to set helm-make-do-save to save all open buffers visiting the Makefile's directory. It also provides, in addition to the plain helm-make command, a helm-make-projectile command, which is almost the same, except the Makefile should come not from the current directory but from projectile-project-root.

I've had these bindings for a very long time, just making sure that you're aware of these commands:

(global-set-key [f6] 'next-error)
(global-set-key [C-f6] 'previous-error)

These bindings work for M-x occur and rgrep as well.

C++ - a dot inserts last var plus dot

2015-01-15T00:00:00+01:00

It is very much in the spirit of C++ to pull an object into existence with e.g. a constructor definition and then poke and prod it with various method calls. Most of the time, the dot will have the object name on the left. So why not automatically insert the object name each time I press the dot? Below, I'll show a code that does exactly that.

The dot command

(defun c++-smart-dot ()
  "Insert a dot or an object name plus dot when appropriate."
  (interactive)
  (let (var-name)
    (if (and (looking-back "^[ \t]*")
             (setq var-name (c++-get-recent-var)))
        (insert var-name ".")
      (insert "."))))

This one is pretty simple: if we are at the beginning of the line, optionally with some spaces or (ugh) tabs before the point, then try to insert the object name along with a dot.

Here's how to bind it:

(eval-after-load "cc-mode"
  `(define-key c++-mode-map "." 'c++-smart-dot))

How to get the recent variable

This code doesn't aim to be thorough, it's just a hack that works reasonably well.

(defconst c++-var-regex "[A-Za-z][A-Za-z0-9_]*"
  "The regex for C++ variable name.")

(defun c++-get-recent-var ()
  "Return the closest thing that looks like an object.
The search is performed backwards through code."
  (save-excursion
    (when (or
           ;; variable dot chain
           (looking-back
            (format " \\(%s\\)\\.%s.*\n[\t ]*"
                    c++-var-regex
                    c++-var-regex))
           ;; variable constructor init
           (looking-back
            (format "[\t ]+\\(%s\\)\\(?:([^)]*)\\)?;[\t\n ]*"
                    c++-var-regex))
           ;; variable dot, first on line
           (re-search-backward
            (format "^[ \t]*\\(%s\\)\\." c++-var-regex) nil t))
      (match-string-no-properties 1))))

If you're a stickler for performance and you don't want to call format a bunch of times, you can amend the code like this:

(defalias 'c++-get-recent-var
    (byte-compile
     `(lambda ()
        (save-excursion
          (when
              (or
               ;; variable dot chain
               (looking-back
                ,(format
                  " \\(%s\\)\\.%s.*\n[\t ]*"
                  c++-var-regex
                  c++-var-regex))
               ;; variable constructor init
               (looking-back
                ,(format
                  "[\t ]+\\(%s\\)\\(?:([^)]*)\\)?;[\t\n ]*"
                  c++-var-regex))
               ;; variable dot, first on line
               (re-search-backward
                ,(format "^[ \t]*\\(%s\\)\\." c++-var-regex) nil t))
            (match-string-no-properties 1)))))
  "Return the closest thing that looks like an object.
The search is performed backwards through code.")

The thing above looks slightly ugly. I'm open to suggestions to make it look nicer.

The sample application

For the happy people that have never seen C++:

DataOut<dim> data_out;
data_out.attach_dof_handler(dof_handler);
data_out.add_data_vector(solution, "u");
data_out.build_patches();

Here, after defining an object data_out, I insert it subsequently with just ..

Zoom in / out with style

2015-01-14T00:00:00+01:00

I don't usually zoom a lot, typically I do it to size up other people's functions. Then, I zoom-out a couple times in a row until the function fits on the screen. Sometimes, I overshoot the zoom-out, and I have to zoom-in instead. I have text-scale-increase bound to <f2> g and text-scale-decrease bound to <f2> l.

Below, I'll demonstrate how to call those two commands interchangeably with e.g. <f2> g g g l g g l, i.e. omitting the <f2> prefix.

Define repeatable command

(defun def-rep-command (alist)
  "Return a lambda that calls the first function of ALIST.
It sets the transient map to all functions of ALIST."
  (lexical-let ((keymap (make-sparse-keymap))
                (func (cdar alist)))
    (mapc (lambda (x)
            (define-key keymap (car x) (cdr x)))
          alist)
    (lambda (arg)
      (interactive "p")
      (funcall func arg)
      (set-transient-map keymap t))))

This is a pretty simple function that takes an alist of keys and commands, and returns a lambda that calls the first command and sets the transient map to call the first and other commands. The way the transient map works, it takes priority over almost all maps, but disappears as soon as you press something that doesn't belong to it.

The zoom-in / zoom-out use case

(global-set-key (kbd "<f2> g")
                (def-rep-command
                    '(("g" . text-scale-increase)
                      ("l" . text-scale-decrease))))
(global-set-key (kbd "<f2> l")
                (def-rep-command
                    '(("l" . text-scale-decrease)
                      ("g" . text-scale-increase))))

And this is it. A nice thing about this setup is that I don't have to think about the zoom state and quitting it: I'll quit it automatically as soon as I press anything other than l or g. Moreover, the command that exited the zoom state will be executed as usual.

Even more dired options

2015-01-13T00:00:00+01:00

I've been posting a lot about dired lately, and with good cause. A lot of people say that org-mode is the killer app of Emacs, but dired should be in that group as well, especially if you count tramp as part of dired. Below, I'll list a few dired options in my config that deviate from the defaults.

`dired-listing-switches`

This is the essence of what dired presents and how it presents it. A great thing about it is that these are just the ls switches, so you can look them up with info ls.

(setq dired-listing-switches "-laGh1v --group-directories-first")

l: Is the only mandatory one.
a: Means to list invisible files.
G: Don't show group information. These days, when there are more laptops than people, the group info is rarely useful.
h: Human readable sizes, such as M for mebibytes.
1v: Affects the sorting of digits, hopefully in a positive way.
--group-directories-first: self-explanatory, I like to have the directories on the top, separate from the files.

On recursion

(setq dired-recursive-copies 'always)
(setq dired-recursive-deletes 'always)

These settings make dired skip the confirmation when you copy or delete a directory that contains other directories. What's the worse that could happen, right?

-  rm -rf /usr /lib/nvidia-current/xorg/xorg
+  rm -rf /usr/lib/nvidia-current/xorg/xorg

File sizes in dired

2015-01-12T00:00:00+01:00

Today, I'll continue with the trend of posting a small piece of my config when I don't have the time to post something more substantial.

Some code

This one looks nice, although it only works on systems with /usr/bin/du, which actually comprise 100% of the systems that I use:

(defun dired-get-size ()
  (interactive)
  (let ((files (dired-get-marked-files)))
    (with-temp-buffer
      (apply 'call-process "/usr/bin/du" nil t nil "-sch" files)
      (message
       "Size of all marked files: %s"
       (progn
         (re-search-backward "\\(^[ 0-9.,]+[A-Za-z]+\\).*total$")
         (match-string 1))))))

On doing a search, turns out that I got this code from the wiki at some point. I can confirm that, unlike some of the other code on the wiki, this one still works as advertised: you can use it on a directory or on a series of marked files and directories.

Standard `dired` marking

In dired, you can:

mark an item with m
unmark an item with DEL
inverse selection with t
unmark everything with U

Compared to this, the selection with the mouse and the control and shift keys that many file browsers use looks like kindergarten.

This new action, getting the size of marked things, I've bound to z:

(define-key dired-mode-map (kbd "z") 'dired-get-size)

Making Elisp regex look nicer

2015-01-11T00:00:00+01:00

This is just a small improvement to make e.g. \\( show up in regular expressions without the escape chars, but instead fontified with font-lock-keyword-face. It doesn't affect the underlying code at all, just makes it look nicer. For the \\| I chose ∨ - the logical or character.

The code

(defun fontify-glyph (item glyph)
  `((,item
     (0 font-lock-keyword-face t)
     (0 (prog1
            (compose-region (match-beginning 0)
                            (match-end 0)
                            ,glyph) nil)))))

(font-lock-add-keywords 'emacs-lisp-mode
                        (fontify-glyph "\\\\\\\\|" "∨"))
(font-lock-add-keywords 'emacs-lisp-mode
                        (fontify-glyph "\\\\\\\\(" "("))
(font-lock-add-keywords 'emacs-lisp-mode
                        (fontify-glyph "\\\\\\\\)" ")"))

How it looks like

At first, I wanted to just inline a picture, but then I thought that htmlize-buffer would be able to handle it. It didn't, so I just edited a small snippet by hand:

(or (string-match "^([^\n%|]*?)|(([^\n]*)?$" str)
    (string-match "^([^\n%|]*?)(%[^\n]*)?$" str))

It's really satisfying to see those escape chars vanish as I type in a capture group in the regex, especially with the help of lispy-mode. Here are some relevant tests for the regex support:

(should (string= (lispy-with "\"a regex \\\\|\"" "(")
                 "\"a regex \\\\(|\\\\)\""))
(should (string= (lispy-with "\"\\\\(|foo\\\\)\"" "\C-?")
                 "\"|foo\""))
(should (string= (lispy-with "\"\\\\(foo\\\\)|\"" "\C-?")
                 "\"foo|\""))
(should (string= (lispy-with "\"|\\\\(foo\\\\)\"" "\C-d")
                 "\"|foo\""))
(should (string= (lispy-with "\"\\\\(foo|\\\\)\"" "\C-d")
                 "\"foo|\""))

dired and ansi-term: BFF

2015-01-10T00:00:00+01:00

In the comments to my previous post on ansi-term, I discovered sane-term - a package that cycles though your terminals in Emacs, as well as implements some of the tips that I gave. While it's nice and all, and you should check it out if you're looking for something like that, it's not really for me. I will describe the system that I'm currently using below.

What is the best list length for cycling?

In my opinion, it's one or two. If it's one, you're not really cycling, if it's two, it's fine. Anything more than that causes stress, since you have to check each time if the outcome of the cycle ended up being the one that you wanted.

That's why I usually have only one *ansi-term* active in my Emacs session at all times. Here's how it looks like:

(defun terminal ()
  "Switch to terminal. Launch if nonexistent."
  (interactive)
  (if (get-buffer "*ansi-term*")
      (switch-to-buffer "*ansi-term*")
    (ansi-term "/bin/bash"))
  (get-buffer-process "*ansi-term*"))

(defalias 'tt 'terminal)

At one point, I had terminal bound to C-t, until I found a command even better suited for that binding, which was smex. The actual terminal command isn't bound right now, I just launch it from smex on very rare occasions.

How I launch terminal 95% of the time

From dired of course. The shell's natural way of switching the directory with cd is extremely inefficient compared to dired. So any time I want to have a shell in a specific directory, I first navigate there with dired, sometimes combined with ido-find-file. Then I get my current *ansi-term* and tell it to switch to the current dired buffer's directory with ` binding:

(define-key dired-mode-map (kbd "`") 'dired-open-term)

(defun dired-open-term ()
  "Open an `ansi-term' that corresponds to current directory."
  (interactive)
  (let ((current-dir (dired-current-directory)))
    (term-send-string
     (terminal)
     (if (file-remote-p current-dir)
         (let ((v (tramp-dissect-file-name current-dir t)))
           (format "ssh %s@%s\n"
                   (aref v 1) (aref v 2)))
       (format "cd '%s'\n" current-dir)))))

I also have a similar eshell setup, although I have yet to comprehend why eshell is great and am using *ansi-term* most of the time instead.

(define-key dired-mode-map (kbd "'")
  (lambda ()
    (interactive)
    (eshell-cmd
     (format "cd %s"
             (expand-file-name
              default-directory)))))

How I launch `dired` 100% of the time

With dired-jump, of course. This command will examine your current buffer's default-directory and open a dired buffer there. All you need is:

(require 'dired-x)

The dired-jump command will be bound automatically to C-x C-j. I have it also bound to C-:, since that's more convenient to press with my keyboard layout.

It's also better in the common situation when I want to jump to a dired buffer from *ansi-term*. In that situation, C-x C-j will not work by default, and will call term-line-mode instead. But it will work once you are in term-line-mode. You can go back to the default term-char-mode with C-x C-k. To avoid this nonsense, just bind dired-jump to some binding that's convenient for you and works from *ansi-term*.

What I do when I need more than one terminal

Then I just name one: since the default one is supposed to be named *ansi-term*, if I create one named e.g. *jekyll*, it will be ignored by dired-open-term. This is exactly what I want, since I just create named terminals for long running processes like jekyll serve. And I can switch to the named terminals with just ido-switch-buffer. Here is the very simple code:

(defun named-term (name)
  (interactive "sName: ")
  (ansi-term "/bin/bash" name))

tilde in ido-find-file

2015-01-09T00:00:00+01:00

On seeing this Emacs Stack Exchange question, it occurred to me that if some config code is old for me, it's not old for the new Emacs users. So I'll share one of the old ido-find-file hacks that I've been using for ages.

This song is an oldie ...but, uh ... pause Well, it's an oldie where I come from.

-- Marty

The code

This is the original code that I was using:

(defun oleh-ido-setup-hook ()
  (define-key ido-file-dir-completion-map "~"
    (lambda ()
      (interactive)
      (ido-set-current-directory "~/")
      (setq ido-exit 'refresh)
      (exit-minibuffer))))

(add-hook 'ido-setup-hook 'oleh-ido-setup-hook)

The generalization

It wouldn't be a LISP if I couldn't generalize the code:

(defun ido-find-file-jump (dir)
  "Return a command that sends DIR to `ido-find-file'."
  `(lambda ()
     (interactive)
     (ido-set-current-directory ,dir)
     (setq ido-exit 'refresh)
     (exit-minibuffer)))

And here's how to leverage this generalization:

(defun oleh-ido-setup-hook ()
  (define-key ido-file-dir-completion-map "~"
    (ido-find-file-jump "~/"))
  (define-key ido-file-dir-completion-map "!"
    (ido-find-file-jump "~/Dropbox/source/site-lisp/"))
  (define-key ido-file-dir-completion-map "@"
    (ido-find-file-jump "~/git/lispy/")))

Note that this is pretty ugly, implementation-wise, since ido-find-file-jump would be called three times each time you do an ido related command, like ido-switch-buffer etc. I would have preferred to do it like this instead:

(eval-after-load "ido"
  `(progn
     (define-key ido-file-dir-completion-map "~"
       (ido-find-file-jump "~/"))
     (define-key ido-file-dir-completion-map "!"
       (ido-find-file-jump "~/Dropbox/source/site-lisp/"))
     (define-key ido-file-dir-completion-map "@"
       (ido-find-file-jump "~/git/lispy/"))))

But, for some strange reason, ido keeps overriding ido-file-dir-completion-map and I actually have to re-set my bindings in ido-setup-hook.

The further generalization

Here is the final iteration of the code:

(defvar oleh-ido-shortcuts
  '(("~/" "~")
    ("~/Dropbox/source/site-lisp/" "!")
    ("~/git/lispy/" "@")))

(mapc (lambda (x)
        (setcar x (ido-find-file-jump (car x))))
      oleh-ido-shortcuts)

(defun oleh-ido-setup-hook ()
  (mapc
   (lambda (x)
     (define-key ido-file-dir-completion-map (cadr x) (car x)))
   oleh-ido-shortcuts))

(add-hook 'ido-setup-hook 'oleh-ido-setup-hook)

The customize tricks

"Custom setters?
In my Elisp?"

It's more likely than you think.

Note that the mapc statement needs to be evaluated if I dynamically modify oleh-ido-shortcuts. This isn't a problem for me, but if I wanted to package a code like this, I would define oleh-ido-shortcuts like this:

(defcustom oleh-ido-shortcuts
  '(("~/" "~")
   ("~/Dropbox/source/site-lisp/" "!")
    ("~/git/lispy/" "@"))
  "A list of directory-shortcut pairs for `ido-find-file'."
  :set (lambda (symbol value)
         (set-default
          symbol
          (mapcar
           (lambda (x)
             (if (stringp (car x))
                 (cons (ido-find-file-jump (car x))
                       (cdr x))
               x))
           value))))

Now, this should work:

(csetq oleh-ido-shortcuts
       (progn
         (setcar (rassoc '("@") oleh-ido-shortcuts)
                 "~/git/worf")
         oleh-ido-shortcuts))

(csetq oleh-ido-shortcuts
       (cons '("~/git/" "^")
             oleh-ido-shortcuts))

Here, the appropriate lambda is auto-generated by using the :set property of oleh-ido-shortcuts. And csetq is just a customize-aware version of setq:

(defmacro csetq (variable value)
  `(funcall (or (get ',variable 'custom-set) 'set-default)
            ',variable ,value))

My org-protocol setup, part 2.

2015-01-08T00:00:00+01:00

This continues the code from the part 1.

`org-handle-link-youtube`

I tried to make the first call to youtube-dl asynchronous, but it wasn't working out. So for the current code, there's still about a 2 second delay before the capture buffer appears.

(require 'async)
(defun org-handle-link-youtube (link)
  (lexical-let*
      ((file-name (org-trim
                   (shell-command-to-string
                    (concat
                     "youtube-dl \""
                     link
                     "\""
                     " -o \"%(title)s.%(ext)s\" --get-filename"))))
       (dir "~/Downloads/Videos")
       (full-name
        (expand-file-name file-name dir)))
    (add-hook 'org-link-hook
              (lambda ()
                (concat
                 (org-make-link-string dir dir)
                 "\n"
                 (org-make-link-string full-name file-name))))
    (async-shell-command
     (format "youtube-dl \"%s\" -o \"%s\"" link full-name))
    (find-file (org-expand "ent.org"))
    (goto-char (point-min))
    (re-search-forward "^\\*+ +Videos" nil t)))

Some notes for people who want to learn more Elisp:

lexical-let* is needed to have dir and full-name visible in the lambda.
org-make-link-string is a nice utility command that escapes all sorts of characters that org-mode doesn't like, e.g. brackets etc.

You can see my full org-capture and org-protocol setup here.

My org-protocol setup, part 1.

2015-01-07T00:00:00+01:00

I'm quite busy with a project today, so I can't compose many words. However, pasting and explaining some code is fine. The basic idea is creating TODO tasks in certain org-mode files by clicking a link in Firefox, thanks to org-mode capture.

`org-protocol` starter

(require 'org-capture)
(require 'org-protocol)
(setq org-protocol-default-template-key "l")
(push '("l" "Link" entry (function org-handle-link)
        "* TODO %(org-wash-link)\nAdded: %U\n%(org-link-hooks)\n%?")
        org-capture-templates)

org-wash-link should clear up some redundancies in the TODO
org-handle-link should open the appropriate file and heading.
org-link-hooks should insert some extra information

`org-wash-link`

Basically, when I capture a question on Stack Overflow, I don't want to see - Stack Overflow - as part of the TODO string, since the TODO itself is stored in wiki/stack.org/* Questions.

(defun org-wash-link ()
  (let ((link (caar org-stored-links))
        (title (cadar org-stored-links)))
    (setq title (replace-regexp-in-string
                 " - Stack Overflow" "" title))
    (org-make-link-string link title)))

`org-link-hooks`

This is just a hack for passing information around that functions from org-handle-link can use.

(defvar org-link-hook nil)

(defun org-link-hooks ()
  (prog1
      (mapconcat #'funcall
                 org-link-hook
                 "\n")
    (setq org-link-hook)))

`org-handle-link`

This is the heart of the setup.

(defun org-handle-link ()
  (let ((link (caar org-stored-links))
        file)
    (cond ((string-match "^https://www.youtube.com/" link)
           (org-handle-link-youtube link))
          ((string-match (regexp-quote
                          "http://stackoverflow.com/") link)
           (find-file (org-expand "wiki/stack.org"))
           (goto-char (point-min))
           (re-search-forward "^\\*+ +Questions" nil t))
          (t
           (find-file (org-expand "ent.org"))
           (goto-char (point-min))
           (re-search-forward "^\\*+ +Articles" nil t)))))

Youtube links will be handled with org-handle-link-youtube
Stack Overflow links will be stored in wiki/stack.org/* Questions
all other links will be stored in ent.org/* Articles

I'll write down org-handle-link-youtube in a later post, since I would still like to sort out a few kinks with it. The main issue is that I'm sending two requests to Youtube: one to download the video, which is fine, since async handles it; and other to get the title of the video and put it in the heading. And this other request causes a perceptible delay when capturing.

Rushing headlong

2015-01-06T00:00:00+01:00

And you're rushing headlong out of control...

-- Brian May

I've finally wrapped a piece of config that I was using for a while in a package called headlong.

What does it do?

It provides a macro called headlong-with that modifies minibuffer completion for the forms within it, making it faster in some situations. For instance:

(headlong-with
 (completing-read "Jump to bookmark: "
                  bookmark-alist nil t))

or:

(headlong-with (read-extended-command))

But more importantly, it provides two commands that can use it efficiently: headlong-bookmark-jump and headlong-bookmark-jump-other. The second one is basically the same as the first one, except it opens the bookmark with pop-to-buffer, i.e. in other window.

How does this completion work?

It's nothing fancy, you will just exit the minibuffer automatically as soon as there is only one completion candidate left. So it saves you one keystroke, namely RET. How much is one keystroke worth? It depends.

If you arrange your bookmarks in a way that I do, with each one starting with a different letter, it saves you 33% of the total keystrokes. For example, suppose I have:

(global-set-key (kbd "M-p") 'bookmark-jump)
(global-set-key (kbd "M-o") 'headlong-bookmark-jump)

Then I can jump to my bookmarked directory named "s: sources" with two methods:

M-psRET
M-os

The second method looks like it's 33% shorter, but it feels like it's even more, since pressing RET is harder than it should be on most keyboards.

Why is this cool?

This is cool because you can implement your bookmarks as efficiently as you would with just wrapping stuff with a lambda and using global-set-key, except that you can view and edit the bindings with bookmark-bmenu-list, and quickly the update bookmark positions with bookmark-set.

Here's what I get when I call M-x bookmark-bmenu-list:

In the list above:

black bookmarks are files
blue bookmarks are directories
pink bookmarks are functions (you need bookmark+ for them)

The package should be available in MELPA soon.

Yet another youtube-dl interface for Emacs

2015-01-05T00:00:00+01:00

If you haven't been living under a rock, you already know what Youtube is. It's a repository with videos of varying degree of usefulness with a terrible media player tacked on. Instead, I like to watch my videos in VLC, which comes closest to providing an Emacs-like experience among video players.

Useful VLC shortcuts

Here is a list of shortcuts that really make me stick with VLC:

f - toggle full-screen
b - toggle audio track
n - toggle subtitle track
] - speed up play by 0.1
[ - slow down play by 0.1
M-right - forward by 15 seconds
M-left - backward by 15 seconds
C-right - forward by 60 seconds
C-left - backward by 60 seconds
M-1 - quarter of video size
M-2 - half of video size
M-3 - full video size
M-4 - double video size
C-h - toggle mouse buttons

So if you're not watching instructional videos at 1.6 speed, or skipping the Simpsons intro sequence with M-right, you're missing out.

From Youtube to VLC

youtube-dl is an excellent command-line tool for saving the videos from Youtube. It downloads the highest resolution at a usually higher speed than Youtube's player buffers. I've discovered it when I had to download a bunch of lecture videos from edX. You can install it with:

sudo pip install youtube-dl

One Emacs script to rule them all

I quickly tired of opening a shell, setting the directory, entering the command, and pasting the link. So I wrote some Elisp code that does it for me. It's nothing too sophisticated, but I've been using this version for a couple months:

(defun youtube-dl ()
  (interactive)
  (let* ((str (current-kill 0))
         (default-directory "~/Downloads")
         (proc (get-buffer-process (ansi-term "/bin/bash"))))
    (term-send-string
     proc
     (concat "cd ~/Downloads && youtube-dl " str "\n"))))

How it works:

Copy the link in Firefox
M-x youtube-dl.

That's it. A new *ansi-term* will open with the task of downloading the video from the link in the clipboard to ~/Downloads. I don't have to wait for the download to finish and can immediately open the video from dired. See the previous post for the description of dired process-starting setup. I can stack up multiple downloads at once if I wish in different *ansi-term*s.

This is my script. There are many like it, but this one is mine.

I did an internet search before writing this post. Apparently many others had the same idea of integrating youtube-dl into Emacs. You can use mine or any other code to generate a setup that works for you. For instance, for a while, instead of copy-pasting the URL and calling youtube-dl I used to just click the org-mode capture button in Firefox, and it would automatically create a TODO item, download the video, and put the link to the downloaded video in the TODO.

I've dropped this workflow when the yank bug surfaced. I don't yet have enough experience of working with Emacs's C code to fix it. Although, according to this excellent rant, fixing the bug is only half of the problem: getting it merged is hard. I'll see how it goes with my latest tiny patch. So far it has been ignored, but it is only two days old as of now.

Start a process from dired

2015-01-04T00:00:00+01:00

Here are the standard dired functions for starting processes:

! calls dired-do-shell-command
& calls dired-do-async-shell-command

While the second one is usually better than the first one, having the benefit of not locking up Emacs, it's still not convenient enough for me. The reason is pretty simple: I want to keep the processes that I started even when I close Emacs (like opened PDFs or videos). This is a non-issue for people with months-long emacs-uptime, but for me an Emacs session lasts on the order of hours, since I mess about with Elisp a lot. Below, I'll share some of my dired process-related customizations.

Ignore running processes when closing Emacs

Usually there's nothing wrong with just killing a spawned process, like an ipython shell or something.

;; add `flet'
(require 'cl)

(defadvice save-buffers-kill-emacs
  (around no-query-kill-emacs activate)
  "Prevent \"Active processes exist\" query on exit."
  (flet ((process-list ())) ad-do-it))

Guess programs by file extension

With this setup, usually there's no need to manually type in the command name.

(require 'dired-x)

(setq dired-guess-shell-alist-user
      '(("\\.pdf\\'" "evince" "okular")
        ("\\.\\(?:djvu\\|eps\\)\\'" "evince")
        ("\\.\\(?:jpg\\|jpeg\\|png\\|gif\\|xpm\\)\\'" "eog")
        ("\\.\\(?:xcf\\)\\'" "gimp")
        ("\\.csv\\'" "libreoffice")
        ("\\.tex\\'" "pdflatex" "latex")
        ("\\.\\(?:mp4\\|mkv\\|avi\\|flv\\|ogv\\)\\(?:\\.part\\)?\\'"
         "vlc")
        ("\\.\\(?:mp3\\|flac\\)\\'" "rhythmbox")
        ("\\.html?\\'" "firefox")
        ("\\.cue?\\'" "audacious")))

Add nohup

According to info nohup:

`nohup' runs the given COMMAND with hangup signals ignored, so that the command can continue running in the background after you log out.

In my case, it means that the processes started by Emacs can continue running even when Emacs is closed.

(require 'dired-aux)

(defvar dired-filelist-cmd
  '(("vlc" "-L")))

(defun dired-start-process (cmd &optional file-list)
  (interactive
   (let ((files (dired-get-marked-files
                 t current-prefix-arg)))
     (list
      (dired-read-shell-command "& on %s: "
                                current-prefix-arg files)
      files)))
  (let (list-switch)
    (start-process
     cmd nil shell-file-name
     shell-command-switch
     (format
      "nohup 1>/dev/null 2>/dev/null %s \"%s\""
      (if (and (> (length file-list) 1)
               (setq list-switch
                     (cadr (assoc cmd dired-filelist-cmd))))
          (format "%s %s" cmd list-switch)
        cmd)
      (mapconcat #'expand-file-name file-list "\" \"")))))

The dired-filelist-cmd is necessary because vlc weirdly doesn't make a playlist when given a list of files.

Then I bind it to r - a nice shortcut not bound by default in dired:

(define-key dired-mode-map "r" 'dired-start-process)

Time flies

2015-01-03T00:00:00+01:00

This is the 15th post on this blog. Thankfully, no heart attacks after the 13th one or anything. So I'll commemorate it with a post on dealing with dates in calc.

How much time has passed since I started this blog?

Open calc with C-x **:
```
--- Emacs Calculator Mode ---
    .
```

Enter 20 Dec 2014 with '<12 20 14RET:

--- Emacs Calculator Mode ---
1:  <Sat Dec 20, 2014>
    .

Enter current time with tN:

--- Emacs Calculator Mode ---
2:  <Sat Dec 20, 2014>
1:  <11:56:27am Sat Jan 3, 2015>
    .

Subtract with -:

--- Emacs Calculator Mode ---
1:  -14.498044
    .

This means that, if I want to maintain my one-post-per-day streak, I still have half of a day to post this. Unfortunately, I have only an old version of the blog repository on this machine, and the current one is on a laptop at home. So I'll post this in the evening.

Did you know what 2015 looks like in binary?

In your current calc session,

Enter 2015 SPC:

--- Emacs Calculator Mode ---
2:  -14.498044
1:  2015
    .

Switch to binary with d2:

--- Emacs Calculator Mode ---
2:  -2#1110.011111110111111111001111110001
1:  2#11111011111
.

Wow, a palindrome. It's too spooky, switch back to decimal with d0:
```
--- Emacs Calculator Mode ---
2:  -14.498044
1:  2015
    .
```

If you're new to calc, you'll probably wonder why you can't enter negative numbers with -. It can be done with _, just like in J. Find out more in the info; the interactive tutorial is absolutely excellent.

Wrap a region with a LaTeX environment

2015-01-02T00:00:00+01:00

Prompted by this StackOverflow question, I wrote down a new package called latex-wrap. It's only a few hours old, but I like it a lot. I've grepped the sources of AUCTeX, and it doesn't seem to have this functionality.

Here's how it works

You start with an active region:

Homer
Marge
Bart
Lisa
Maggie

After calling M-x latex-wrap-region and selecting enumerate from the list of environments (others being itemize, center etc.), you get this:

\begin{enumerate}
\item Homer
\item Marge
\item Bart
\item Lisa
\item Maggie 
\end{enumerate}

Let's mark everything, M-x latex-wrap-region, and select center:

\begin{center}
  \begin{enumerate}
  \item Homer
  \item Marge
  \item Bart
  \item Lisa
  \item Maggie
  \end{enumerate} 
\end{center}

As you can see, I want to make sure that it's possible to conveniently continue by always placing the point on the end of the last line of the inserted environment.

How it works with no active region

If (looking-back "^ *") is true, the current line is used as if it was the region. Otherwise, an empty environment is inserted after the current line.

Using the code

If you like the idea, you can check out the code at github and test it out. If you know of another package that already does this, do let me know, otherwise I'll post the package on MELPA soon. And if you have some ideas, or want to add a few environments that I forgot to mention to the list, just post an issue, I don't bite.

Three ansi-term tips

2015-01-01T00:00:00+01:00

Tip #1

There's no reason not to have /bin/bash instead of /bin/sh as the default choice when you M-x term.

(setq explicit-shell-file-name "/bin/bash")

Tip #2

After you close the terminal, you get a useless buffer with no process. It's probably left there for you to have a history of what you did. I find it not useful, so here's a way to kill that buffer automatically:

(defun oleh-term-exec-hook ()
  (let* ((buff (current-buffer))
         (proc (get-buffer-process buff)))
    (set-process-sentinel
     proc
     `(lambda (process event)
        (if (string= event "finished\n")
            (kill-buffer ,buff))))))

(add-hook 'term-exec-hook 'oleh-term-exec-hook)

Tip #3

By default, C-y calls term's own yank, which is different from Emacs's yank. So, until recently, I was using S-<insert> to paste stuff into *term*. Here's a more ergonomic way:

(eval-after-load "term"
  '(define-key term-raw-map (kbd "C-c C-y") 'term-paste))

The keymap arms race

2014-12-31T00:00:00+01:00

Sometimes new Emacs packages have to fight for their place in the sun, as all the good bindings and huge keymap areas are already taken by the older packages. This post will cover some practical problems that you may encounter when your package needs to be aware of another active package.

`ace-window` vs. `helm`

helm is a wonderful package, it's my goto-package when I need completion. All of the following packages use it:

But helm is super-greedy: once you're in the helm-minibuffer, there's no way out except either a successful completion or a cancel. But exiting the minibuffer for a short while may be useful. For instance, you could copy some text and yank it in the helm-minibuffer. The default minibuffer functions, as well as ido easily allow it.

I started to investigate into this when I got issue #15: Does not work with helm in minibuffer for ace-window. I checked it, and indeed you could not ace-window out of a helm-minibuffer. In fact, it was not possible to exit with other-window either. This looked like good news, since I had an inkling that it used to work at some point. So I checked out a year-old version of helm and it did work.

`magit-bisect` to the rescue!

It's very simple:

Check out the master of helm
Call magit-bisect-start and mark HEAD as bad
magit will automatically check out a revision that is halfway between a bad state and the initial commit. Now I exit Emacs and try helm again to see if I can exit from the minibuffer. It's kind of lame to have to exit Emacs, but somehow I don't trust unload-feature to do the right thing. Anyway, if the thing works, move to helm's repository and call magit-bisect-good, otherwise call magit-bisect-bad.
Continue this process until termination. I needed 10 iterations in this case.

The culprit commit was this one:

     (let* ((source (helm-get-current-source))
            (kmap (and (listp source) ; Check if source is empty.
                       (assoc-default 'keymap source))))
-      (when kmap (setq overriding-local-map kmap)))))
+      (when kmap (set-transient-map kmap)))))

the priority of maps

In Emacs, set-transient-map has priority over overriding-local-map, which was exactly what ace-window was using. It's also funny that ace-window used to work with helm for a week, since it was published on Mar 26 and helm switched to set-transient-map on Apr 2. And I found out that it's not working only now.

Here's what helm is using currently:

(if (fboundp 'set-transient-map)
    (set-transient-map it)
  (set-temporary-overlay-map it))

So I've amended ace-window with similar code. The way set-transient-map works, the last call to it overrides the previous one, so I thought that it would work out since ace-window is always called after helm.

It didn't work out, because helm adds the code that calls set-transient-map to post-command-hook. In the end, this finally worked:

(remove-hook 'post-command-hook 'helm--maybe-update-keymap)

`lispy` vs. `SLIME` and `CIDER`

I thought that enabling lispy-mode for slime-repl-mode and cider-repl-mode might be a good idea. Extra navigation options are always good, and the ability to call raise is just so useful.

For instance, you start with:

; SLIME 2014-11-28
CL-USER> (expt (expt 2 10) 3)
1073741824
CL-USER>

With lispy-mode on you can:

M-p to get the previous input
f to move the cursor after (expt 2 10)
r to raise (expt 2 10)

Here's the final state:

; SLIME 2014-11-28
CL-USER> (expt (expt 2 10) 3)
1073741824
CL-USER> (expt 2 10)

But the problem was that SLIME has slime-repl-map-mode minor mode on that competes for lispy's shortcuts, and CIDER has something similar as well.

When two minor modes bind the same keys, which one wins?

The answer is the first one on minor-mode-map-alist. This function I've found on the wiki:

(defun lispy-raise-minor-mode (mode)
  "Make MODE the first on `minor-mode-map-alist'."
  (let ((x (assq mode minor-mode-map-alist)))
      (when x
        (setq minor-mode-map-alist
              (cons x (delq mode minor-mode-map-alist))))))

I didn't want lispy-mode to mess with minor-mode-map-alist too actively, so I went with this approach: if lispy-mode is called interactively, i.e. via a key binding or M-x, put it ahead:

(when (and lispy-mode (called-interactively-p 'any))
    (mapc #'lispy-raise-minor-mode
          (cons 'lispy-mode lispy-known-verbs)))

It's still a work in progress, currently only lispy's RET properly yields to call cider-repl-return and slime-repl-return respectively. I'll see if there are more key bindings that need to yield. Happy coding in the New Year!

Emacs Web Wowser (EWW) got ace-link

2014-12-30T00:00:00+01:00

Emacs goodness incoming

I've discovered a nice Emacs-related blog - Content AND Presentation. Unlike The Axis of Eval, the blog that I mentioned yesterday, this one is pretty self-contained, i.e. it doesn't link to many external information sources. So I thought that it's perfect for trying EWW to read it.

Not so fast! Configure first.

For modes that don't require to self-insert (and even for some that do), I like to navigate with h/j/k/l as arrows. These arrows are on the home row, so navigation becomes a pleasant and relaxed experience. But for EWW I decided to add a little twist: if the point is in the first column, j/k will move down/up not by one line, but by one paragraph. This is great for concentration: I navigate to a paragraph, read it, navigate to the next one. The point shows me the paragraph that I'm reading, everything before the point I've already read. So every time I press j, I get a tiny warm feeling of accomplishment. I can also pair this with v, which I bind to recenter the current line to the top.

So here's what my key setup currently looks like:

(defun oleh-eww-hook ()
  (define-key eww-mode-map "j" 'oww-down)
  (define-key eww-mode-map "k" 'oww-up)
  (define-key eww-mode-map "l" 'forward-char)
  (define-key eww-mode-map "L" 'eww-back-url)
  (define-key eww-mode-map "h" 'backward-char)
  (define-key eww-mode-map "v" 'recenter-top-bottom)
  (define-key eww-mode-map "V" 'eww-view-source)
  (define-key eww-mode-map "m" 'eww-follow-link)
  (define-key eww-mode-map "a" 'move-beginning-of-line)
  (define-key eww-mode-map "e" 'move-end-of-line)
  (define-key eww-mode-map "o" 'ace-link-eww)
  (define-key eww-mode-map "y" 'eww))
(add-hook 'eww-mode-hook 'oleh-eww-hook)

As you see, I was careful to re-assign eww-back-url and eww-view-source - the commands that I've displaced from l and v. And here's the implementation of the arrows:

(defun oww-down (arg)
  (interactive "p")
  (if (bolp)
      (progn
        (forward-paragraph arg)
        (forward-line 1))
    (line-move arg)))

(defun oww-up (arg)
  (interactive "p")
  (if (bolp)
      (progn
        (forward-line -1)
        (backward-paragraph arg)
        (forward-line 1))
    (line-move (- arg))))

Cherry on the top

And while I was at it, I've added ace-link support for EWW. It was pretty easy, basically the same routine as for help-mode and info-mode. The only hard part was to figure out what part of the code keeps binding shr-save-contents to o, my preferred binding for ace-link. Turns out it was eww-link-keymap, and not shr-map. So here's the new key binding code:

(defun ace-link-setup-default ()
  "Setup the defualt shortcuts."
  (eval-after-load "info"
    '(define-key Info-mode-map "o" 'ace-link-info))
  (eval-after-load "help-mode"
    '(define-key help-mode-map "o" 'ace-link-help))
  (eval-after-load "eww"
    '(progn
      (define-key eww-link-keymap "o" 'ace-link-eww)
      (define-key eww-mode-map "o" 'ace-link-eww))))

If you haven't tried ace-link before, you can get it from MELPA. The minimal configuration that you need is this:

(ace-link-setup-default)

Here's the setup that I'm actually using:

(use-package ace-link
    :load-path "~/git/ace-link"
    :init (ace-link-setup-default))

I'm using it from my git folder since when I want to edit a project, I like to use smex's jump-to-definition.

And use-package is useful for the cases when my ~/git/ happens not to contain ace-link. In that case, instead of getting a debugger error on starting Emacs, I get only a polite "Could not load package ace-link" in my *Messages* buffer.

Monkeying around with JavaScript

2014-12-29T00:00:00+01:00

Exciting encounter

Recently, I happened upon a wonderful blog called The Axis of Eval. I knew that I'd love it just when I read the name. (or emacs pales in comparison, but I couldn't just sit on my hands for months or years while thinking up a perfect blog name. If you think of a blog name as awesome as "The Axis of Eval" and are willing to let me use it, I'll probably make the switch.

The blog did not disappoint, featuring gems like this:

In the Lisp world, new languages are built by combining large, battle-tested building blocks, and polishing or updating them when needed, instead of starting over from toothpicks and double-sided duct tape. A large Lisp like Common Lisp is like a toolchain of decades-old tools that have proven their worth, and have been codified in standards, folklore, and implementations.

The only thing in the way of extracting information and enjoyment from this blog was the horrendous theme of black background, white foreground and magenta links. Plus the RSS was kind of quirky, and I couldn't just feed all of it into Elfeed.

Greasemonkey to the rescue!

In the previous post I've mentioned that, in addition to using the best editor, I'm using the best browser. Well, this particular best browser has an extension called Greasemonkey that allows you to automatically run your own JavaScript on certain websites.

I'm not very proficient in JavaScript, the following code I just found by searching around. The part to note is the @include - the pattern of website names for which this script should be run automatically.

// ==UserScript==
// @name        background
// @namespace   abo-abo
// @include     http://axisofeval.blogspot.nl/*
// @version     1
// @grant       none
// ==/UserScript==
(function () {
    document
        .body
        .setAttribute("style",
                      "background-color: #ffffff; color:#000");
    var nodesArray = document.getElementsByTagName('a');
    for (var i = 0; i < nodesArray.length; i++) {
        nodesArray[i].style.color = 'red';
    }
})();

I can barely stand to look at it. How could you take Scheme and turn it into this monstrosity? Such a shame. But it works, so I guess everyone should learn JavaScript. All hail the mighty ~~HypnoToad~~ JavaScript!

Throwing abbrevs into the mix

2014-12-28T00:00:00+01:00

Currently, I'm using two methods for completing Elisp: company-mode and helm-lisp-completion-at-point. The latter is the cannon, the big gun: it always gets the job done, but I don't want to shoot at sparrows with it. So I only bring it out for hairy cases, like for stuff that starts with LaTeX-. Hence, the company-mode. But too often have I typed region- only to find 7 candidates staring at me, 4 of them useless. Which prompted me to look for an additional completion method.

Enter abbrevs

According to the manual,

A defined "abbrev" is a word which "expands", if you insert it, into some different text

Also,

Abbrevs can have "mode-specific" definitions, active only in one major mode

Sounds like something that could solve my problem with region- commands:

rb -> region-beginning
re -> region-end
ra -> region-active-p

Also, obviously,

Abbrevs expand only when Abbrev mode, a buffer-local minor mode, is enabled

Add it to the mix:

(defun oleh-emacs-lisp-hook ()
  (setq outline-regexp ";; ———")
  (company-mode 1)
  (abbrev-mode 1)
  (set (make-local-variable 'company-backends)
       '((company-elisp :with company-dabbrev-code)))
  (yas-minor-mode-on)
  (lispy-mode 1)
  (auto-compile-mode 1))

Some data acquisition

I had the whole abbrev thing in the back of my mind until I saw a link to the post Abbrevs for the most frequent elisp symbols. That's when I decided to act. That post eventually links to a pastebin, where 1600 abbrevs are defined. With my handy best extension for best browser I've opened the paste in ~~Emacs~~ best editor by just clicking the edit button in the RAW Paste Data section.

I had to M-x emacs-lisp-mode, since the file opened in text-mode. And boy, it's big. In lispy-mode, I usually use 99j to navigate 99 sexps down and therefore to the end of the list. Well, for this file even 999j wasn't enough. I quickly tired of deleting one-by-one the each individual useless abbrev. I mean:

ek -> echo-keystrokes,

when is that ever going to be useful? So I wrote this throw-away code:

(defun foobar ()
  (interactive)
  (lispy-mark-list 2)
  (let ((str (read (lispy--string-dwim)))
        count)
    (other-window 1)
    (goto-char (point-min))
    (setq count (count-matches str))
    (other-window 1)
    (lispy-out-backward 1)
    (deactivate-mark)
    (if (< count 5)
        (lispy-delete 1)
      (message "%d" count))))
(local-set-key (kbd "C-.") 'foobar)

After switching to a two-pane window layout, with point in the pastebin buffer, calling foobar would count the amount of the abbrev matches in my most frequent elisp buffer. If it was less than 5, the abbrev was auto-deleted, otherwise the decision was up to me, as holding C-. would no longer delete. In the end, there were only 56 abbrevs left out of 1600.

The final result

Here's what I have put into my abbrev_defs:

(define-abbrev-table 'emacs-lisp-mode-abbrev-table
    '(("sm" "string-match") ("mm" "major-mode")
      ("rb" "region-beginning") ("ca" "char-after")
      ("smd" "save-match-data") ("mb" "match-beginning")
      ("pm" "point-min") ("ir" "indent-region")
      ("sf" "search-forward") ("ci" "call-interactively")
      ("sn" "symbol-name") ("se" "save-excursion")
      ("scb" "skip-chars-backward") ("fc" "forward-char")
      ("ff" "find-file") ("fs" "forward-sexp")
      ("pa" "prefix-arg") ("re" "region-end")
      ("dc" "delete-char") ("ms" "match-string")
      ("tc" "this-command") ("dd" "default-directory")
      ("bc" "backward-char") ("rsf" "re-search-forward")
      ("snp" "substring-no-properties")
      ("bsnp" "buffer-substring-no-properties")
      ("lep" "line-end-position") ("bs" "buffer-substring")
      ("cc" "condition-case") ("ul" "up-list")
      ("bfn" "buffer-file-name") ("lb" "looking-back")
      ("tap" "thing-at-point") ("rm" "replace-match")
      ("fl" "forward-line") ("df" "declare-function")
      ("ntr" "narrow-to-region") ("dr" "delete-region")
      ("rsb" "re-search-backward") ("scf" "skip-chars-forward")
      ("wcb" "with-current-buffer") ("ie" "ignore-errors")
      ("gc" "goto-char") ("jos" "just-one-space")
      ("la" "looking-at") ("ow" "other-window")
      ("dk" "define-key") ("dm" "deactivate-mark")
      ("bod" "beginning-of-defun") ("sic" "self-insert-command")
      ("eol" "end-of-line") ("me" "match-end")
      ("nai" "newline-and-indent") ("cb" "current-buffer")
      ("atl" "add-to-list") ("rris" "replace-regexp-in-string")))

Mmm... minty

2014-12-27T00:00:00+01:00

The backstory

In one of the earlier posts, I was discussing the implementation of an Emacs Lisp lexer for Pygments. Here, I'll show how to install the update and get nicely highlighted code in a pdf via the minted LaTeX package.

The install

Assuming that you are on a Debian-related system:

sudo apt-get install mercurial
mkdir ~/git && cd ~/git
hg clone https://bitbucket.org/abo-abo/pygments-main
cd pygments-main
make mapfiles
sudo python setup.py install

And, of course, I'm assuming that you already have TeX Live installed. I'm not too sophisticated about it, so I just install everything:

sudo apt-get install texlive-full

The result

So here I took some code from a previous post and copy-pasted it into minty.org file. And here's the result of the PDF export (C-c C-e lo): minty.pdf.

The red tape

org-mode had trouble exporting on my laptop until I did this:

cd /usr/bin/
sudo ln -s /usr/local/texlive/2013/bin/x86_64-linux/pdflatex

Also be mindful of the -shell-escape flag to pdflatex:

(setq org-latex-pdf-process
      '("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
        "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
        "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))

tiny.el - the little package that could

2014-12-26T00:00:00+01:00

The Challenge

It all started with a heated discussion with the author of yasnippet over some minor nonsense. In the end, we agreed to disagree, but not before he suggested:

So I hereby challenge you to create this stripped down, no-crap, version of yasnippet. Dub it " tiny is not yasnippet " after your grandiose views and in the glorious unix tradition of recursive acronyms

The Thought Process

Well, doing exactly that would probably be lame, but I really loved the acronym. Somewhere around that time I saw some post about using eval-and-replace, i.e. inserting some Elisp in your non-Elisp buffer and then replacing that code in-place with the result of the eval.

Here's the type of code that I was playing around with:

(mapcar
 (lambda (x) (* x x))
 (number-sequence 1 7))

Then I realized that the code should probably produce a string. Here's a more refined version:

(mapconcat
 (lambda (x)
   (format "hex: 0x%x"
           (* x x)))
 (number-sequence 1 7)
 ";\n")

Loops are a useful thing to have, they are a blind spot of yasnippet, and looping is exactly what the code above does. The parameters for this loop expansion are:

integer range start: 1
integer range end: 7
separator to join the expressions: ";\n"
Elisp expression to transform the linear range: (* x x)
format expression for the result: "hex: 0x%x"

So ideally, in order to have a package called tiny, I'd like to keep only the parameters and throw away everything else.

The Result

Here's the final result of the shortening, and what tiny-expand would produce:


hex: 0x1;
hex: 0x4;
hex: 0x9;
hex: 0x10;
hex: 0x19;
hex: 0x24;
hex: 0x31

As you see, it's pretty compact, with only two characters which are not actually the parameters of the template:

m signifies the start of the template. I think this way is much better than something like having to mark the template body with a region before expanding. tiny-expand should be called from the end of the snippet, so there's no need to mark the end position.
| signifies the end of the Elisp expression and the start of the format string. It can be omitted if your format string starts with a %.

Note also the use of shortened Elisp. You can still use the full thing if you want. Or just use only the closing parens to resolve the ambiguities.

The Demos

Here are some more snippets, you can click on them to see what they expand to. You can also find them and more in the comments section of the source code:

0 1 2 3 4 5 6 7 8 9 10

5 6 7 8 9 10

5,6,7,8,9,10

25 36 49 64 81 100

19 24 31 40 51 64

0x19 0x24 0x31 0x40 0x51 0x64

a b c d e f g h i j k l m n o p q r s t u v w x y z

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z

aa,bb,cc,dd,ee,ff,gg,hh,ii,jj,kk,ll,mm,nn,oo,pp,qq,rr,ss,tt,uu,vv,ww,xx,yy,zz

aA,bB,cC,dD,eE,fF,gG,hH,iI,jJ,kK,lL,mM,nN,oO,pP,qQ,rR,sS,tT,uU,vV,wW,xX

aAa,bBb,cCc,dDd,eEe,fFf,gGg,hHh,iIi,jJj,kKk,lLl,mMm,nNn,oOo,pPp,qQq,rRr,sSs,tTt,uUu,vVv,wWw,xXx

0 and 0 and 0
2 and 1 and 1
4 and 4 and 2
6 and 9 and 3
8 and 16 and 4
10 and 25 and 5
12 and 36 and 6
14 and 49 and 7
16 and 64 and 8
18 and 81 and 9
20 and 100 and 10

6 8 10 12 14 16 18 20 22 24 26

1.0
2.718281828459045
7.38905609893065
20.085536923187668
54.598150033144236
148.4131591025766
403.4287934927351
1096.6331584284585
2980.9579870417283
8103.083927575384
22026.465794806718

00000000002.72
00000000007.39
00000000020.09
00000000054.60
00000000148.41
00000000403.43
00000001096.63
00000002980.96
00000008103.08
00000022026.47
00000059874.14
00000162754.79
00000442413.39
00001202604.28
00003269017.37
00008886110.52
00024154952.75
00065659969.14
00178482300.96
00485165195.41

1 2 4 8 16 32 64 128

0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07

0.00 1.00 2.00 3.00 4.00 5.00 6.00 7.00 8.00 9.00 10.00

* TODO http://emacsrocks.com/e01.html
* TODO http://emacsrocks.com/e02.html
* TODO http://emacsrocks.com/e03.html
* TODO http://emacsrocks.com/e04.html
* TODO http://emacsrocks.com/e05.html
* TODO http://emacsrocks.com/e06.html
* TODO http://emacsrocks.com/e07.html
* TODO http://emacsrocks.com/e08.html
* TODO http://emacsrocks.com/e09.html
* TODO http://emacsrocks.com/e10.html
* TODO http://emacsrocks.com/e11.html
* TODO http://emacsrocks.com/e12.html
* TODO http://emacsrocks.com/e13.html
* TODO http://emacsrocks.com/e14.html

* TODO Wash dog 2
DEADLINE: <2015-01-01 Thu>
* TODO Wash dog 3
DEADLINE: <2015-01-06 Tue>
* TODO Wash dog 4
DEADLINE: <2015-01-11 Sun>
* TODO Wash dog 5
DEADLINE: <2015-01-16 Fri>
* TODO Wash dog 6
DEADLINE: <2015-01-21 Wed>
* TODO Wash dog 7
DEADLINE: <2015-01-26 Mon>
* TODO Wash dog 8
DEADLINE: <2015-01-31 Sat>
* TODO Wash dog 9
DEADLINE: <2015-02-05 Thu>
* TODO Wash dog 10
DEADLINE: <2015-02-10 Tue>

You can expand them one-by-one to see what they do. As you can see, Ruby-style interpolation is available in the format string. There's also one special function called date that you can use there. It takes the start date as a string ("Jan 1" in the example) and an integer shift and prints an org-style date.

The full syntax

The full syntax for the snippet is:

m{range start:=0}{separator:= }{range end}{Lisp expr:=indentity}|{format expr:=%d}

You always start with m.
Then optional range start that defaults to 0.
Then optional separator that defaults to a single space.
Then mandatory range end.
Then optional Lisp expr, that defaults to identity.
Then optional format-style string, that defaults to %d. You have to separate it with | if the format string does not start with %. You can also Ruby-style interpolation here, e.g. %(* x x).
With the point at the end of the snippet, M-xtiny-expand.

The Summary

In the end, tiny lives up to the name, implementing only one snippet that can be used in a variety of ways.

tiny is not yasnippet

Ode to the toggle

2014-12-25T00:00:00+01:00

Man, I just love toggles: the light switches, the f - full-screen key in vlc, and the clicky pens (ooh, those are the best). So I try to model some of my Emacs key bindings as toggles.

Let me just quantify the two features that make a good toggle:

only two states: on and off
the state is visible at a glance

One could argue that with undo most editing commands become toggles. But they're not, since each time you call undo, you mess with Emacs's undo state. And the undo state isn't visible at a glance, so both requirements for a good toggle aren't fulfilled.

I'll demonstrate the two editing commands that I use every day, capitalize-word-toggle and upcase-word-toggle, that are good toggles.

`capitalize-word-toggle`

Talk is cheap. Show me the code.

(defun char-upcasep (letter)
  (eq letter (upcase letter)))

(defun capitalize-word-toggle ()
  (interactive)
  (let ((start
         (car
          (save-excursion
            (backward-word)
            (bounds-of-thing-at-point 'symbol)))))
    (if start
        (save-excursion
          (goto-char start)
          (funcall
           (if (char-upcasep (char-after))
               'downcase-region
             'upcase-region)
           start (1+ start)))
      (capitalize-word -1))))
(global-set-key (kbd "C-z") 'capitalize-word-toggle)

I may not have mentioned this before, but you should for the most part ignore the key bindings mentioned on this blog. I'm actually using them, they work for me because of my non-standard layout, but you should assign what works for you.

Anyway, capitalize-word-toggle clearly has a state that's visible at a glance: the first char of the current symbol. Also, there are only two possible states: the char can either be upper-case or lower-case. Hence, I can toggle this state with C-z for fun and profit.

Maybe some background on how this command is useful for me. I write a bunch of C++, and the code features a lot of lines like this:

Triangulation triangulation; // duh

So when I'm using auto-complete, it often eagerly expands to Triangulation when I want triangulation, and the other way around. So capitalize-word-toggle is super-useful there.

`upcase-word-toggle`

(defun upcase-word-toggle ()
  (interactive)
  (let ((bounds (bounds-of-thing-at-point 'symbol))
        beg end
        (regionp
         (if (eq this-command last-command)
             (get this-command 'regionp)
           (put this-command 'regionp nil))))
    (cond
      ((or (region-active-p) regionp)
       (setq beg (region-beginning)
             end (region-end))
       (put this-command 'regionp t))
      (bounds
       (setq beg (car bounds)
             end (cdr bounds)))
      (t
       (setq beg (point)
             end (1+ beg))))
    (save-excursion
      (goto-char (1- beg))
      (and (re-search-forward "[A-Za-z]" end t)
           (funcall (if (char-upcasep (char-before))
                        'downcase-region
                      'upcase-region)
                    beg end)))))
(global-set-key (kbd "C->") 'upcase-word-toggle)

upcase-word-toggle's state becomes binary after you call it once, since initially the thing at point could have mixed case. But afterwards, it's either all lowercase or all uppercase. So again, a clearly visible binary state is a good thing.

This command works either on (bounds-of-thing-at-point 'symbol) or on the active region. Since region-active-p is deactivated after you call the command once, there's some machinery to remember the state and to toggle when called again.

Light it up! Pygments for Emacs Lisp.

2014-12-24T00:00:00+01:00

The Challenge

More than 2 years ago, the formidable @bbatsov of Emacs Redux had this to say:

After so many years pygments (a popular syntax highlighting library used by GitHub & others) still lacks proper support for Emacs Lisp #fail
— Bozhidar Batsov (@bbatsov) September 15, 2012

Well, let's turn that #fail-frown upside down!

The Python

A quick search brought me to this page: Write your own lexer -- Pygments. Turns out that the Pygments development takes place on Bitbucket, so I had to start an account there. I shortly cloned the repository:

hg clone https://abo-abo@bitbucket.org/birkenfeld/pygments-main

Then I quickly copy-pasted some starting code:

__all__ = ['SchemeLexer', 'CommonLispLexer',
           'HyLexer', 'RacketLexer',
           'NewLispLexer', 'EmacsLispLexer']

class EmacsLispLexer(RegexLexer):
    """
    An ELisp lexer, parsing a stream and outputting the tokens
    needed to highlight elisp code.
    """
    name = 'ELisp'
    aliases = ['emacs', 'elisp']
    filenames = ['*.el']
    mimetypes = ['text/x-elisp']

    flags = re.MULTILINE

    # the rest of the code was copied from CommonLispLexer for now

Apparently, infrastructure-wise, I only need to know two commands. The first one needs to be run just once, so that Pygments is aware of the new lexer:

$ cd ~/git/pygments-main && make mapfiles

The second command is to (re-)generate /tmp/example.html:

$ cp ~/git/emacs/lisp/vc/ediff.el \
  ~/git/pygments-main/tests/examplefiles/
$ ./pygmentize -O full -f html -o /tmp/example.html \
  tests/examplefiles/ediff.el

I would repeat the last line with each update to the code, and then refresh the page in Firefox to see the result.

The Elisp

To finalize the lexer, the following tasks ensued:

get a list of built-in macros
get a list of special forms
get a list of built-in functions

In the process, I've added two more lists:

a list of built-in functions that are highlighted with font-lock-keyword-face:

'defvaralias', 'provide', 'require',
'with-no-warnings', 'define-widget', 'with-electric-help',
'throw', 'defalias', 'featurep'

a list of built-in functions and macros that are highlighted with font-lock-warning-face:
```
'cl-assert', 'cl-check-type', 'error', 'signal',
'user-error', 'warn'
```

To generate the other three lists, I started off writing things in *scratch*, but after a while my compulsion to C-x C-s kicked in and I've saved the work to research.el. At least, thanks to @bbatsov, I'm not C-x C-s-ing that much since I've added this:

(defun save-and-switch-buffer ()
  (interactive)
  (when (and (buffer-file-name)
             (not (bound-and-true-p archive-subfile-mode)))
    (save-buffer))
  (ido-switch-buffer))
(global-set-key "η" 'save-and-switch-buffer)

But it's time for the student to one-up the master, so here's a tip to improve even further:

(defun oleh-ido-setup-hook ()
  (define-key ido-buffer-completion-map "η" 'ido-next-match))

This way I can cycle the buffers with the same shortcut that invokes save-and-switch-buffer. The defaults are C-s and C-r, in case you didn't know.

The C

Getting the list of built-in C functions and special forms, obviously involved browsing the C source code. In case you don't (yet) have the Emacs sources, they're here:

$ git clone git://git.savannah.gnu.org/emacs.git

I switched to the ./src directory and called M-x find-name-dired with *.c to build a list of all the sources. Then I ran the following code from research.el:

(defvar foo-c-functions nil)
(defvar foo-c-special-forms nil)

(defun c-research ()
  (let ((files (dired-get-marked-files))
        (i 0))
    (dolist (file files)
      (message "%d" (incf i))
      (with-current-buffer (find-file-noselect file)
        (goto-char (point-min))
        (while (re-search-forward "^DEFUN (" nil t)
          (backward-char 1)
          (let ((beg (point))
                (end (save-excursion
                       (forward-list)
                       (point)))
                str)
            (forward-char 2)
            (search-forward "\"" nil t)
            (setq str (read (buffer-substring-no-properties
                             (+ beg 2) (1- (point)))))
            (if (re-search-forward "UNEVALLED" end t)
                (push str foo-c-special-forms)
              (push str foo-c-functions))))))))

This was beautiful, by the way, to just generate this sort of documentation from such well-formatted and documented C sources. Free Software FTW.

If you're interested, there are 1294 built-in functions. Here's a list of 23 special forms that I found:

and catch cond condition-case defconst
defvar function if interactive let let*
or prog1 prog2 progn quote
save-current-buffer save-excursion
save-restriction setq setq-default
unwind-protect while

You can read up on the special forms in the SICP. There's no node for them, so just use isearch.

The Result

You can see it here: ediff.html, as well as on the rest of the site, since I've switched it on everywhere.

The Impact

Unfortunately this won't have impact on the Github source code highlighter, since Github dropped Pygments recently.

But people that use the static blog generator Jekyll or the LaTeX package minted (that's the package that org-mode's PDF Export uses by default) will be able to get better Elisp highlighting. In fact, this blog is already using the new highlighter.

See the rest of projects that use Pygments here

The Bitbucket

So now, to share the new lexer with the world I just have to learn how to:

stage and commit in Mercurial
push Mercurial to Bitbucket
open a pull request on Bitbucket

I don't want to become a hipster, these things just happen.

upcase-word, you so silly

2014-12-23T00:00:00+01:00

Do you know what the most frequently used Emacs commands are? I can confirm by my own experience that they are next-line and previous-line (in that order). So why do M-u - upcase-word, M-l - downcase-word, and M-c - capitalize-word have such terrible synergy with Emacs's best commands?

No, upcase-word, this is not what I had in mind:

Learn basic keystroke commands
Overview of Emacs features at gnu.org

M-u

Learn basic keySTROKE commands
Overview of Emacs features at gnu.org

If you say:

But how did you get the cursor in such a crazy position in the first place? You should have used M-b/M-f.

Well, I got there with previous-line - one of the best Emacs commands!

Resolve the `*-word` malarkey with `defadvice`

Here are some simple advice commands that I've just rolled:

(defadvice upcase-word (before upcase-word-advice activate)
  (unless (looking-back "\\b")
    (backward-word)))

(defadvice downcase-word (before downcase-word-advice activate)
  (unless (looking-back "\\b")
    (backward-word)))

(defadvice capitalize-word (before capitalize-word-advice activate)
  (unless (looking-back "\\b")
    (backward-word)))

Small explanation to the Elisp novices:

before upcase-word is called, execute the body of upcase-word-advice
unless we are at the beginning of the word
backward-word once to move to the beginning of the word

I'm intentionally not using the newest advice system here, since not everyone has yet upgraded to Emacs 24.4. In fact, I saw this gem today at Stack Overflow:

I am using Emacs 23 and cedet 1.0.1 ...

Sometimes things break

2014-12-22T00:00:00+01:00

I was very surprised to find the lispy build broken after I pushed some minor update, like a change to README.md. I mean, how in the world would a few words in README.md break the Elisp tests? Upon investigation, it turned out that only one test was broken ¹. This one:

(ert-deftest clojure-thread-macro ()
  (require 'cider)
  (should
   (string=
    (lispy-with
     "|(map sqr (filter odd? [1 2 3 4 5]))" "2(->>]<]<]wwlM")
    "(->> [1 2 3 4 5]\n  (map sqr)\n  (filter odd?))|")))

The culprit was an update in clojure-mode's indentation. The previous behavior:

(->> [1 2 3 4 5]
   (map sqr)
   (filter odd?))

is now replaced with:

(->> [1 2 3 4 5]
     (map sqr)
     (filter odd?))

Thankfully, the Travis CI in combination with cask is keeping me up to date. Apparently, there were some heated discussions accompanying the change, and there was some reverting going on. Anyway, it looks to me that both approaches have merit: the first one is more logical, since ->> is an operation akin to Elisp's with-current-buffer, where the first argument is different from the others, while the second one is more aesthetically pleasing. Fine with me either way, I'm not complaining:)

Also, the key sequence in the test is pretty ancient. These days I'd probably use: 2(->>C-fd<j<skwAM. I've recently done a more complex Elisp refactoring screencast, check it out here. Later on, I plan to do more Emacs-related screencasts (not just lispy-related) on my channel.

If you haven't tried lispy yet, you're missing out - doing this refactor operation feels like you're doing the 15-number puzzle:

And that's fun in my book. But let me get back to the short overview of the Emacs testing tools that lead me to this post, mainly cask.

`cask`: what does it do?

According to its own documentation:

Cask is a project management tool for Emacs Lisp to automate the package development cycle; development, dependencies, testing, building, packaging and more.

Yes, please, I'd like to do that! But after the exciting intro sentence, there's very little followup documentation-wise. It took me ages to figure out how cask can actually give me some tangible benefits, since I thought that package.el is enough to maintain my own config (it still is).

tangible benefits of `cask`

I'd like to be sure that my packages work across recent Emacs versions. I'm using the bleeding edge myself, but people who download my packages from MELPA might be using something older, like emacs-24.3.

So I want to run my tests on both versions. Also, even for just one version, the tests need to be run in a minimum environment, i.e. with only the dependencies loaded, so that my personal configuration does not interfere with the tests.

This is where cask actually shines: it can bootstrap a whole new .emacs.d, separate from your own, just for running tests. It can do it on your machine as well as on Travis CI.

Here's my Cask file for lispy:

(source gnu)
(source melpa)

(package-file "lispy.el")

(files "*.el" (:exclude "init.el" "lispy-test.el"))

(development
 (depends-on "helm")
 (depends-on "ace-jump-mode")
 (depends-on "noflet")
 (depends-on "iedit")
 (depends-on "multiple-cursors")
 (depends-on "cider")
 (depends-on "slime")
 (depends-on "geiser")
 (depends-on "projectile")
 (depends-on "s")
 (depends-on "highlight"))

And here's the Makefile:

EMACS = emacs
# EMACS = emacs-24.3

CASK = ~/.cask/bin/cask
CASKEMACS = $(CASK) exec $(EMACS)
LOAD = -l lispy-inline.el -l lispy.el -l lispy-test.el

all: test

cask:
    $(shell EMACS=$(EMACS) $(CASK))

compile:
    $(CASKEMACS) -q  $(LOAD) lispy.el \
    --eval "(progn (mapc #'byte-compile-file '(\"lispy.el\" \"lispy-inline.el\" \"le-clojure.el\" \"le-scheme.el\" \"le-lisp.el\")) (switch-to-buffer \"*Compile-Log*\") (ert t))"

test:
    $(CASKEMACS) -batch $(LOAD) -f ert-run-tests-batch-and-exit

clean:
    rm -f *.elc

As you can see, the Makefile has two separate testing targets: an interactive one (compile) and a non-interactive one (test). There's actually some validity to this, since it happened once that the same tests we failing in non-interactive mode, but passing in interactive mode. Also, compile obviously compiles, testing for compilation warnings/errors. I can change the Emacs version at the top, although I don't have to do it too often.

Finally, here's .travis.yml:

language: emacs-lisp
env:
  matrix:
    - EMACS=emacs24

before_install:
  - sudo add-apt-repository -y ppa:cassou/emacs
  - sudo apt-get update -qq
  - sudo apt-get install -qq $EMACS
  - curl -fsSkL --max-time 10 --retry 10 --retry-delay 10 https://raw.github.com/cask/cask/master/go | python

script:
  - make cask
  - make test

So each time I push a change to github, Travis CI will

install emacs24
install cask
install the packages from MELPA:
- helm
- ace-jump-mode
- noflet
- iedit
- multiple-cursors
- cider
- slime
- geiser
- projectile
- s
- highlight
load Emacs with these packages
load lispy-test.el and run it
show up green if make test returned 0

Seems a bit wasteful, but it's the Cloud - what can you do?

upon even further investigation, the test itself was broken for almost a year, since lispy-with-clojure should have been used instead of lispy-with, but cider was changing the indentation of ->> also for emacs-lisp-mode, so things were kind of working out ↩

Easy helm improvement

2014-12-21T00:00:00+01:00

When you press DEL (also known as backspace) in a helm buffer, and there isn't any input to delete, it only errors at you with:

Text is read only

Why not make it do something useful instead, for instance close helm?

Easy:

(require 'helm)
(defun helm-backspace ()
  "Forward to `backward-delete-char'.
On error (read-only), quit without selecting."
  (interactive)
  (condition-case nil
      (backward-delete-char 1)
    (error
     (helm-keyboard-quit))))

(define-key helm-map (kbd "DEL") 'helm-backspace)

Poyekhali!

2014-12-20T00:00:00+01:00

Welcome to (or emacs!

My name is Oleh and I've been using Emacs for about 3 years now. I think that it's an awesome editor, and I've accumulated some know-how to make it even better (at least for me and people who think like me). Sharing is caring, so here we go.

`ace-window` update

On this weekend I've made a major update to my package ace-window that allows it to be used as a library. Luckily the change went smoothly, as there are no complaints in the github issues so far. In case you don't know what the package does in the first place, a short blurb follows.

`ace-window`'s "what and why"

I'm sure you're aware of the other-window command. While it's great for two windows, it quickly loses its value when there are more windows: you need to call it many times, and since it's not easily predictable, you have to check each time if you're in the window that you wanted.

Another approach is to use windmove-left, windmove-up etc. These are fast and predictable. Their disadvantage is that they need 4 key bindings. The default ones are shift+arrows, which are hard to reach.

This package aims to take the speed and predictability of windmove and pack it into a single key binding, similar to other-window. To achieve this, I'm using the excellent ace-jump-mode.

Here's how the package looks in action: ace-window.gif

Since switching windows is a frequently used operation, I recommend binding ace-window to something short, like M-p.

By default, three actions are available:

M-p - select window
C-u M-p - swap the current window with the selected window
C-u C-u M-p - delete the selected window

finally, the library part

So now, what if you want to select a window to maximize with ace-window? After the change that I've mentioned, the code to do this is dirt simple:

(defun ace-maximize-window ()
  "Ace maximize window."
  (interactive)
  (setq aw--current-op
        (lambda (aj)
          (let ((wnd (aj-position-window aj)))
            (select-window wnd)
            (delete-other-windows))))
  (aw--doit " Ace - Maximize Window"))

(global-set-key (kbd "C-M-o") 'ace-maximize-window)

(or emacs

Happy New Year 2022!

Intro

Emmet-mode

Getting emmet-mode for free

Personal

Outro

Happy New Year!

Intro

Org-roam

Org-roam config

Outro

Ivy 0.13.0 is out

Intro

Overview

Details on changes

Highlights

New bindings

New features

counsel-package

counsel-M-x

counsel-rg

ivy-update-candidates

ivy-use-virtual-buffers

New Commands

Outro

Ivy 0.12.0 is out

Intro

Overview

Details on changes

Highlights

New bindings

New Commands extensions

New Commands

Outro

Ivy reverse-i-search

Introduction

Getting better history completion with Ivy

Recent improvement: delete history items

Outro

Ivy usability improvements when dealing with directories

Introduction

File name completion

Directory creation

An alternative key binding scheme

Canceling dired-dwim-target

Outro

hydra 0.15.0 is out

Highlights

Display hints using posframe

Less boilerplate in defhydra

Add heads to an existing hydra

Outro

avy 0.5.0 is out

Highlights

New API functions

New dispatch actions

New avy-style setting: 'words

avy-linum-mode

Restarting an avy search

Outro

Change the current time in Org-mode

Intro

How to close 20 TODOs using a timestamp in the past

Outro

Swiper-isearch - a more isearch-like swiper

Intro

Problem 1: slow startup

Problem 2: candidates are lines

Enter swiper-isearch

Outro

Progress bars for apt in shell

Intro

Initial work around

Progress bar in the mode line

Use the Echo Area instead of the mode line

Using exclusion patterns when grepping

Git

Ivy integration for Git

Using .ignore with ripgrep

`counsel-package`

`counsel-M-x`

`counsel-rg`

`ivy-update-candidates`

`ivy-use-virtual-buffers`

Canceling `dired-dwim-target`

New `avy-style` setting: 'words

`avy-linum-mode`

Restarting an `avy` search

Enter `swiper-isearch`

Using `.ignore` with ripgrep

Use `C-d` in ivy-occur buffers

`ivy-occur` for grep-like functions

`ivy-occur` for `ivy-switch-buffer`

`ivy-occur` for `counsel-find-file`-like functions

Using `customize` with orca