Emacs on manuel uberti

Insert date at point

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 21 Sep 2025 00:00:00 +0000

I don’t know why I haven’t shared this little helper before, but here it is.

(defun mu-date-at-point (date)
  "Insert current DATE at point via `completing-read'."
  (interactive
   (let* ((formats '("%Y%m%d" "%F" "%Y%m%d%H%M" "%Y-%m-%dT%T"))
          (vals (mapcar #'format-time-string formats))
          (opts
           (lambda (string pred action)
             (if (eq action 'metadata)
                 '(metadata (display-sort-function . identity))
               (complete-with-action action vals string pred)))))
     (list (completing-read "Insert date: " opts nil t))))
  (insert date))

What mu-date-at-point does is formatting the current date in four different ways with format-time-string and then offering them as options to completing-read.

The interesting part is how opts is built. It’s a nice trick to ensure its content is always sorted according to the order in formats. Without leveraging completion-metadata the completion system would take care of sorting the items for me.

For the record, I learned how to tweak completion-metadata on Emacs StackExchange. I suggest reading C-h f completing-read and C-h f completion-metadata to know more.

Delete duplicate words

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 15 Jun 2024 00:00:00 +0000

I make a lot of mistakes when I write prose, because I usually write down everything that comes to mind and then edit sentences and paragraphs over and over again until I get what I want. This is a recipe for all sort of errors, of course.

Although I have been a happy user of Flyspell and proselint, in order not to get distracted by warnings and errors nowadays I like to avoid automatic spell-checkers or linters and rely on ispell-buffer.

There is however a specific category of errors for which ispell-buffer cannot help: duplicate words. When quickly rephrasing a sentence or adjusting a paragraph it could happen that I do not pay enough attention to the words I remove and so I keep typing with no care whatsoever.

Much in the spirit of my occasional use of ispell-buffer, I want a command that scans the buffer, finds consecutive occurrences of the same word, and removes all but one of them. Emacs already has a built-in solution for this: C-M-% (query-replace-regexp).

Nevertheless, laziness prevails. Why typing the necessary regular expression every time when a simple command can do it for me?

(defun mu-delete-duplicate-words ()
  "Delete duplicate words via `query-replace-regexp'."
  (interactive nil text-mode)
  (save-excursion
    (goto-char (point-min))
    (query-replace-regexp "\\(\\b\\w+\\b\\)\\W+\\1\\b" "\\1")))

Thesis frontispiece with LaTeX

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 10 Apr 2024 15:00:00 +0000

Usually when I start writing a new document I am not immediately interested about the output layout. This may sound unorthodox to one accustomed to the WYSIWYG likes of Microsoft Word, but since I mainly write in Markdown and LaTeX, I like to focus on what I want to say first and think about typesetting the text later. The look of the output matters, though, so eventually I have to deal with it.

For example, while working on my BA thesis with LaTeX I was faced with the problem of the frontispiece. Ca’ Foscari university provides a template that students can slap in front of their documents, but the choice is limited to a couple of popular file formats: DOC and ODT.

The quick and dirty solution could have been along these lines:

edit the ODT template;
export it to a PDF file;
add it to the front of my final document.

However, I decided to stick with AUCTeX and accept the challenge. The following is a working example based on my thesis that can be saved to a frontispiece.tex file:

\documentclass[12pt]{book}
\usepackage{geometry}
\usepackage{graphicx}
\usepackage{xcolor}

\begin{document}

\begin{titlepage}

\newgeometry{top=1cm,bottom=1cm,right=1cm,left=1cm}
\fontfamily{lmss}\selectfont
\includegraphics[width=0.15\textwidth]{cafoscari-logo}\par\vspace{1cm}

\begin{center}
\LARGE{Corso di Laurea triennale in \colorbox{gray!10}{indirizzo}\par}
\vspace{1cm}
\LARGE{Tesi di Laurea\par}
\vspace{1.5cm}
{\huge\bfseries \colorbox{gray!10}{titolo}\par}
\LARGE{\colorbox{gray!10}{sottotitolo}\par}
\end{center}
\vspace{2cm}
\vfill
\textbf{Relatore}\\
\colorbox{gray!10}{nome e cognome}\\[0.5cm]
\textbf{Laureando}\\
\colorbox{gray!10}{nome e cognome}\\
\colorbox{gray!10}{numero matricola}\\[0.5cm]
\textbf{Anno Accademico}\\
\colorbox{gray!10}{0000/0001}
\vfill

\end{titlepage}

\end{document}

The only missing bit is the Ca’ Foscari university logo, referenced above as {cafoscari-logo} as per the name of the image file I used, which is cafoscari-logo.png. Here it is:¹

Now, getting a PDF is simply a matter of placing the .tex and the .png files in the same directory and run something like pdflatex frontispiece.tex.

On the other hand, I have AUCTeX and PDF Tools on my side. From the comfort of Emacs I can then set TeX-view-program-selection to '((output-pdf "PDF Tools")) and then press C-c C a to create and display the desired PDF output.

One last remark for any Ca’ Foscari student reading this. To the best of my knowledge supervisors in the Philosophy department usually ask for drafts in DOC format. Although this may not be true for other departments, unless LaTeX is a requirement make sure your supervisor and assistant supervisor, if any, accept PDFs when you want their valuable opinion on your draft.

The logo comes from the ODT template, which is publicly available on the university website. I just extracted it to a PNG file using LibreOffice Writer. ↩︎

My 2023

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 22 Dec 2023 00:00:00 +0000

Another year, another recap. 2023 has been a strange bunch of months for different reasons. Last year I complained about not finding enough motivation with my studies and the book clubs I had joined. 2023, on the other hand, has been definitely better in these regards. I will return to my studies later when I will deal with my favourite books, but in terms of book clubs I am now a member of the Proust Society of Greenwich and I have found myself deeply involved in monthly discussions on my favourite author. A rewarding experience to say the least, something I would like to expand on soon.

Anyway, let’s proceed.

Emacs

I have to say 2023 has seen few experiments with the one and only text editor. I have moved around completion solutions just to rely on the standard, built-in one eventually, because it has been much improved in Emacs 29 and therefore in the development version I use as well. The one thing I was missing is a predictable behaviour for the window containing the *Completions* buffer. Basically, I want this window to always pop up at the bottom.

(add-to-list
 'display-buffer-alist
 '("\\*Completions*\\*"
   (display-buffer-reuse-mode-window display-buffer-at-bottom)))

Furthermore, I have been relying a lot on project-compile to run unit and integration tests and execute shadow-cljs when needed. Speaking of Cloure, I have played around a bit with clojure-ts-mode with nothing to be sad about, although I have yet to find corner cases which regular clojure-mode seriously struggles with.

Learning French

Early this year I briefly mentioned my intention to learn French in order to read the entirety of Proust’s oeuvre. I started with the popular Duolingo, but after a while I was tired of random phrases without context. I cannot learn a language like this. At most this is good for practising and revising.

Therefore I went with the good old way: a proper course with a professional language teacher. I looked for one on Preply until I found the teacher with the right qualifications. Everything has been great so far, my basic knowledge of French has already improved a lot.

Along with the lessons I have been following the same approach I had used in the past to learn English: language exposure. I watched my first French film without English subtitles (Roman Polanski’s J’accuse), I read my first French book with a dictionary on the side and no translation to help me (Neige Sinno’s Triste tigre), I have been reaching for French news (Franceinfo and France 24), and I have been keeping a grammar book next to me for some extra practice.

All of this would not make much sense if I had not set a goal for myself, which is a DELF B2 certification. It will take time, but I will get there.

Books

First, the usual selection from this year’s readings:

I piaceri e i giorni (Marcel Proust)
Jean Santeuil (Marcel Proust)
Saggi (Marcel Proust)
Vita di Marcel Proust (Jean Yves-Tadié)
Giovanni’s Room (James Baldwin)
Teoria del romanzo (Guido Mazzoni)
Le vite del romanzo (Thomas Pavel)
The Idiot (Elif Batuman)
Sulla poesia moderna (Guido Mazzoni)
Either/Or (Elif Batuman)
Bel Ami (Guy De Maupassant)
Blonde (Joyce Carol Oates)
Fontamara (Ignazio Silone)
Senza intellettuali (Giorgio Caravale)
Triste tigre (Neige Sinno)

There is no need to explain again why Proust is there. Nonetheless, here are some additional notes:

literary theory is a wonderful thing;
I consider Elif Batuman one of the most interesting writers out there. Her newsletter is a nice way to entertain me while I eagerly wait for her next book;
Blonde hit me on so many levels that I have struggled to find something interesting to write about it. I honestly believe it is one of the greatest books I have ever put my eyes on;
Triste tigre started as an exercise because I wanted to read something in French and it has ended up being an emotional tour de force. A Lolita from the other side if you will.

There is another author that has played an important role in the last months, but I have not put him on the list because I have only studied bits and pieces of his writings so far. Still, since it has already been moving me in so many ways,¹ he deserves a mention: Antonio Gramsci. Thanks to a course on political philosophy I have finally had the chance to study Gramsci more closely and work on my rather sparse knowledge of him. The more I dig the more he is leaving a mark on me as great as Spinoza’s.

Music

The new records from RVG and Angie McMahon came out right when I needed them this year. RVG showed up with their best album so far, fiercely personal and less obvious about its roots than the two before, while McMahon healed her wounds with an open letter from her heart to the world, as close to a real-life hug as possible.

I should also put Róisín Murphy here. Even though her controversial statements ruined her party, I still believe her latest effort is fantastic. And let’s not forget about Paul St. Hilaire, who came back after many years with all the dub vibes one could ask for.

As for Italy, I am glad the people behind the music festival I mentioned last year are back with a new place for great live music. Thanks to them I found out about Trust The Mask and their lovely Idiom. It was impossible to stay still at the concert, a sign of undeniable quality. I have also the utmost respect for the intrepid Daniela Pes, whose Spira sounds like nothing else around me, and only good words for Marta Del Grandi and The Thugs.

However, boygenius’ the record and, to a lesser extent, the follow-up EP the rest are what 2023 has been mostly all about in terms of music. The vinyl did not come cheap, but the record has been pretty much my go-to album until McMahon stole its thunder. It does not matter, anyway, because boygenius are a storm and they still have plenty a thunder to share.

As for older music, I have fallen madly in love with Ada Oda, who are clearly here to remind me new wave is as relevant for me today as it was back in my youth, and I have found something worth of attention in Andrew WK’s most recent and less appreciated albums. They cannot match the wild rides of his first two works but at least they do find him at peace with himself somehow.

Cinema

Just as it has been a great year for studying and reading, cinema has found its way to my heart again. The following is a mixed selection of titles from 2023 and from 2022, because I had so much to catch up with.

Knock at the Cabin (M. Night Shyamalan)
La Nuit du 12 (Dominik Moll)
Novembre (Cédric Jimenez)
Coma (Bertrand Bonello)
Pacifiction (Albert Serra)
Blonde (Andrew Dominik)
Avatar: The Way of Water (James Cameron)
Malum (Anthony DiBlasi)
Sick of Myself (Kristoffer Borgli)
Bodies Bodies Bodies (Halina Reijn)
Anatomy of a Fall (Justine Triet)
Bottoms (Emma Seligman)
Ferrari (Michael Mann)
Priscilla (Sofia Coppola)
May December (Todd Haynes)

As I did with books, some extra notes:

French cinema is still able to say things like nobody else;
Blonde is absolutely fantastic and I wonder if my appreciation for it could explain why I feel so distant from most contemporary film critics;
James Cameron is once again reinventing cinema;
I am so happy that horror films still talk to me;
I did not need Ferrari to love Michael Mann, but I am glad he wanted to make sure my feelings have not changed.

So much so that the critical editions of his Notebooks and Letters are already next to me. ↩︎

Using Ugrep with Embark

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 01 Oct 2023 00:00:00 +0000

When I wrote about using Ugrep with Consult I hinted at the chance of having my custom command available in Embark as well.

Building on top of Consult is great. Much like consult-git-grep and consult-ripgrep, the integration with Embark is around the corner.

As Omar Antolín Camarena explained to me, though, it is not immediately obvious how to combine mu-consult-ugrep with Embark.

Consult async search commands are tricky to use as Embark actions, which is why there is an entire, nontrivial embark-consult package to set up the integration.

However, he kindly suggested the solution to my problem as well. I just had to add it to my setup:

(with-eval-after-load 'embark-consult
  (setf (alist-get 'mu-consult-ugrep embark-target-injection-hooks)
        '(embark-consult--prep-async embark--allow-edit))

  (setf (alist-get 'mu-consult-ugrep embark-pre-action-hooks)
        '(embark--unmark-target))

  (setf (alist-get 'mu-consult-ugrep embark-around-action-hooks)
        '(embark-consult--projectless embark--cd))

  (keymap-set embark-consult-search-map "u" #'mu-consult-ugrep))

The above code lets me call mu-consult-ugrep on the candidate at point with C-. C u, where C-. corresponds to embark-act while C gives me access to embark-consult-search-map. This approach complements my regular usage of mu-consult-ugrep via M-s u, which I generally use when what I am looking for is not the thing at point.

Note that C-. C u can be just as easily replaced by M-s u M-n M-n to leverage Emacs’ future history¹ or even by a basic wrapper around mu-consult-ugrep that would grab the thing at point. This is Emacs, of course, so the user is in charge of their preferences.

Type C-h i g (emacs) Minibuffer History RET to know more. ↩︎

Using Ugrep with Consult

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 16 Sep 2023 00:00:00 +0000

I have already discussed how one can leverage ugrep and consult-xref to make a completing-read variant of project-find-regexp.

However, today I would like to go a bit further and show how easily Consult can be extended to include a command that behaves like consult-grep, consult-git-grep, and consult-ripgrep, but with ugrep as its engine. True, something along these lines has been around for a while. And yet I have no need for an external package when Consult has everything in place in order to devise a custom command.

By inspecting the code behind consult-git-grep and consult-ripgrep the pattern is pretty clear:

a defcustom with the command (e.g., git grep) and its arguments
a builder function to create the actual command to be invoked (e.g., consult--git-grep-make-builder)
a wrapper around consult--grep (e.g., consult-git-grep)

Therefore, the solution is simple:

(defvar mu-consult-ugrep-args (string-join '("ugrep"
                                             "--color=never"
                                             "--exclude-dir=.git/"
                                             "--hidden"
                                             "--ignore-binary"
                                             "--ignore-case"
                                             "--line-buffered"
                                             "--line-number"
                                             "--null"
                                             "--recursive")
                                           " "))

(defun mu-consult-ugrep-make-builder (paths)
  "Create ugrep command line builder given PATHS."
  (let ((cmd (consult--build-args mu-consult-ugrep-args)))
    (lambda (input)
      (pcase-let* ((`(,arg . ,opts) (consult--command-split input))
                   (`(,re . ,hl)
                    (funcall consult--regexp-compiler arg 'extended t)))
        (when re
          (cons (append cmd
                        (cdr (mapcan (lambda (x) (list "--and" "-e" x)) re))
                        opts paths)
                hl))))))

(defun mu-consult-ugrep (&optional dir initial)
  "Search with `ugrep' for files in DIR with INITIAL input."
  (interactive "P")
  (require 'consult)
  (consult--grep "Ugrep" #'mu-consult-ugrep-make-builder dir initial))

Since I am always using the same ugrep options, my builder function is a bit simpler than consult--git-grep-make-builder or consult--ripgrep-make-builder. Other than that, it’s only a matter of understanding the right options for ugrep.

Building on top of Consult is great. Much like consult-git-grep and consult-ripgrep, the integration with Embark is around the corner. And now that the power of the minibuffer is available during my searches I have no use for mu-recursive-grep any more.

Clojure and Tree-sitter

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 26 Aug 2023 00:00:00 +0000

By now Emacs users are well aware of Tree-sitter and the built-in integration that comes with Emacs 29. I am a bit late to the party because only recently I have started to look into treesit-language-source-alist and treesit-install-language-grammar, but right now I am more interested in how Clojure programming can benefit from Tree-sitter.

Danny Freeman is the maintainer of clojure-ts-mode, and after I kindly nudged him he made it available on NonGNU ELPA. This means that the package is only a M-x package-install away.

Once installed Emacs has to know how to prefer clojure-ts-mode to good old clojure-mode. This is where majore-mode-remap-alist comes into play.

(push '(clojure-mode . clojure-ts-mode) major-mode-remap-alist)
(push '(clojurec-mode . clojurec-ts-mode) major-mode-remap-alist)
(push '(clojurescript-mode . clojurescript-ts-mode) major-mode-remap-alist)

Since I always use CIDER let’s leverage clojure-ts-mode-hook to enable it.

(add-hook 'clojure-ts-mode-hook #'cider-mode)

This is enough to activate clojure-ts-mode, but upon entering a project I noticed the lack of a couple of useful key bindings.

(with-eval-after-load 'clojure-ts-mode
  (keymap-set clojure-ts-mode-map "C-c C-r" 'clojure-refactor-map)
  (keymap-set clojure-ts-mode-map "C-c C-x" 'cider-start-map))

Note that clojure-ts-mode is still under development. For instance, Danny is working on allowing users to pick their preferred indentation style. As Daw-Ran Liou suggested, for now I can use clojure-mode-variables to make clojure-ts-mode follow my preferred formatting settings.

(add-hook 'clojure-ts-mode-hook #'clojure-mode-variables)

I have been using clojure-ts-mode daily in the last two weeks and the experience has been great. They say Tree-sitter is a game changer. I say thank you, Danny Freeman.

Tweaking Consult completion

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 17 Jun 2023 00:00:00 +0000

After having adapted vertico--format-candidate to behave like I want in my Marginalia-less setup, I noticed I still had undesired documentation during completion.

Now, Daniel Mendler created the beautiful Corfu to improve completion at point in Emacs. However, he did not forget about old school users such as myself and provided consult-completion-in-region for the minibuffer lovers out there.

My only “problem”¹ with consult-completion-in-region is that by default candidates are offered with some related documentation next to them, much like what one would see with M-x were one to use Marginalia. It is possible to leverage consult-customize to change a subset of consult-completion-in-region details,² but to remove the extra information something else is needed.

(define-advice consult-completion-in-region
    (:around (&rest args) mu-completion-no-extra-properties)
  "Remove extra properties from completion candidates."
  (cl-letf (((default-value 'completion-extra-properties) nil))
    (apply args)))

A hack, yes, but also another way to prove the level of freedom Emacs empowers the user with.

Note that my small modifications to vertico--format-candidate and consult-completion-in-region are not intended to highlight any Vertico or Consult shortcomings. These are great packages that improve the standard Emacs experience, thus they should be tried as they come out of the box for a while. The fact that I can easily adjust them to my preferences just make them shine even more.

The quotes should be enough to suggest that this is not a real problem, but let me spell it out to avoid confusion. ↩︎
Try C-h f consult-completion-in-region RET to know more. ↩︎

Tweaking Vertico candidates

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 16 Apr 2023 00:00:00 +0000

One of the Emacs packages I do not seem to get used to is Marginalia. There is nothing wrong with it and since Daniel Mendler is involved the ELisp underneath is great. However, to me it’s just too much information where I rarely want it. When I need that sort of documentation it’s always a quick key binding away.

Given the author it should not come as a surprise that Marginalia works rather smoothly with Vertico. In fact, it works so well that I only see a “problem” when I use it without Marginalia. Months ago I reported this minor glitch to Daniel, but to cut a long story short, at the end of the current selected item vertico--format-candidate adds a newline escape sequence to which the vertico-current face is applied as well.

I know, it’s a minor thing that should not stop me from using Vertico. Still, it can be fixed quite easily. I suggested an advice in the aforementioned report, but since vertico--format-candidate is implemented as a cl-defgeneric I can do better:

(with-eval-after-load 'vertico
  (set-face-attribute 'vertico-current nil :extend nil)
  
  (cl-defmethod vertico--format-candidate (cnd pref suf idx _start)
    "Format CND given PREF, SUF, and IDX."
    (setq cnd (vertico--display-string (concat pref cnd suf "\n")))
    (when (= idx vertico--index)
      (add-face-text-property 0 (1- (length cnd)) 'vertico-current 'append cnd))
    cnd))

Beside ensuring that vertico-current does not extend beyond the selected candidate, I use the lovely named 1- function to avoid applying this face to \n as well.

Note that something like fido-vertical-mode does not need a hack like this. Yet I simply cannot resist tinkering with my favourite packages.

CIDER and Clojure LSP

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 25 Mar 2023 00:00:00 +0000

When I wrote about formatting Clojure buffers I also mentioned that Clojure LSP can take care of this among other things. Since my working days are pretty much Clojure days, it’s time to check out how LSP can help me in this regard and whether the experience is worth an extra tool.

Installing Clojure LSP is trivial so I will leave you on your own with that. After the installation the first thing I tried is the obvious M-x eglot in a Clojure buffer, but all I got was a connection timeout error as a reply. Weird, I thought, this has never happened with LaTeX. However, the solution was simple: I just needed to increase the default value of eglot-connect-timeout to 60.

Emacs can leverage many goodies from Clojure LSP thanks to Eglot, but some of them out of the box interfere with CIDER. For instance, the integration with ElDoc is better left in the capable hands of Eglot in order to avoid duplicates when displaying documentation.

(setq-default cider-eldoc-display-for-symbol-at-point nil)

(defun mu-cider-disable-eldoc ()
  "Let LSP handle ElDoc instead of CIDER."
  (remove-hook 'eldoc-documentation-functions #'cider-eldoc t))

(add-hook 'cider-mode-hook #'mu-cider-disable-eldoc)

In a similar fashion I put Clojure LSP in charge of completions. This approach is useful when in a Clojure buffer all I need is some poking around to understand the code in front of me. There is no need to jack-in with CIDER to do just that.

(defun mu-cider-disable-completion ()
  "Let LSP handle completion instead of CIDER."
  (remove-hook 'completion-at-point-functions #'cider-complete-at-point t))

(add-hook 'cider-mode-hook #'mu-cider-disable-completion)

I am sure CIDER can, and probably will, embrace Clojure LSP some day, but one cannot blame its developers for these nuisances. On the contrary, we should be grateful for the ease of customization at our disposal, which is one more reason to appreciate CIDER, if you ask me.

Anyway, now I can get rid of mu-cljfmt-format-buffer and rely on M- eglot-format-buffer for my Clojure formatting needs. A happy ending indeed, because removing code from my init.el is always a pleasure.

Jump to minibuffer from completions

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 25 Feb 2023 00:00:00 +0000

More than a month after my commitment to the default built-in completion system I can say that everything has been going smoothly. I adjusted my muscle memory to hit TAB in the minibuffer whenever I need to pop up the *Completions* window, which to my surprise has not been happening as much as I was expecting. The only thing that I added to the original setup is the following:

(keymap-set completion-list-mode-map "M-e" #'switch-to-minibuffer)

This is easier to reach than M-g M-c when I want to move from the completion window to the minibuffer. Admittedly, it’s not something that I do often, but it can be useful if I need to edit what I have just typed.

If you are wondering why I chose M-e for this, the answer is simple. I like isearch-edit-string and use it regularly, plus the e in M-e reminds me of the verb “edit”, which is what this key binding allows me to do.

Better built-in completions

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 12 Jan 2023 00:00:00 +0000

Despite me doing my best to track Emacs development and build the latest master regularly, I forgot to check out the improvements on the default *Completions* buffer that are going to be available on the next official release of our favourite text editor. Thankfully, Robert Enzmann did it for me.

Much like Robert, I’ve been living with Vertico, Consult, Corfu and Orderless for a while now, and you won’t be hearing any complaint from me on that side. These packages are simply fantastic. Still, by now a regular reader knows I enjoy the vanilla Emacs experience, and if there is a chance to stick with it I am not the one who is going to miss it.

Robert did a great job already at explaining what’s new when it comes to built-in completions and what settings you can tweak to take advantage of the new developments. He is sporting pretty animations too, so go check his writing for further details. I’ll just mention that, beside setting completions-header-format to nil, I set completion-show-help to nil to keep the *Completions* buffer as clean as possible.

A setup like this is a radical change for me. From my IDO days, I have always relied on a completion approach rather different than what is available on the very first Emacs run. Basically one that provides more than a bare prompt. As expected, it took me a while to adapt and learn to change my old habits. Take M-x, for instance. With Helm or Icomplete candidates appear before I hit other keys, and since I usually sort them by usage, I can navigate to the most recent one without typing its name at all. To overcome the confusion, I tried to think at the prompt as a shell one. Like I do in a shell, I type some letters and then reach for TAB to complete the rest. It’s not that I wasn’t doing something like this before. Think of file paths, for example. However, most of the times the initial list took me away from the prompt entirely because what I was after was a C-n away.

Moreover, every Vertico and friends user knows that they stay close to Emacs internals and work like building blocks, nicely complementing each other in order to extend step by step core functionalities. This means that nothing is stopping me to keep Consult and Orderless around or having Corfu ready to pop up completion candidates at point without having to move my eyes to the bottom of the screen. For anyone yet not convinced, this is another sound proof of how carefully the likes of Daniel Mendler and Omar Antolín Camarena designed their packages.

To get back at Robert’s article, I’ll ask myself the same question he did to himself and I’ll reply with a similar, enigmatic answer: will I see the *Completions* buffer more often from now on? Yes, probably yes.

LaTeX footnotes and Tempel

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 02 Jan 2023 00:00:00 +0000

For those who remember, the combination of AUCTeX and Eglot makes me happy. And those with even better memory surely recall me mentioning BibLaTeX for my footnotes. The thing with footnotes, though, is that having beautiful, automatic completion for my bibliography is only half of the story. The other half is leveraging yet another great package from the unstoppable Daniel Mendler: Tempel.

As usual with Daniel, the README is full of details, so there is little for me to add. Following the documentation, I have M-+ bound to tempel-complete and then I have few templates for things like clojure-mode, emacs-lisp-mode, and haskell-mode in an aptly named templates file. I also have the following for latex-mode:

(footnote "\\footnote{" p ".}")
(texcite "\\textcite{" p "}")

It may look like trivial stuff, I know, but this is all it takes to insert a footnote:

Hit M-+
Pick footnote
If no bibliographical entry is needed, type the desired text
Otherwise, hit M-+ again
Pick textcite
Let Corfu powered by Digestif offer the required bibliographical entry

Trust me, it’s a quick manoeuvre once you get used to it. It’s also a bit cumbersome, if you ask me. Daniel must know me better than I know myself because Tempel already provides a simpler option, namely the tempel-key macro.

(with-eval-after-load 'tex
  (tempel-key "C-c t f" footnote TeX-mode-map)
  (tempel-key "C-c t t" texcite TeX-mode-map))

Now with few key strokes and AUCTeX doing the rest of the heavy lifting I can safely focus on the content of my document without worrying about the footnotes.

Note that tempel-key sort of fixes a small issue with tempel-complete. When I hit M-+ right after the last letter of a word, I get a message saying tempel--interactive: tempel-complete: No completions. To avoid this unpleasant behaviour either I add an extra whitespace character to be removed after the footnote is ready, or I use tempel-key. The better alternative is obvious.

A final warning: the most recent version of Digestif introduced a problem with completion-at-point and Xref, which I reported on the bug tracker. For now it’s possible to work around the issue by using commit f1b4202 as I wrote over there.

My 2022

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 22 Dec 2022 00:00:00 +0000

This year I am going to approach my usual recap in a different way. Instead of separating best-of lists I will look back at 2022 in a single writing to keep it simple.

2022 will not be remembered as a particularly stimulating time. For instance, I have struggled to keep my enthusiasm alive when it comes to university. This is not solely because of the whole mess with dual lessons, but it encompasses the quality of the courses and what I have been learning as well. Maybe I will return on this at some point in the future, but for now let me just add that once again I can’t wait to get it over with. Almost the same reasoning can explain why I left the two book clubs I had joined in 2021. I was not pleased by the reading choices nor by the discussions around them, and more often than not it felt like I was putting obstacles between me and the books I want to read. But let’s set aside the negativity for a while and see what really mattered this year.

Emacs

I usually document my Emacs adventures on this website so I’ll be brief. For the ever-present and more reliable software in my computing life this has been the first year fully away from Magit and MELPA. The built-in VC system has been a trustworthy companion, and the combination of GNU ELPA and NonGNU ELPA has provided the few external packages I need. Speaking of packages, Eglot deserves a mention. It’s true that I don’t use it for work, but whenever I deal with academic writings (LaTeX) or hobby projects (Haskell) Eglot has made me appreciate some of the goodies that LSP has to offer. Another package worth being included here is detached.el, which I’ve been using to run commands like bundle, yarn, and shadow-cljs from shell-mode without losing control of the buffer. So neat.

SourceHut

Early this year I moved my projects from GitHub to SourceHut. This was such an important step for me because for my repositories I don’t want to worry about actions, notifications, unnecessary JavaScript, and giant corporations stalking my code. SourceHut firmly avoids all of that and provides the user with a small set of great tools. GitHub helped me to get out of my cave and learn how to share and collaborate with others, something not to be underestimated. However, SourceHut cares. The least I could do was joining them to support this wonderful act of caring.

DivestOS

After almost six years, in May I decided to leave the default Fairphone OS behind and look for something different. The experience with DivestOS has been so fantastic I had to make a donation to this awesome project. My phone battery now lasts longer than ever before and the user interface is generally more responsive, but the true value of this OS is that I have a Google-free Fairphone 2 that works as expected. For a person who has basic needs when it comes to their smartphone and wishes for better privacy, DivestOS is the perfect solution.

Books

From the book lover perspective 2022 has been intense, and I am not referring to the total number of pages I read. What I mean is the profound quality of the works I’ve been through and the hours spent thinking both while reading and after the turn of the last page. Even in the one case where I got angry at the author it was still worth it. Here are the most rewarding readings of the past months:

Anna Karenina (Leo Tolstoy)
In the Eye of the Wild (Nastassja Martin)
Cecilia e le streghe (Laura Conti)
Malvina, or the Heart’s Intuition (Maria Wirtemberska)
Le Père Goriot (Honoré de Balzac)
Beloved (Toni Morrison)
Spinoza’s Religion: A New Reading of the Ethics (Clare Carlisle)
Horcynus Orca (Stefano D’Arrigo)
The Handmaid’s Tale (Margaret Atwood)
The Pale King (David Foster Wallace)
In Search of Lost Time (Marcel Proust)

Most of these are classics so you don’t really need my words to pick them up. Still, it’s safe to say that for one reason or another they all are experiences to treasure, worth the time and the effort that they require. If you are wondering where philosophy fits in my 2022 readings, I can say Kant, Hegel, and Deleuze are the authors I have spent a great deal of days on, but there has been room for Spinoza, Heidegger, Wittgenstein, and Adorno too.

Music

As an avid music listener and record collector, I feel a bit ashamed in this regard. The only records I bought this year are Big Time by Angel Olsen and II by Liberato, but Olsen’s costed me a small fortune, so there goes my banal excuse for not sticking more with music in 2022.

Anyway, some of my best experiences had more to do with concerts. I went to a little festival last summer, called Upside Fest, created by the same people behind the loveliest place for beer and live music around here that sadly did not survive the pandemic. The festival was all about independent music, workshops, and being friendly to each other, which is the sort of spirit the organizers always put in everything they do. It took place in the small park of what long ago was the castle of the town, a cozy and quiet environment which invites everyone to massive chill out sessions. It’s impossible to come out bored or unhappy when these people are involved.

On the opposite side of the intimacy spectrum, I finally attend a Liberato’s live performance. The show has been postponed multiple times due to COVID-19, but eventually they did it and it was glorious. I am not too fond of big concerts and huge crowds these days, but Liberato is some of the best music Italy has at the moment so I could not miss it. He pretty much remixed all of his tracks, interpolating covers and extending them with new beats for the entire set. We danced (well, jumped around mostly) and yelled Neapolitan words for two hours. Fun times indeed.

Cinema

I know this is going to sound horrible coming from a self-proclaimed cinephile, but all things considered I have not been able to feel moved, involved, passionate with a film not already part of my Blu-ray and DVD collection. I can mention Elvis and Kimi as pleasant and interesting movies, but titles such as Deep Water, Armageddon Time, and Crimes of the Future were just below my expectations. The only exception to this bleakness is The Fabelmans, which although formulaic, predictable, and not up there with the best from Steven Spielberg, shows love for the art and it understands where the heart fits among the images. It reminded me of Zhang Yimou’s One Second, hence storytelling for the sake of telling.

It looks like I have been approaching films with a precise idea of what I wanted from them, which is obviously not the right thing to do. Cinema owes me nothing and it’s up to me to be open and apply my mind accordingly. I see myself getting tired quickly with recent films, throwing around comparisons and unable to accept what is in front of me. I have not been keeping up with new releases, at least not as much as I used to, so I don’t have the proper tools to understand where cinema is going and why. I hope this is just some sort of vacation from one of my deepest and oldest loves in order to regain the mindset to be at peace with it again.

Automatically format Clojure buffers

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 27 Oct 2022 00:00:00 +0000

Contrary to my experience with free or open source projects, when it comes to the proprietary software I have been developing for work since late 2004, code formatting has never been matter of discussion. There was a team, back in my days in the UK, that enforced some strict rules via Ant, but until today that was the sole exception.

Luckily the people I am coding with nowadays are more open to this kind of problem. Yes, I used the word problem. As I explained to a co-worker when I raised the question of formatting tools, I read code as I read a book. I cannot imagine sitting through different books each written according to the authors' own ideas of stylistic conventions. It’s about having the text, whether words or code,¹ accessible to anyone by making the assumption that the first step to understanding is ease of legibility.

The team agreed on using cljfmt for this task. Most of the developers here use Clojure LSP and, from what I understand, the integration with cljfmt is already there for them. I, on the other hand, went with a more manual approach. I first built the cljfmt binary with GraalVM thanks to Rune Juhl Jacobsen’s useful cljfmt-graalvm. Rune offers a snippet for use-package and Projectile users, but I leveraged project.el and a CIDER hook instead.

(defvar mu-cljfmt-edn "cljfmt.edn"
  "The name of `cljfmt' configuration file.")
  
(defun mu-cljfmt-format-buffer ()
  "Format current buffer with `cljfmt'."
  (when (derived-mode-p 'clojure-mode)
    (let* ((pr (project-root (project-current)))
           (cfg-dir (locate-dominating-file pr mu-cljfmt-edn))
           (cfg-edn (expand-file-name mu-cljfmt-edn cfg-dir))
           (cmd (if (file-exists-p cfg-edn)
                    (format "cljfmt -c %s %s" cfg-edn buffer-file-name)
                  (format "cljfmt %s" buffer-file-name))))
      (shell-command-to-string cmd))
    (revert-buffer t t)))

(defun mu-cider-format-buffer ()
  "Automatically format current buffer after saving."
  (add-hook 'after-save-hook #'mu-cljfmt-format-buffer nil t))

(add-hook 'cider-mode-hook #'mu-cider-format-buffer)

Some things worth considering:

the location and the name of the cljfmt.edn file matter, so check your projects if you follow my approach. For instance, the snippet provided by Rune uses .cljfmt.edn. With mu-cljfmt-edn I can customize it per-project via directory variables, if needed.
clojurec-mode and clojurescript-mode are both derived from clojure-mode. This explains the use of derived-mode-p;
in buffers handled by clojure-mode I always have CIDER enabled, even if not necessarily jacked-in. For a more general approach, clojure-mode-hook should be preferred;
CIDER provides an integration with cljfmt. Depending on your needs that may be already enough.

With a tool tweaked to format code idiomatically for us, now it’s time to argue about names. Wait, let me refresh my hadoukens first.

By the way, looking at code as text is the subject of Sense and Structure: Towards a Textual Analysis of Software, a recent talk by Zach Tellman. ↩︎

Jump to the last change in the buffer

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 16 Oct 2022 00:00:00 +0000

Ages ago I did the minimally required amount of work to get Chris Done’s goto-last-point to MELPA. Recently the maintenance of that package has been taken over by someone else as part of me moving away from GitHub and caring only about projects I want to actively maintain.

The thing with goto-last-point is that it’s too much code for me. I simply want to jump back to the last change in the buffer when I need. A savvy Emacs user knows that commands such as isearch-forward (C-s) or beginning-of-buffer (M-<) push mark at the previous position, making it easy to go back to that position with a quick C-u C-SPC.

However, suppose for a moment that for some inexplicable reason you reached over to the scroll wheel to move around your buffer. C-u C-SPC cannot help you now.

(defun mu-back-to-last-edit ()
  "Jump back to the last change in the current buffer."
  (interactive)
  (ignore-errors
    (let ((inhibit-message t))
      (undo-only)
      (undo-redo))))

Bind mu-back-to-last-edit to a key binding of your choice and no matter the weird dances your point is put through, you can safely reach for the last edit without thinking too much about it.

Note that I am using ignore-errors and inhibit-message just because both undo-only and undo-redo display useful messages that, in this specific case only, I don’t need. You could avoid them if you don’t mind some noise in the echo area.

Update on Eglot and jdtls

manuel.uberti@inventati.org (Manuel Uberti) — Tue, 27 Sep 2022 00:00:00 +0000

This is just a quick update on the status of Eclipse JDT Language Server support in Eglot.

Since my Python skills are close to none, Roland Grunberg kindly stepped forward to make sure that jdtls can take care of setting up everything in order to avoid ugly workarounds in Emacs and, I guess, other text editors and IDEs as well.

The fix will be available on the next Eclipse JDT milestone. However, nothing stops you from grabbing the latest snapshot build and M-x eglot away in your Java projects.

Even though I am not working with Java these days, it’s good to know that I could do it in Emacs with the nice features LSP offers.

Working with diff-mode

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 24 Sep 2022 00:00:00 +0000

One Emacs package that has been with me for a very long time is diff-hl, and the reason is not its on-the-fly coloured fringe markers, but the fact that colours stay there when I visit the same buffer later. This is useful since more often than not I end my work day with something still in progress, so the next morning it’s easier to use diff-hl-next-hunk and diff-hl-previous-hunk to move around my unfinished edits.

However, I have put diff-hl aside because there have been some welcome improvements lately on the built-in diff-mode, especially the possibility to edit its buffer contents and commit straight from it. I now find myself using C-x v D (vc-root-diff) many times a day, and by using diff-mode more, I have started to appreciate one simple thing that was already available to me but have always ignored, that is the navigation among hunks with diff-hunk-next (n) and diff-hunk-prev (p).

The pattern, already become muscle memory, is the following:

C-x p p to enter the project I am working on
Visit the file I am interested in
Hit C-x v =
Move with either n or p to the desired hunk
Hit RET to jump to the hunk
Hit C-x 1 to hide the diff-mode buffer

Easy and quick. I guess one could even speed up the process by using something like recentf-mode, for instance, but I’ll leave that to you wild ELisp explorers.

By the way, after months with VC instead of Magit,¹ the combination of vc-dir, vc-git, diff-mode, and shell-command has resulted in one of the most dreaded command any serious Emacs user can think of, one that I cannot even type out of fear of mystical forces coming after me. Let’s just say it involves package-delete and… Dear GNU, they’re already here.

My actual focus on VC roughly started last year, see: Rebasing with VC. ↩︎

Automatically highlight regular expressions

manuel.uberti@inventati.org (Manuel Uberti) — Tue, 06 Sep 2022 00:00:00 +0000

While reading the nice Straightforward Emacs: Automatically Highlight Buffer Text, I kept wondering whether I could get a similar solution with Emacs built-in facilities. The article explains how to highlight “TK” and variations of it (e.g., “TKTKTKTK”) using the helpful hl-prog-extra. The author says they had to rely on an external package “after some searching and trial and error”, but it is in fact possible to avoid hl-prog-extra for the simple problem they are trying to solve. The trick is using font-lock-add-keywords.

First of all, I am going to use a custom face instead of the font-lock-warning-face one used in the original article, because I like to think of “TK” as a comment instead of a warning.

(defface mu-tk-face '((t :inherit font-lock-comment-face :bold t))
  "Face used to highlight \"TK\" markers.")

Then I am going to create a small function to hook into the mode where I want to use “TK” markers.

(defvar mu-tk-regexp "\\(TK\\)+"
  "Regexp to identify \"TK\" markers.")

(defun mu-markdown-mode-setup ()
  "Configure `markdown-mode'."
  (font-lock-add-keywords nil `((,mu-tk-regexp 0 'mu-tk-face))))

The rest is trivial:

(add-hook 'markdown-mode-hook #'mu-markdown-mode-setup)

This should be enough already, but since I use flyspell-mode in my Markdown documents it has to ignore “TK” so as to avoid having the flyspell-incorrect face interfering with my own mu-tk-face. In order to accomplish this, I need a function that ignores these markers so I can use it as the value of flyspell-generic-check-word-predicate.

(defun mu-flyspell-skip-tk ()
  "Ignore \"TK\" markers when spell-checking."
  (not (string-match-p mu-tk-regexp (thing-at-point 'word t))))

Finally it’s enough to add the following to mu-markdown-mode-setup:

(setq-local flyspell-generic-check-word-predicate #'mu-flyspell-skip-tk)

Now I can use “TK” markers as intended.

Hopefully it should be obvious that I am not advising against using hl-prog-extra for your highlighting needs. My code is a small solution to a tiny itch, while the scope of hl-prog-extra is much larger. The intent of this writing is just showing that for certain tasks Emacs comes already prepared.

Ugrep and consult-xref

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 01 Sep 2022 00:00:00 +0000

This is going to be a small correction to my previous post about Ugrep and project navigation.

If you remember, I was using xref-show-definitions-completing-read to make project-find-regexp offer its results in the minibuffer. The problem with that command is that the results are grouped by file, which is good, but within the groups they do not appear to be sorted by line number, which is not so good.

However, since I am already using consult the solution is right behind the corner.

(defun mu-project-find-regexp ()
  "Use `project-find-regexp' with completion."
  (interactive)
  (defvar xref-show-xrefs-function)
  (let ((xref-show-xrefs-function #'consult-xref))
    (if-let ((tap (thing-at-point 'symbol)))
        (project-find-regexp tap)
      (call-interactively #'project-find-regexp))))

The documentation of consult-xref itself is pretty clear.

Show xrefs with preview in the minibuffer.

This function can be used for ‘xref-show-xrefs-function'.

Now the only thing left is saying “Thank you, Daniel Mendler!” one more time for all his beautiful work.

Search thing at point with Ugrep

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 31 Aug 2022 00:00:00 +0000

When I described how I use Ugrep in Emacs I forgot to mention something. It’s true that I rely on project-find-regexp (C-x p g) for searches, but there is a specific use-case where this command is not as handy as it usually is: project-wide navigation.

To be more precise, in my daily workflows it can happen that all I need to do is jump to a different file where the thing at point is used. The power of project-find-regexp is too much here, because I don’t need the *xref* buffer with all the results and the ability to replace them. I just want a quick a way to hit RET on the candidate I am looking for and move to the desired file.

With xref-search-program set to 'ugrep¹ the solution is trivial.

(defun mu-project-find-regexp ()
  "Use `project-find-regexp' with completion."
  (interactive)
  (defvar xref-show-xrefs-function)
  (let ((xref-show-xrefs-function #'xref-show-definitions-completing-read))
    (if-let ((tap (thing-at-point 'symbol)))
        (project-find-regexp tap)
      (call-interactively #'project-find-regexp))))

The trick is temporarily setting xref-show-xrefs-function to xref-show-definitions-completing-read, which according to its documentation does exactly what I am looking for.

Let the user choose the target definition with completion.

When there is more than one definition, let the user choose between them by typing in the minibuffer with completion.

I then bind mu-project-find-regexp to M-? and all is set. Needless to say, the heavy work is still done by project-find-regexp. Such an awesome tool.

Note that I am overriding the default M-? on purpose, because the original xref-find-references does not take things like .gitignore into account, something absolutely necessary in large projects where I want to avoid having useless candidates spam the ever precious minibuffer.

Finally, be aware that a better version of mu-project-find-regexp can be found here.

Once again, refer to Using ugrep with Emacs for the configuration details. ↩︎

Fix jdtls configuration for Eglot

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 18 Aug 2022 00:00:00 +0000

When thanks to its developers I added support for jdtls in Eglot, I did it by removing a lot of boilerplate in the package devised to accommodate the complex setup needed for Eclipse JDT to start the language server. This made the java-mode entry in eglot-server-programs simpler and it also moved the responsibility of providing the correct defaults to the jdtls script itself.

However, recent versions of jdtls seem to still require extra configuration, in particular with regards to the -data argument that before my change was tweaked within Eglot. Understandably, Eglot’s maintainer cannot spend all his time hunting down random quirks for every LSP server out there. Therefore, it’s up to the users to update their configuration at least until jdtls takes care of this problem once and for all.

The small hack I added to my init.el is the following:

(with-eval-after-load 'eglot
  (let ((cache (expand-file-name (md5 (project-root (project-current t)))
                                 (locate-user-emacs-file "jdtls-cache"))))
    (add-to-list 'eglot-server-programs `(java-mode "jdtls" "-data" ,cache))))

The above snippet works fine with the latest jdtls (as of 2022-08-11 14:25) and OpenJDK 18.0.2-ea. I updated the relevant Eglot discussion as well, so refer to it if you need more details.

Ugrep in Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 07 Aug 2022 00:00:00 +0000

Almost a year ago I wrote about my handy mu-recursive-grep, an easy way to combine rgrep and vc-git-grep. But after Leah Neukirchen mentioned ugrep recently, I could not resist checking whether it was a good fit for my daily Emacs usage. A couple of benchmark¹ impressed me enough to add support for it directly via xref-search-program-alist.

The details to configure everything you need are over at Using ugrep within Emacs on the project README. Once set, you can just hit C-x p g (project-find-regexp) in your project and let ugrep do his magic.

Moreover, as the README mentions, it’s possible to leverage grep-template to have commands like lgrep rely on ugrep.

(setq-default grep-template (string-join '("ugrep"
                                           "--color=always"
                                           "--ignore-binary"
                                           "--ignore-case"
                                           "--include=<F>"
                                           "--line-number"
                                           "--null"
                                           "--recursive"
                                           "--regexp=<R>")
                                         " "))

Thus, mu-recursive-grep becomes a bit simpler:

(defun mu-recursive-grep (search-term search-path)
  "Recursively search for SEARCH-TERM in SEARCH-PATH."
  (interactive
   (progn
     (unless grep-command
       (grep-compute-defaults))
     (let ((search-term (grep-read-regexp))
           (search-path (expand-file-name
                         (read-directory-name
                          "Directory: " nil default-directory t))))
       (list search-term search-path))))
  (lgrep search-term "*" search-path))

As mentioned in Grep’s good rep, for project-wide searches C-x p g is my go-to key binding. However, there are situations when I want to limit the search to specific paths, and that’s where I prefer using mu-recursive-grep.

A closing remark: before blindly leaving grep, ripgrep, or even vc-git-grep behind, I suggest to benchmark the performance of each tool and see what actually suits you best. You may find that whatever you are using at the moment is already the best choice.

See 54608#14 and 54608#20. ↩︎

Restart Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 18 Apr 2022 00:00:00 +0000

Tracking Emacs development is always nice, because I get to explore new things as soon as they are made available. Yesterday Lars Ingebrigtsen introduced a new command: restart-emacs.

Let’s C-h f restart-emacs RET to check what we are dealing with:

Kill the current Emacs process and start a new one. This goes through the same shutdown procedure as ‘save-buffers-kill-emacs’, but instead of killing Emacs and exiting, it re-executes Emacs (using the same command line arguments as the running Emacs).

It sounds useful, doesn’t it? So I quickly devised a new command to let me decide whether I want to quit Emacs or re-launch it:

(defun mu-quit-or-restart (&optional restart)
  "Quit Emacs or restart it with RESTART."
  (interactive "P")
  (if restart
      (restart-emacs)
    (save-buffers-kill-terminal t)))
(keymap-global-set "C-x C-c" #'mu-quit-or-restart)

This little command should be obvious: C-x C-c does the usually killing, whereas C-u C-x C-c re-executes Emacs. This will come in handy when I upgrade packages, because I tend to restart Emacs after that and being able to do it quickly is a great thing indeed.

Note that keymap-global-set may not be available if you are not following the Emacs master branch. Rely on global-set-key in that case.

Eglot and Eclipse JDT for Java

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 16 Mar 2022 00:00:00 +0000

Last time I mentioned that I helped making it possible for Eglot to use jdtls, the Python helper script packaged with Eclipse JDT to start the language server with sane defaults. The only problem I had during my work on this is that jdtls requires Python 3.9 or later, why my Ubuntu 20.04 machine comes with the 3.8.10 version. Since changing the default Python on Ubuntu can bring pain,¹ I decided to have Emacs work with Python 3.9 only for my Java projects.

First, I installed the required Python packages:

$ sudo apt install python3.9 python3-9-venv

Then, in my Java project root directory I ran:

$ python3.9 -m venv env

Finally, I had to tell Emacs how to interact with this new Python environment. In the root directory of my project I added a .dir-locals.el file with the following content:

((nil . ((buffer-env-command . ">&2 . \"$0\" && env -0")
         (buffer-env-script-name . "env/bin/activate")
         (python-shell-virtualenv-root . "./env"))))

I am using Augusto Stoffel’s buffer-env to pick up the activate script and run it automatically for me. Checking the Python version with M-! /usr/bin/env python3 -V RET told me I was doing the right thing. Keep in mind that you don’t have to set buffer-env-command like I do. Here I am setting it back to its default value because I changed it in my init.el to specifically deal with direnv. Anyway, with everything in place Eglot correctly interfaced with jdtls for a smooth Java developing experience.

A note to myself: I will probably need to revisit this setup as soon as I move to the new Ubuntu LTS which, I guess, will provide a more recent Python by default.

Trust me on this. ↩︎

Eglot and digestif for LaTeX

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 12 Mar 2022 00:00:00 +0000

I don’t think I have enough words to express my admiration for Eglot. The more I use it, the more I appreciate its minimalist approach that just does the right thing and then gets out of my way. With the help of its maintainer João Távora and the friendly Felicián Németh, I have done my part to help keeping it up to speed with Eclipse JDT latest developments. I had to give back something, didn’t I?

Why stop at Java, though? Since I have come to enjoy the niceties of LSP, I decided to push it a little further and step outside my comfortable software developer zone to check how Eglot can improve on my experience with LaTeX. Albeit a bit early in my student’s career, I have followed a kind professor’s prompt to pursue some ideas of mine and have started working on my thesis. Mind you, I have been a happy AUCTeX user for quite a long time and I do not intend to leave it behind. How can Eglot fit in, then?¹

The “don’t be silly, trust Emacs!” answer comes from Augusto Stoffel in the form of digestif. If you are familiar with a language server, you know what digestif does. I like to think of it as AUCTeX missing piece, because it offers completion, documentation, and navigation commands that really make a difference when writing a non-trivial LaTeX document. Furthermore, Augusto has recently added specific integration for BibLaTeX, which turns inserting citation and footnotes into a nice and easy task and it also means that I can safely disable RefTeX now.

Installing digestif is just as painless as well: put the self-installing script in your $PATH, make it executable, and run it once. Or you can use luarocks install digestif if you have luarocks on your machine. Back in Emacs, Eglot will take care of everything else. Try M-x eglot in your LaTeX buffers if you don’t believe me.

When I first heard of LSP I wasn’t sure of what to do with it. Well, to a certain degree I still am. For instance, I am not using clojure-lsp even though I spend eight hours a day with Clojure. However, when it comes to LaTeX I don’t think I am going to abandon Eglot and digestif any time soon. Whether or not you use AUCTeX, with digestif the experience is simply more comfortable and, thus, better.

Most Emacs users would suggest Org instead of plain LaTeX here, but I just enjoy writing LaTeX in the old fashioned way. ↩︎

Ignore project buffers

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 27 Feb 2022 00:00:00 +0000

As you may already know, I take buffer switching seriously. Jokes aside, one of the key bindings I use the most is C-x p b, which is bound to project-switch-to-buffer by default. As the above linked article explains, it takes little time to find myself with many open buffers, some of which may not be immediately relevant to the context of my actual work.

Instead of tweaking switch-to-buffer, though, I decided to make it possible for project-switch-to-buffer to act according to certain conditions. With the help of Dmitry Gutov, I have recently added project-ignore-buffer-conditions on Emacs master. Now, for instance, I can do the following:

(defvar-local mu-ignored-buffers
    '("\\` " "^\\*Async" "^\\*Completions" "^\\*Flymake" "^\\*Help"
      "^\\*Messages" "^\\*eldoc" "^\\*envrc" "\\*tramp" "^\\*xref")
  "A list of predicates for buffers to ignore.")
  
(defun mu-project-ignore-buffer-p (buffer)
  "Check if BUFFER is a member of `mu-ignored-buffers'."
  (seq-contains-p mu-ignored-buffers (buffer-name buffer) #'string-match-p)) 
  
(setq-default project-ignore-buffer-conditions '(mu-project-ignore-buffer-p
                                                 (derived-mode . comint-mode))

Note that I changed project--read-project-buffer to take the new defcustom into account, so project-display-buffer and project-display-buffer-other-frame are also affected.

Futhermore, to understand what kind of conditions you can use, check project-kill-buffer-conditions which is what I based project-ignore-buffer-conditions on following Dmitry’s tip.

Handling wildcards in paths

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 20 Jan 2022 00:00:00 +0000

My recent experiments with Eglot and Java led me to figure out how to speed up the connection to Eclipse JDT Language Server. Basically I wanted a simpler version of eglot--eclipse-jdt-contact to avoid any prompt and just do the right thing for me.

Looking at Eglot’s bug tracker, there is an issue with some tips: #424. I followed the instructions and added the relevant code to my init.el:

(with-eval-after-load 'eglot
  (defconst mu-jdt-launcher
    (concat "/home/manuel/jdt/plugins"
            "/org.eclipse.equinox.launcher_1.6.400.v20210924-0641.jar"))

  (defun mu-eglot-jdt-contact (_interactive)
    "See `eglot--eclipse-jdt-contact'."
    (let ((cp (or (getenv "CLASSPATH") path-separator)))
      (setenv "CLASSPATH" (concat cp path-separator mu-jdt-launcher))
      (unwind-protect (eglot--eclipse-jdt-contact nil)
        (setenv "CLASSPATH" cp))))
  (setcdr (assq 'java-mode eglot-server-programs) #'mu-eglot-jdt-contact))

However, I do not like the hard-coded path to the JDT jar file, mainly because I have to manually update it every time I install a new version of the language server. Fortunately, Emacs has what I need right under the hood: file-expand-wildcards.

(defconst mu-jdt-launcher
  (let ((path "~/jdt/plugins/org.eclipse.equinox.launcher_*"))
    (car (file-expand-wildcards path 'full))))

If you check the documentation of file-expand-wildcards you will notice that it returns a list of file names matching the given pattern. In this case, there is only one element in that list, so car can safely grab it. Again, the documentation will also explain the meaning of that 'full argument, but I am sure it is pretty clear already.

Completing shell commands

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 10 Dec 2021 00:00:00 +0000

The more I move to VC,¹ the more I end up relying on M-! (shell-command). Admittedly, this is a tool I’ve hardly ever used before, but since VC lacks many features covered by Magit, sometimes I need to interact with the power of Git straight from the command line.

One of the best things about Magit is that I don’t have to remember the many Git options to use it every day. Through transient menus, Magit makes Git a matter of few key strokes. On the other hand, from time to time I find myself on remote machines where Magit is not available, so it does not hurt to have a better understanding of the basic Git operations at my disposal.

However, typing them all out every single time is not the kind of pleasant activity a lazy Emacs user enjoys. Juri Linkov shared this little trick on emacs-devel:

(defun mu-minibuffer-complete-history ()
  "Complete minibuffer history."
  (interactive)
  (completion-in-region (minibuffer--completion-prompt-end) (point-max)
                        (symbol-value minibuffer-history-variable)
                        nil))

Juri also suggested to bind it to C-TAB in minibuffer-local-map which, coincidentally, is the same key binding I have to manually complete with Company outside of the minibuffer.

What Juri’s code does is popping up a *Completions* buffer with the history of the commands used in the minibuffer. I only use it with shell-command, but try it with C-x C-f for fun.

I leave it as a small exercise for the reader to understand how to switch from the minibuffer to the *Completions* buffer and vice versa. Tip: C-h m is your friend.

See A job for VC and Rebasing with VC. ↩︎

Rebasing with VC

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 05 Dec 2021 00:00:00 +0000

Two weeks without Magit¹ have forced me to rethink how I use Git in my projects. I have already written about some commands I have been using, but beside basic things, how does Emacs hold up in a more complex situation?

Let’s talk about interactive rebasing. If you are familiar with Magit,² you know how simple it gets. This is what I usually do from magit-status:

l for magit-log
l for current
n as many times as needed to move to the commit I want to start rebasing with
r for magit-rebase
i for interactive
s on the commits I want to squash
C-c C-c to confirm
write the commit message I want
C-c C-c to confirm
P and -f to push with --force-with-lease enabled

It’s quicker to do it than to write it all down, especially now that it has become muscle memory. No wonder I was still relying on Magit to interactively rebase on my first days with VC.

Since I did not find a similar solution in vc-git, I asked on emacs-devel how the core developers approach this workflow. I got different, interesting replies that can be roughly summed up with:

bare command line
helm-ls-git
custom code

Not wanting to be scared away from a non-Magit option, this is what I have eventually ended up doing:

in shell-mode, I run git rebase -i <branch>~<commits>
in the buffer that opens up I type s on the commits I want to squash
C-x C-s
C-x k RET
in the buffer with the commit message I edit the text as I wish
C-x C-s
C-x k RET
either I run git push --force-with-lease from shell-mode, or C-u P from C-x p v to push with --force-with-lease added manually

Note that this approach requires that in ~/.config/git/config I have editor set to emacsclient and either I have server-start somewhere in my init.el or I do M-x server-start before starting the actual rebasing.

It looks like that even without Magit I can do everything from Emacs, which makes for a good alternative in my opinion. Nonetheless, it does not take a PhD to notice that Magit makes the whole rebasing easier to sort out. Hence, you will not hear me scream “drop it already and party hard, fellas!”. Sorry.

Not entirely true, but keep reading. ↩︎
Who isn’t in this day and age? ↩︎

Stashing with VC

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 29 Nov 2021 00:00:00 +0000

Following my previous article on VC, I felt like proposing a key binding for vc-git-stash to the Emacs developers was something that could turn out to be useful for other VC users.

As it is usually recommended to do in these cases,¹ I filed my request using M-x report-emacs-bug: #52158. You can see that I specifically mentioned mu-vc-git-stash, the thin wrapper I coded to have VC stashing commands easily reachable, in order to back my proposal with the custom code I used to scratch a tiny itch.

Lars Ingebrigtsen, one of the Emacs co-maintainers, replied to me quickly² suggesting that I can use C if I put my cursor on the Stash: line of the vc-dir buffer. That led me to discover that if I move the cursor onto a line pointing to a stash I can press P to pop it with vc-git-stash-pop-at-point. The outcome should be obvious: I can get rid of mu-vc-git-stash.

Why wasn’t I using these key bindings before? As I wrote on the bug tracker, C-h m in vc-dir buffers does not document them and I did not find them explained in the 28.1.10.2 VC Directory Commands section of the manual either. If the documentation is not added, I may get in touch with the Emacs maintainers to see if I can contribute it myself. Unless of course the documentation is already there and it’s just my reading and searching skills failing me.

I was once advised to use this approach on emacs-devel. ↩︎
This is something Emacs core developers do all the time and I don’t think it’s appreciated enough. They always reply to my questions, even the ones that on second thoughts I consider silly. ↩︎

A job for VC

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 27 Nov 2021 00:00:00 +0000

Some days ago I briefly wrote about my willingness to give Emacs built-in VC system a try for real. For real means that it’s easy to praise the beauties of vc-git when working on personal projects such as this blog, but is VC actually worth it on bigger projects where different people commit and push regularly, rebasing is a habit, and merge conflicts are unavoidable necessities?

A warning first. This article is not intended as a VC tutorial. It aims to be an example of how I use it or, to phrase it better, how I started to use it. As Mickey Petersen suggests in the “Exploring Emacs” section of his great Mastering Emacs book, if you want to know more about VC there is plenty of information right within our favourite text editor. Furthermore, Protesilaos Stavrou has a couple of nice videos on VC you might want to check out: Introduction to VC and Workflow with VC for Git.

Now, let’s break down a common workflow of mine:

A new ticket is assigned to me
I create a new branch for this ticket, starting from the master one
I code my thing
I commit and push my code
I file a new merge request ready to be reviewed
The review may require changes to my code
I may need to rebase my changes onto master because other developers have merged their branches before me
Merge conflicts may arise and need to be fixed
I push my updated code ready to be reviewed again
If everything’s fine I merge my changes, otherwise back to my edit/rebase/merge process until it’s properly done
Meanwhile, it may happen that I need to stash my changes and quickly fix a higher priority bug

This more or less happens on a daily basis, so the interaction with Git (the only VCS I have used in the last ten years) must be smooth. On the other hand, Git-wise the above workflow is not that complicated. For instance, I rarely use features such as cherry-picking or bisecting.

On the surface, the main difference between Magit and VC is transient. Magit transient menus make all the operations I described above¹ a breeze. From checking out a branch to interactive rebasing, Magit requires few key strokes to accommodate my needs. The blatant truth is that Magit wraps everything I want from Git and much more in a user interface that just works.

VC, however, is not tightly coupled to Git, so it does not cover all of its many options. And yet I was able to manage my work projects with VC alternatives to Magit commands.

VC has its own vc-git-stash, vc-git-stash-pop, and vc-git-stash-delete commands, but instead of calling them via M-x I devised mu-vc-git-stash and bound it to z in vc-dir-mode-map:

(defun mu-vc-git-stash (pop-or-delete)
  "Create, pop, or delete Git stashes.
With no POP-OR-DELETE call `vc-git-stash'. With one prefix
argument call `vc-git-stash-pop'. With two prefix arguments call
`vc-git-stash-delete'."
  (interactive "P" vc-dir-mode)
  (cond ((= (prefix-numeric-value pop-or-delete) 4)
         (call-interactively #'vc-git-stash-pop))
        ((= (prefix-numeric-value pop-or-delete) 16)
         (call-interactively #'vc-git-stash-delete))
        (t (call-interactively #'vc-git-stash))))

As you can see, C-u z issues vc-git-stash-pop while C-u C-u z runs vc-git-stash-delete.

One thing that Magit really shines at for me is interactive rebasing (r i). I haven’t had the opportunity so far to check how I can handle this with VC. I guess a combination of shell-command and something I have yet to discover would do, probably.

Anyway, I’ll keep using VC in the next days and report back if I manage to adapt more of my Git workflows to it. I suspect Magit will outshine the humbler Emacs built-in eventually, but who knows. Reading on the emacs-devel mailing list that some wild Emacs developers prefer VC to Magit seems to confirm that the world is still full of surprises.

Well, only the ones related to Git of course. ↩︎

On Eglot and VC

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 21 Nov 2021 00:00:00 +0000

I have been pretty busy since my last update here, but that does not mean I haven’t had the time to explore a couple of things for my everyday Emacs usage.

Lately I had to deal with some Java and some JavaScript. No fancy libraries on top of them, no languages built upon them, just plain, old Java and JavaScript. I took that as a chance to familiarize myself with LSP and especially with Eglot, one of the two (to my knowledge) packages that add LSP support to Emacs. Why Eglot and not lsp-mode? Easy: I like how Eglot leverages project.el and Flymake, tools I heavily rely on, and I also like how quickly it enabled me to type Java and JavaScript code. I mean, it’s just a matter of M-x eglot. It does not get any easier than that, if you ask me.

Eglot works well with Company, Xref, and ElDoc, so coding in Java finally makes sense in Emacs. Granted, I haven’t used it on a big project and I am sure the likes of IntelliJ IDEA and Eclipse do wonders, but none of them has the editing capabilities or the openness to infinite customization that Emacs offers.

Another tool that entered my day-to-day computing is the built-in version-control system, or VC for short. My love for Magit is well-known, but on my way to a vanilla Emacs appreciation I thought I could give VC a try. It turns out most of the things I need to do with my Git-versioned projects can be done from vc-dir. This means that instead of C-x g for magit-status I have been using C-x p v for project-vc-dir. When it’s time to get my hands dirty with some advanced Git-fu, Magit is always next to me.

One thing should be obvious here: Magit is more powerful and feature rich than the built-in VC, so I do not intend to drop Magit as quickly I dropped Projectile and Flycheck. Why don’t I just use Magit, then, you ask. For the same reason I tried Eglot instead of installing Eclipse, I’d reply. Curiosity will not kill any cat in my house.

Grep’s good rep

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 10 Sep 2021 00:00:00 +0000

Look around this blog and you will find nice words about ripgrep. I especially enjoy how I can plug it into Emacs, like the time when I devised my own Helm commands for it.

However, roughly a year ago I started my journey to a more vanilla Emacs experience. During this time I have been slowly moving away from the niceties of ripgrep in order to stick to a couple of built-in tools: rgrep and vc-git-grep. Now, technically speaking, both this commands rely on external tools, grep and git grep. Why should I use these instead of ripgrep? Personal preferences, of course: grep is readily available on Ubuntu and git is the first tool I install when upgrading to a new LTS from Canonical.¹

Furthermore, I rarely need the power of ripgrep. Your experience may be different on this, but the size of my projects does not scare neither grep nor git grep. For instance, I regularly use vc-git-grep on Emacs sources, which amounts to something like 2,755,361 lines of code,² and the performances are just fine for me.

The only thing I usually do not need from these commands is the prompt for the file types to look into.

(defun mu-recursive-grep (search-term search-path)
  "Recursively search for SEARCH-TERM in SEARCH-PATH."
  (interactive
   (progn
     (unless grep-command
       (grep-compute-defaults))
     (let ((search-term (grep-read-regexp))
           (search-path (expand-file-name
                         (read-directory-name
                          "Directory: " nil default-directory t))))
       (list search-term search-path))))
  (if (vc-root-dir)
      (vc-git-grep search-term "*" search-path)
    (rgrep search-term "*" search-path)))

I combined the two commands to make it simpler. When I am in a Git-versioned project (i.e., vc-root-dir is not nil) mu-recursive-grep runs vc-git-grep; otherwise, it’s time for rgrep to shine. As trivial as it might look, the fact that the last two lines of mu-recursive-grep look similar is what made it easier for me to devise a common wrapper. Emacs describe system is always invaluable for discoveries such as this.

One last thing. When in a project, if I want to find where the thing at point is used I do not need mu-recursive-grep. For this task project-find-regexp (C-x p g) is enough,³ but mu-recursive-grep is still helpful when I want to narrow the search down to a specific path.

I use Ansible Playbooks to set up the new system. ↩︎
That’s what scc tells me today, anyway. ↩︎
C-h v xref-search-program shows that ripgrep can be used instead of the default grep. Hence you can keep ripgrepping if that’s what you prefer. ↩︎

Package report

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 01 Sep 2021 00:00:00 +0000

I don’t know about you, but I like to monitor my Emacs configuration to see if it is growing out of control due to my penchant for experimenting with ELisp and new packages. This led me to a simple question: why not have a command that can produce a summary of the installed packages? Specifically, I want to know the total number of packages installed and I’d like to list the packages for every archive set up in package-archives.

(defun mu-package-report ()
  "Report total package counts grouped by archive."
  (interactive)
  (package-refresh-contents)
  (mu--display-package-report
   (let* ((arch-pkgs (mu--archive-packages))
          (counts (seq-sort-by #'cdr #'> (mu--archive-counts arch-pkgs)))
          (by-arch (seq-group-by #'car arch-pkgs)))
     (concat
      (format "Total packages: %s\n\n" (apply #'+ (mapcar #'cdr counts)))
      (mapconcat
       (lambda (archive)
         (concat "• "
                 (format "%s (%s)" (car archive) (cdr archive))
                 ": "
                 (mapconcat (lambda (ap-pair) (cdr ap-pair))
                            (alist-get (car archive) by-arch)
                            ", ")))
       counts
       "\n\n")))))

Now, let’s unpack it.

I want my report buffer to be displayed in a new window, so this is what mu--display-package-report does:

(defun mu--display-package-report (output)
  "Display OUTPUT in a popup buffer."
  (let ((buffer-name "*package-report*"))
    (with-help-window buffer-name
      (with-current-buffer buffer-name
        (visual-line-mode 1)
        (erase-buffer)
        (insert output)
        (goto-char (point-min))))))

Next, I want to know from which archive (e.g., GNU ELPA) a package is coming to my system:

(defun mu--archive-packages ()
  "Return a list of (archive . package) cons cells."
  (seq-reduce
   (lambda (res package)
     (let ((archive (package-desc-archive
                     (cadr (assq package package-archive-contents))))
           (pkg (symbol-name package)))
       (push (cons archive pkg) res)))
   (mapcar #'car package-alist)
   nil))

This is nice because now I can also have the number of packages for every archive.

(defun mu--archive-counts (arch-pkgs)
  "Return a list of cons cells from alist ARCH-PKGS.
The cars are package archives, the cdrs are the number of
packages installed from each archive."
  (seq-reduce
   (lambda (counts key)
     (cons (cons key (+ 1 (or (cdr (assoc key counts)) 0)))
           (assoc-delete-all key counts)))
   (mapcar #'car arch-pkgs)
   nil))

The rest of the code in mu-package-report deals with formatting the output. For example, I am using seq-sort-by to have the archive with the highest number of packages on top. As for the mapconcat producing the actual bullet points, the Emacs community came to the rescue on Emacs Stack Exchange.

Finally, this is how M-x mu-package-report RET looks like:

Switching buffers (Take 3)

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 14 Aug 2021 00:00:00 +0000

The more I remove code from my init.el to rely on Emacs defaults, the more I am getting used to it. This means I stopped using the likes of nswbuff and counsel-projectile, but it doesn’t mean there isn’t room for small tweaks.

The basic switch-to-buffer (C-x b) does exactly what it says: it lets you switch to a buffer of your choice. Now, if you play around in Emacs for a while you end up with many open buffers such as *Messages*, *Flymake log*, *Help*, *Ibuffer*, etc. Usually when I want to switch to a buffer I start typing and fido-mode gets me there, but the output of vanilla switch-to-buffer is still a bit cluttered with buffers I never jump to.

(defvar mu-ignored-buffers
  '("\\` " "^\\*Async" "^\\*Compile-Log" "^\\*Completions" "^\\*Flymake"
    "^\\*Messages" "^\\*eldoc" "^\\*envrc" "\\*tramp" "^\\*xref")
  "A list of predicates for buffers to ignore.")
  
(defun mu-switch-to-buffer (buffer-or-name)
  "Switch to BUFFER-OR-NAME but ignore specific buffers."
  (interactive
   (list (read-buffer "Switch to: "
                      (other-buffer (current-buffer))
                      (confirm-nonexistent-file-or-buffer)
                      (lambda (buf)
                        (not
                         (seq-contains-p
                          mu-ignored-buffers (car buf) #'string-match-p))))))
  (switch-to-buffer buffer-or-name))

The key point in mu-switch-to-buffer is the fourth argument passed to read-buffer.

Optional arg PREDICATE, if non-nil, is a function limiting the buffers that can be considered. It will be called with each potential candidate, in the form of either a string or a cons cell whose `car’ is a string, and should return non-nil to accept the candidate for completion, nil otherwise.

Note that I am using mu-ignored-buffers only in mu-switch-to-buffer. Ibuffer still shows the ignored buffers to me. If I’ll ever get particularly angry at those buffers, I could hide them in Ibuffer as well by adding them to ibuffer-never-show-predicates. These days, though, teenage angst is far behind myself.

Trust me, I complete

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 06 Aug 2021 00:00:00 +0000

Not too long ago I wrote about my pleasant experience with icomplete-vertical-mode, a recent addition on Emacs master which gives a vertical spin to the good old Icomplete. But now Emacs also comes with fido-mode, which enhances icomplete-mode with ido-mode powers.

The question is: can I combine fido-mode and icomplete-vertical-mode to have the best of both worlds? Yep, it turns out I can and it is simple and easy.

(fido-vertical-mode 1)

And this is basically it. The only other thing I did was setting icomplete-matches-format to nil because I don’t have a particular need for the match count at the prompt.

Whether or not one uses fido-vertical-mode, fido-mode enables nice features such as icomplete-fido-delete-char (C-d), which deletes the current character or calls dired on the current directory, and icomplete-fido-kill (C-k), which kills the current line or, for instance, if we are completing files asks if we want to delete the selected one. Check icomplete-fido-mode-map for more details on the available key bindings.

Inspecting icomplete--fido-mode-setup reveals that fido-mode also uses the flex completion style,¹ but nothing forces us to stick with it or try something like Orderless instead. As always with Emacs, the power is in our hands.

One more thing. The “Trust me” in the title aims to be a pun on the word “fido”. In Italian “fido” is the form for “I” of “fidare” which means “to trust”: “Mi fido di te” becomes “I trust you” in English. “Fido” is also a famous dog in Italy that came to public attention because of his strong loyalty. Thus using fido-mode implies that my love for dogs is sincere and trustworthy.

C-h o completion-styles-alist RET to know more about it. Specifically, search for flex in the Value: section of the documentation. ↩︎

A dictionary in Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 31 Jul 2021 00:00:00 +0000

I explained my need for an English dictionary when I wrote about my own [helm-wordnut]({% post_url 2020-06-13-helm-wordnut %}). To sum it up: my English is good but it’s not David Foster Wallace good, so a dictionary is mandatory.

Last October Torsten Hilbrich added dictionary-el to Emacs master so, in my quest for a Vanilla Emacs appreciation, I decided to give it a try. According to the first line of dictionary.el this library is a client for RFC 2229 dictionary servers, which as the RFC says, rely on the DICT protocol:

The DICT protocol is designed to provide access to multiple databases. Word definitions can be requested, the word index can be searched (using an easily extended set of algorithms), information about the server can be provided (e.g., which index search strategies are supported, or which databases are available), and information about a database can be provided (e.g., copyright, citation, or distribution information). Further, the DICT protocol has hooks that can be used to restrict access to some or all of the databases.

This is very useful because it means that one can collect different definitions from various dictionary and possibly compare synonyms.

This is how I set up dictionary.el in my init.el:

(global-set-key (kbd "C-c d") #'dictionary-search)
(setq dictionary-server "dict.org")

dictionary-search cleverly picks up the word at point which means that when I hit C-c d RET on a word I don’t know I get a *Dictionary* buffer with entries coming from:

The Collaborative International Dictionary of English
WordNet
Moby Thesaurus II

There is much more in dictionary.el, though. I counted 17 defcustoms for starters, so go on and tweak it like any Emacs hacker would do. As for me, the couple of ELisp lines above are adequate.

Reuse Dired buffers

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 14 Jul 2021 00:00:00 +0000

This is going to be a real quick one, mainly a “thank you!” to Lars Ingebrigtsen. Lars has recently added a new option on the Emacs master branch: dired-kill-when-opening-new-dired-buffer. I will let the documentation speak for itself:

dired-kill-when-opening-new-dired-buffer is a variable defined in ‘dired.el'.

Its value is t
Original value was nil

You can customize this variable. This variable was introduced, or its default value was changed, in version 28.1 of Emacs. Probably introduced at or before Emacs version 28.1.

If non-nil, kill the current buffer when selecting a new directory.

Setting this new option to t means that pressing RET or ^ in a Dired buffer will reuse the existing buffer. This is something I required a while ago (#20598) and that up until today I had been hacking up poorly in my .init.el.

I know the Emacs developers have more urgent bugs to work on, but this is such a nice improvement I am pretty sure you can see me happily smiling right now.

I complete. You?

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 24 Jun 2021 00:00:00 +0000

Tracking the Emacs development by building its master branch may not be a smooth experience for everyone, but for the average enthusiast is the perfect way to see their favourite tool evolve, trying experimental things, and reporting back to the core developers to help them. Sure, one has to deal with occasional build failures, but with Git at one’s service it’s always easy to reset to a working commit and find happiness again.

Recently a shiny new mode has been implemented on master: icomplete-vertical-mode. Now, if you had the chance to read this blog in the past you know that when it comes to candidate completion I am a gangsta jumping back and forth among packages with excessive self-satisfaction. But you should also already know that I like to use as many Emacs built-ins as possible. Hence, I could not wait to give icomplete-vertical-mode a try.

Turning it on is trivial:

(icomplete-mode 1)
(add-hook 'icomplete-mode-hook #'icomplete-vertical-mode)

Since other completion systems have spoiled me, I prefer scrolling over the rotating behaviour of the standard icomplete:

(setq icomplete-scroll t)

Furthermore, I always want to see the candidate list:

(setq icomplete-show-matches-on-no-input t)

This is pretty much it. I use icomplete-fido-backward-updir to move up one directory and I have exit-minibuffer bound to C-j for convenience.

I have been using icomplete-vertical-mode daily for a while now and everything has been working as expected. For the record, this mode works seamlessly with your favourite completion-styles settings, so moving from, say, Vertico to icomplete-vertical-mode is simple and easy.

Would Alfred Hitchcock use Emacs?

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 12 Apr 2021 00:00:00 +0000

First you have to excuse the awful title, but a cinephile cannot resist the temptation of an easy reference when the Emacs package he is going to write about is called Vertico.

Daniel Mendler has become such a prolific contributor to our Emacs world. His work with Omar Antolín Camarena and Clemens Radermacher (to name a few!) has been showing me how much can be done with little improvements on Emacs default completion system. Actually, “little” is a bit unfair to them because they have been putting a lot of effort in their packages and contributions. What “little” stands for instead is the amount of code I had to add to my init.el to get a superb completion UI. I combine Vertico with Orderless and I didn’t have to do much beside this after the installation via package.el:

(require 'orderless)
(setq completion-styles '(orderless))

(require 'vertico)
(vertico-mode 1)

Well, to be fair I did something more, like binding vertico-exit-input to C-j and setting orderless-matching-styles to orderless-regexp, plus I am using Daniel’s consult to extend Vertico capabilities, but I guess you see where I am going by now. The combination of small packages makes for a modular system that I can interact with more easily. For instance, Daniel can go berserk and forget about the lovely 500 lines of code limit he set himself to with Vertico. Why should I trust this criminal mind, then? I can switch to Selectrum and keep using Consult and Orderless with it.¹

The beauty of Vertico is that it is not about reinventing Emacs completion once again. By sticking to Emacs built-in commands and completion facilities, Vertico succeeds in staying close to the source without losing the chance to improve on it. On the one hand, moving to Vertico means it is up to the user to configure extra niceties. That is what packages like Consult, Orderless, Embark, and Marginalia aim for, but again, the user is in charge of the right setup for their needs, while a solution such as Helm offers a lot of functionalities out of the box. On the other hand, tools such as Helm, Ivy, and Selectrum are more complex than Vertico and may bring in code you do not necessarily need, which is something even Emacs itself doesn’t shy away from.²

I find it amazing that a seemingly simple and yet so central feature in my everyday Emacs such as the completion system has pushed people to create all these amazing packages. It seems to me that Helm has helped pave the way for a more powerful experience when it comes to completion and that by studying Emacs internals carefully one can achieve similar benefits with a different approach. As humble end-users of all this we really are a lucky bunch.

The irony should be obvious. ↩︎
I don’t really need games in my text editor. ↩︎

Back to the roots

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 08 Apr 2021 00:00:00 +0000

Last time I left straight for the built-in package.el, a choice I have not had the pleasure to regret so far. Now I am going to reason about a more ambitious change in my Emacs configuration: I am not using use-package any more.

Before answering your concerned why!? let me just say that if you are happy with use-package you should stay with it. By wrapping all the settings for a built-in feature or an external package with use-package you can easily notice what you are doing wrong when tweaking something, while having control over the installation and the loading of your favourite library as well. Despite some unhappiness around the web,¹ use-package is just a great tool that any serious Emacs hacker should consider when digging deep into their .emacs.d.

As for my choice to move away from it, it all started as an experiment. I wanted to see if I could have the same amount of control and readability over my init.el without an extra package. You see, most of the recent changes to my setup involved trying to rely on Emacs own facilities to answer my needs, and I am glad to say vanilla Emacs has been really a surprise in this regard. My liaisons with project.el and Flymake are nice examples of this.

Removing use-package has meant rethinking the way I install packages, especially if I want my setup to be ready to go any time I upgrade to a newer version of Ubuntu. My solution was adding the packages I use to package-selected-packages and have a check on startup to make sure they are installed. This works very well combined with package-autoremove: if a package is not listed under package-selected-packages, Emacs takes care of the mess.

All the use-package blocks have been replaced with a combination of with-eval-after-load, define-key, and add-hook, which was not as complicated as it might sound, and more often than not was similar to what I had in my days before the use-package takeover. True, I lost the nice readability of use-package with this massive edit. For example, its keywords have the benefit of grouping settings together and clearly indicate when a new group starts, but on the other hand now there is less macro-magic masking package-related operations. As a result I have a more detailed insight of what is really going on with my Emacs Lisp. For instance, I have gained a better knowledge of what run-with-idle-timer actually does.

Again, it is a matter of personal preferences. By now the beauty of use-package is well-known in the Emacs world and all the praises are well-deserved. Let me stress it again: use-package makes your configuration simpler to manage and easier to read. Those were the main reasons I switched to it years ago, anyway.

However, if you know what you are doing you can achieve a clean and pleasant init.el with what Emacs already offers. Does it take more effort? Yes, it probably does. Is it really worth it? It’s up to you, mate. Am I just showing off? No, come on, don’t be rude.

See for instance here or here. ↩︎

Quick starting is a bendy road

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 08 Mar 2021 00:00:00 +0000

After more than a year with straight as my package manager, recently I have decided to sit down and look closely at how I handle my Emacs packages.

For all the interesting design choices and splendid documentation straight offers, I have never used neither its version freezing capabilities nor the chances to edit the source code of a package to try possible fixes before sending patches upstream. Two reasons, mainly:

I update my packages on a daily basis, accepting the risk of breakages in order to signal them to the maintainers and offer some help;
when I want to send a patch, I have the source code of the package I am working on outside of my Emacs configuration to avoid leaving something messy around.

These are not issues with straight, of course. It all depends on what one needs from their package manager.

One of the major benefits that straight brought to my setup is a boost in startup speed. However, why don’t give package-quickstart a try? Setting package-quickstart to t instructs package.el to pre-compute an autoload file so that the activation of packages can be done much faster, resulting in a faster startup. And indeed it does, resulting in more or less the same 0.4 seconds that I was getting with straight.

One thing to be aware of is that, as the documention of package-quickstart suggests, “the use of ‘package-quickstart-refresh’ every time the activation need to be changed, such as when ‘package-load-list’ is modified” is required. Hence, I added an :after-while advice to package-menu-execute (bound to x in Package Menu) to make sure package-quickstart-refresh is run after every upgrade.

Again, mine is not an argument against straight. It’s still a great package manager and a fantastic alternative to the built-in package.el. However, these days my Emacs interactions do not need the fine-grained control straight provides.

Embarking in a new affair with completions

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 25 Dec 2020 00:00:00 +0000

What a year this 2020. Beside the pandemic changing our lives in unpredictable ways, from the perspective of my Emacs usage much was going on in my init.el until I felt that a temporary break was necessary.

Most of my tinkering concerned the minibuffer and its completion mechanisms. I finished last year and started this one with Helm, but I am about to close 2020 with the built-in minibuffer completion and Embark providing candidates. A solution that Protesilaos Stavrou explored and which has been really suiting me.

Before detailing how I adapted his approach to my preferences, though, let me give you a bit of rationale. First, Helm rocks and it rocks hard. Its power is evident after a couple of hours with it. I briefly used Icomplete tweaked to display its results vertically, but I didn’t find it responsive enough to stick with it. Then I found out about Selectrum, which fixed the responsiveness but eventually was not adding a significant difference compared to Helm. True, Selectrum has a simpler codebase, but were I only to look at my daily interactions with Emacs, only the user interface can tell Helm and Selectrum apart.

Protesilaos took a different path. He wants to understand the code in front of him, so the less changes the better. In this regard Helm, Selectrum, and even Icomplete add a layer of indirection between him and the minibuffer. He is right in this. The minibuffer is more capable than the plethora of completion frameworks may suggest, and one can leverage its strength without forcing it to behave in a totally new way. Protesilaos’ reasoning got me thinking. Once again, am I looking for a solution from the outside before having really understood what lies underneath my beloved text editor?

Following Protesilaos’ steps, I set up the minibuffer to rely only on orderless and Embark, with Consult chiming in for a some of operations like better history in shell-mode and an improved apropos. What I added to Protesilaos’ code is the only thing that I felt was missing: a command to search for the symbol at point in my project, with the results displayed in an embark-live-occur window in order to quickly jump to a specific entry. Over at the Consult’s GitHub there are talks about a consult-rg utility which would serves this purpose, and there has been suggestions of using project-find-regexp as well.

(defun mu-project-find-refs ()
  "Use `project-find-regexp' to search for thing at point."
  (interactive)
  (if-let (tap (thing-at-point 'symbol))
      (project-find-regexp tap)
    (message "Nothing at point to search for")))

Easy enough to understand. However, if you, like me, set up Embark like Protesilaos does you’ll notice that this command doesn’t show any candidate unless you type something at the Jump to definition prompt. The candidates are there already, though, so I have to avoid waiting for an input and display the candidate list immediately.

The solution is straightforward: just remove embark-live-occur-after-input from minibuffer-setup-hook and use embark-live-occur-after-delay instead. I added a :before advice on mu-project-find-refs for this. The beauty of this advice is that it works elsewhere as well. For instance, I have been using it for consult-flymake and flyspell-correct-at-point too.

Note that this advice requires a little change to the original minibuffer-setup-hook I have lifted from Protesilaos. Instead of adding embark-live-occur-after-input to it I am using this to ensure only embark-live-occur-after-input is present.

(defun mu-embark-live-occur-after-input ()
  "Ensure only `embark-live-occur-after-input' is active."
  (remove-hook 'minibuffer-setup-hook #'embark-live-occur-after-delay)
  (add-hook 'minibuffer-setup-hook #'embark-live-occur-after-input))

Without a dedicated completion framework the minibuffer may feel rather basic at first, but do not let it deceive you with its frugality. Like project.el, all it needs is love.

Restricting Flymake to my projects

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 21 Nov 2020 00:00:00 +0000

My recent move from Flycheck to Flymake has proven to be a solid choice because the Emacs built-in syntax checker has yet to let me down. And since by now I am sure my love for project.el is absolutely obvious, could I miss the opportunity to make these two underappreciated gems shine together?

Honestly, though, the credit here goes all to Protesilaos Stavrou. His Flymake setup made me aware of a neat way to limit the use of Flymake to the places I actually need it.

All I had to do was adapt it to my preferences:

(defun mu-flymake-mode-activate ()
  "Activate `flymake-mode' only in my projects."
  (project--ensure-read-project-list)
  (let ((known-projects (project-known-project-roots))
        (pr (or (locate-dominating-file "." ".git")
                default-directory)))
    (if (and (eq buffer-read-only nil)
             (member pr known-projects))
        (flymake-mode 1)
      (flymake-mode -1))))

I then hooked this little function to prog-mode-hook and text-mode-hook and everything was good to go.

Note that project.el must be required before running mu-flymake-mode-activate, otherwise Emacs will complain about project--ensure-read-project-list not being available.

Extending project.el

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 14 Nov 2020 00:00:00 +0000

In my first appreciation of project.el I wrote about a patch for project--files-in-directory. It’s a working solution, I won’t deny that, but patching code always feels hacky. It’s like a dirty workaround you cannot avoid to look at every time you visit your Emacs configuration.

By inspecting the code of project.el I noticed that project-files is a generic function. In Emacs Lisp parlance, a generic function specifies an abstract operation with the actual implementation provided by methods. This simply means that I can devise my own implementation of project-files.

(cl-defmethod project-root ((project (head local)))
  (cdr project))

(defun mu--project-files-in-directory (dir)
  "Use `fd' to list files in DIR."
  (let* ((default-directory dir)
         (localdir (file-local-name (expand-file-name dir)))
         (command (format "fd -t f -0 . %s" localdir)))
    (project--remote-file-names
     (sort (split-string (shell-command-to-string command) "\0" t)
           #'string<))))

(cl-defmethod project-files ((project (head local)) &optional dirs)
  "Override `project-files' to use `fd' in local projects."
  (mapcan #'mu--project-files-in-directory
          (or dirs (list (project-root project)))))

project.el has to be made aware of my local type now.

(defun mu-project-try-local (dir)
  "Determine if DIR is a non-Git project.
DIR must include a .project file to be considered a project."
  (let ((root (locate-dominating-file dir ".project")))
    (and root (cons 'local root))))

mu-project-try-local just needs to be added to project-find-functions to make sure my non-Git projects become known and remembered across sessions when I hit C-x p p. This is way more elegant than the previous patch.

Since I also never use Git submodules, I can push my extensions a little further.

(defun mu--backend (dir)
  "Check if DIR is under Git, otherwise return nil."
  (when (locate-dominating-file dir ".git")
    'Git))

(defun mu-project-try-vc (dir)
  "Determine if DIR is a project.
This is a thin variant of `project-try-vc':
- It takes only Git into consideration
- It does not check for submodules"
  (let* ((backend (mu--backend dir))
         (root
          (when (eq backend 'Git)
            (or (vc-file-getprop dir 'project-git-root)
                (let ((root (vc-call-backend backend 'root dir)))
                  (vc-file-setprop dir 'project-git-root root))))))
    (and root (cons 'vc root))))

mu-project-try-vc now replaces project-try-vc in project-find-functions.

Emacs and Emanuele Severino

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 24 Oct 2020 00:00:00 +0000

The recently available Emacs User Survey made me think, once again, about the status of the technological world around me. The survey was painstakingly discussed on the emacs-devel mailing list, and generated some interesting reactions among people outside the core developing team as well. More interesting for the perspective of this writing are the reactions to the discussions on emacs-devel, because they reveal how great the distance between me and some members of the Emacs community has been getting.

You see, I am a failed Free Software supporter. I stopped campaigning in its favour as soon as my wife’s school closed. There I had set up everything with Free and Open Source software, and watching the teachers effectively do their job with technological solutions they were not accustomed to made me happy. They did not really care about the reasons behind my choices, but they respected my contribution and were willing to overcome the first weeks of adaptation as long as I could guarantee a comfortable working environment. When all of this ended and I went back to software development, Free and Open Source software became only a private concern. While still set on Linux,¹ I left Debian for Ubuntu because I didn’t want to spend time tinkering with my operative system to get the best out of my Dell XPS. My distro-hopping days had come to an end. I just wanted a system that would let me code, write, and browse the Web. I chose the easy way.

However, I have never stopped paying attention to the world around me and behaving consciously. For instance, I hate wasting technology. The 3-and-a-half-year old Dell XPS where I am writing now replaced my 8-year old Dell Inspiron, and my 7-year old HP server is still rock-solid and here to stay. I have a 4-year old Fairphone, my first and only smartphone, that I intend to keep for as long as possible. Beside gadgets, I’ve been on a vegan diet for almost seven years and I consider it one of the best and most important choices I’ve ever made regarding the ethics of what I eat. Come to think of it, as bad as the Coronavirus crisis is turning out to be, it “fixed” the problem of getting to the office every day, cutting my car usage down to once a week for groceries² and thus decreasing my impact on the environment.

This is why mixing technocraticism with pragmatism bothers me. The words “pragmatic” and “pragmatism” have been kind of a constant in the IT world I live in since “The Pragmatic Programmer” passed on my shelves. As every word in every language, “pragmatic” and “pragmatism” are complex words and their actual meaning is not trivially describable. Immanuel Kant distinguishes between “practical” and “pragmatic”, but without asking him we can quickly see what the dictionary tells us. According to the Oxford Learner’s Dictionary, “pragmatic” means “solving problems in a practical and sensible way rather than by having fixed ideas or theories”. Treccani, however, is closer to how “pragmatic” is known nowadays: “what is being characterised by the prevailing of practical interests over theoretical ones and ideal values”. I won’t digress on the multiple meanings of “ideal” to keep it simple and because “values” is actually the key word for me here.

“Pragmatic” and “pragmatism”, in common parlance, imply a separation between theoretical thoughts and practical action, but it is actually impossible to draw a line between the two. Every action is informed by a thought and every thought shines a light on the action. We can act automatically without thinking about it, sure, but that has nothing to do with voluntary actions. When we act, we act according to a line of reasoning, and it’s that line of reasoning that determines the value of the action. Take my choice of using Ubuntu on this Dell XPS. A deliberate decision born out of my desire to prefer a comfortable option instead of spending time to value more Free Software-compliant solutions. I acted with a plan just as I acted with a plan when I chose my vegan diet. Which choice is more pragmatic? Which one tells you more about my ethics?

For years now I’ve been seeing the IT world as self-involved and rarely eager to discuss larger issues. Problems such as the environmental crisis become material for self-congratulatory speeches at conferences around the world, while in fact the day after the conference we resume our lives as if nothing other than ourselves mattered. We do that because, as Emanuele Severino says, we are scared of what is beyond ourselves. We have replaced religious myths with the myth of technology to find the immediate answers to deep and life-changing questions that we do not want to investigate any further.

It’s not easy to understand the weight of words like “pragmatism” and “pragmatic” in a technocratic world. We live in an age where we believe that technology is our ultimate saviour. We are driven to accept technology as it is because of the benefits it brings to ourselves. We trust our technology because not doing so would result in the effort of questioning it, which in turns may unveil the details that the technocratic world goes a long distance to hide. More importantly, questioning technology could disclose what we really are and need to be, something that takes will and courage to face. In a time like this, Emanuele Severino’s claim that technique is the dominant power of our time sounds as forceful as ever.

Yes, I didn’t write GNU/Linux. ↩︎
Yes, I am a bit of a recluse. ↩︎

Reliable REPL switching and buffer loading with CIDER

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 16 Oct 2020 00:00:00 +0000

As a Clojure developer one of the most important packages in my everyday Emacs usage is CIDER. There are many things to love about it, chief among them the great interactive code evaluation and a sweet integration with popular Clojure tools. I still haven’t played with its debugging facilities, but yes, I know I should.

However, there is something that has been bothering me for quite a while: REPL switching and buffer loading. I cannot pinpoint the exact moment when these seemingly simple operations have become so unreliable, but I still remember when switching to the correct REPL buffer according to the file in front of me used to work as expected and loading a buffer didn’t require dealing with sessions first.

Let me give you more details before this writing starts to look like a random rant. My projects are usually web applications, which means I have to write both Clojure and ClojureScript. The Clojure side can be backed by leiningen or a deps.edn file, and we are set on shadow-cljs for ClojureScript. The first thing I normally do is jack-in with C-c C-x j j and then bring up the dedicated ClojureScript REPL with C-c C-x j s. Opening the browser and navigate to something along the lines of localhost:3000 finalises the process of setting up the ClojureScript REPL. That’s it, another good day of coding can begin. And soon enough frustration follows.

I tend to move from Clojure to ClojureScript files and vice versa quite a lot, and hitting C-c C-z frequently results in an unpredictable behaviour. Sometimes the REPL of the expected type pops up, sometimes the other one appears, sometimes I get a message about a missing REPL in the current session. Manually linking the current buffer to the correct REPL with C-c C-s b seems to fix the problem, but it’s only a matter of time. It takes a couple of buffer switching operations to bring the issue back. It is as if the link between the buffer and the REPL has vanished. Even worse, without that link I can forget about C-c C-k to load the buffer.

To overcome my frustration, I sat back and looked at how exactly I interact with CIDER:

I only deal with one project at a time
I need at most two running REPLs
I don’t really care about firing up dedicated REPLs for other projects. If I change project, I simply close every buffer of the current one and start afresh

This made me realise that the whole CIDER session management is too much for my basic needs.

(defun mu--cider-repl-regex (type)
  "Return the regexp to get the CIDER REPL based on TYPE."
  (if (eq type 'clj)
      "\`*cider-repl .*clj[*]"
    "\`*cider-repl .*cljs"))

(defun mu--cider-repl-buffer-name (type)
  "Get buffer from `buffer-list' according to TYPE."
  (let ((regex (mu--cider-repl-regex type)))
    (car (seq-filter (lambda (s) (string-match-p regex s))
                     (mapcar #'buffer-name (buffer-list))))))

(defun mu-cider-switch-to-repl (&optional type)
  "Open a CIDER REPL for TYPE.
If TYPE is not passed, open a Clojure REPL."
  (interactive "P")
  (let ((type (or type 'clj)))
    (if-let (buffer (mu--cider-repl-buffer-name type))
        (pop-to-buffer buffer)
      (message "No CIDER REPL available"))))

(defun mu-cider-switch-to-cljs-repl ()
  "Open a CIDER REPL for ClojureScript."
  (interactive)
  (mu-cider-switch-to-repl 'cljs))

Note that I changed the value of nrepl-repl-buffer-name-template to *cider-repl %j %r:%S*, so you may have to change mu--cider-repl-regex according to the value in your setup.

C-c C-z is bound to mu-cider-switch-to-repl in clojure-mode-map and clojurec-mode-map, and to mu-cider-switch-to-cljs-repl in clojurescript-mode-map. This of course means that in .cljc files I always get to a Clojure REPL, but that’s fine. The code in there has to be tested on both REPLs anyway, so it doesn’t matter which one comes up first.

Now, let’s fix C-c C-k as well.

(defun mu--cider-session-by-type (type)
  "Return the current CIDER session by TYPE."
  (let* ((regex (mu--cider-repl-regex type))
         (system (sesman--system))
         (sessions (sesman-current-sessions system '(buffer))))
    (car
     (seq-filter (lambda (s)
                   (string-match-p regex (buffer-name (cadr s))))
                 sessions))))

(defun mu--cider-load-buffer (session)
  "Load the current buffer according to SESSION."
  (if session
      (let ((system (sesman--system))
            (buf (current-buffer)))
        (sesman--clear-links)
        (sesman-link-session system session 'buffer buf)
        (cider-load-buffer buf))
    (message "No CIDER REPL available")))

(defun mu-cider-load-clj-buffer ()
  "Load the current Clojure buffer."
  (interactive)
  (mu--cider-load-buffer (mu--cider-session-by-type 'clj)))

(defun mu-cider-load-cljc-buffer ()
  "Load the current ClojureC buffer."
  (interactive)
  (let ((clj-session (mu--cider-session-by-type 'clj))
        (cljs-session (mu--cider-session-by-type 'cljs)))
    (if (and (null clj-session)
             (null cljs-session))
        (message "No CIDER REPL available")
      (when clj-session
        (mu--cider-load-buffer clj-session))
      (when cljs-session
        (mu--cider-load-buffer cljs-session)))))

(defun mu-cider-load-cljs-buffer ()
  "Load the current ClojureScript buffer."
  (interactive)
  (mu--cider-load-buffer (mu--cider-session-by-type 'cljs)))

Just like for C-c C-z, C-c C-k is now bound to these commands according to the mode map. For the sake of completeness, I have also disabled both C-c C-k and C-c C-z in cider-mode-map in order to avoid any kind of overshadowing by CIDER.

Note that this approach works well with my intended CIDER usage. It may not be what you are looking for if you are experiencing the same problems with REPL switching and buffer loading. Still, I have been using these commands for a while now and I am happy with them. CIDER has become my trusted Clojure IDE again.

We can fly with what we have

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 23 Sep 2020 00:00:00 +0000

There was a time when I just didn’t trust Emacs. This lack of confidence was the result of mixing good and evil: listening to other reliable Emacsers’ opinions while being too lazy to see for myself what Emacs could do. The outcome of this endeavour was a frenetic copying-and-pasting of code snippets in my init.el, blindly dragging in more and more external packages.

Don’t get me wrong, external packages made Emacs what it is today for me. I can’t even imagine using it without the likes of Magit or CIDER. However, ignoring what is already there and reaching for MELPA every time I have an itch to scratch has made me overlook built-in niceties like project.el.

Flymake did fell prey of this line of reasoning. Flycheck has always seemed like the way go, so much so that I have barely registered João Távora’s and other Emacs developers’ efforts to improve Flymake. Since my recent experiments with project.el have turned my eyes inwards again, I wanted to see if I can live without Flycheck.

There are three places where I need on-the-fly syntax checking:

Emacs Lisp package files with package-lint
Clojure files with clj-kondo
Markdown files with proselint

Kind people took care of Emacs Lisp and Clojure for me: package-lint-flymake comes with package-lint and flymake-kondor is a valid alternative to flycheck-clj-kondo. But I wasn’t able to find an existing integration with proselint, so I decided to provide one.

My first tries with flymake-easy didn’t go very well. I asked for help on Emacs StackExchange, before realizing I could use flymake-quickdef like flymake-kondor does and answer to myself. The next step was making the solution available to everyone in the form of a package, and so I published the little flymake-proselint.

Flymake may not have the extensive support for checkers that its bigger brother has, and it doesn’t seem to have the same huge community behind, but it’s still a great library to play with. There is a comparison between the two projects on the Flycheck website, so have a look there before making your choice. Note that the comparison doesn’t mention flymake-quickdef, which I find easier to use for extending Flymake.

As for me, my requirements for on-the-fly syntax checking are met by Flymake. At the end of the day it’s good to know that after all these years together Emacs can still surprise me.

It’s never too late

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 18 Sep 2020 00:00:00 +0000

In his article What’s new in Emacs 27.1? Mickey Petersen wrote that the built-in project.el¹ is a library “not widely used” and “about 20 years too late”, concluding that it is “a missed opportunity”.

From what I can tell project.el has been around since 2015. As everything else in our Emacs world, it’s an effort from volunteers offered back to the community. I see no reason to avoid it because it has been lacking the attention of other well-known alternatives such as Projectile. On the contrary, I believe that the more users try it and report what is missing back to the developers or perhaps contribute with lines of code, the more chances this tiny library has to grow and to get better.

Instead of replacing helm-ls-git with project.el, I decided to leave Helm aside for a moment and try my luck with Icomplete. I trust Protesilaos Stavrou’s opinion on it, anyway, so that’s another good point to give it a shot. If you want a detailed setup for Icomplete be sure to follow his lead. I limited myself to installing icomplete-vertical and orderless to make my life easier.

The entry point in project.el is the prefix C-x p. You can hit C-h after that to see the available key bindings. If you press C-x p p a list of known projects will appear. You will see that an option to select a new project is always available, so it’s trivial to add new elements here.

Once you land on your candidate hit RET to be presented with a customizable list of commands to act on the selected project. The keys to activate the commands are highlighted so, for instance, you can press f to start exploring your project files.

The defaults key bindings provided by project.el suit me well enough, but I did apply some changes to tune its behaviour to my needs.

First, I don’t want to rely on find for project--files-in-directory when the faster fd is around the corner.

(el-patch-defun project--files-in-directory (dir ignores &optional files)
  (el-patch-remove
    (require 'find-dired)
    (require 'xref)
    (defvar find-name-arg))
  (let* ((default-directory dir)
         ;; Make sure ~/ etc. in local directory name is
         ;; expanded and not left for the shell command
         ;; to interpret.
         (localdir (file-local-name (expand-file-name dir)))
         (command (el-patch-swap
                    (format "%s %s %s -type f %s -print0"
                            find-program
                            localdir
                            (xref--find-ignores-arguments ignores localdir)
                            (if files
                                (concat (shell-quote-argument "(")
                                        " " find-name-arg " "
                                        (mapconcat
                                         #'shell-quote-argument
                                         (split-string files)
                                         (concat " -o " find-name-arg " "))
                                        " "
                                        (shell-quote-argument ")"))
                              ""))
                    (format "fd -t f -0 . %s" localdir))))
    (project--remote-file-names
     (sort (split-string (shell-command-to-string command) "\0" t)
           #'string<))))

Then I had to tweak project-kill-buffer-conditions for buffers in cider-repl-mode to ensure project-kill-buffers catches them.

(add-to-list 'project-kill-buffer-conditions '(major-mode . cider-repl-mode) t)

The last customization was adding quick keys for magit-status, project-shell, and ripgrep to project-switch-commands. You don’t need my Elisp for that.

As little and work-in-progress as it is, project.el already covers everything I usually need to handle my projects. It’s good to know that right within our beloved text editor comes a tool like this. And no, Pat Benatar, this time is not too little too late.

Note that project.el is also available on ELPA. ↩︎

The end of an era?

manuel.uberti@inventati.org (Manuel Uberti) — Tue, 08 Sep 2020 00:00:00 +0000

Yesterday I noticed it has been a while since I wrote something here. I can easily blame the lack of time and concentration, point the finger at my cinema obsession, or even rant against Plato and Hegel for the energy-draining efforts they require from me. Or I can simply be honest and say the truth out loud: my journey with Emacs has come to a halt. Before calling me names and put the GNU police on my back, hear me out.

After years on a constant tinkering diet, my configuration has reached a point where everything I need from it is covered. The key word in the previous statement is everything. What is this everything I use Emacs for? Well, contrary to the popular Emacs-centric workflows of many fellow Elisp lovers, everything is just prose (Markdown, LaTeX) and Clojure programming with some Elisp on the side. What happens outside of my beloved text editor is up to Firefox, Thunderbird, GNOME Terminal on some occasions, Slack for work and Gajim for personal use, and KeePassXC. 99% of the times this is what my computing is about these days.

Although Emacs can be used for some of the things the aforementioned external programs do, I am fine with this setup for a couple of reasons.

Firstly, I like to keep my configuration as simple as possible. It used to sport over 200 packages, but refinement after refinement has taken me to half that number. It’s even a smaller total if I don’t count the package dependencies for which there is no use-package snippet in my init.el. I am still far from minimalism but maintenance is much easier now, because I know what I want from Emacs and I want it to do just that.

Secondly, but maybe more importantly, I don’t want any kind of distraction in my text editor. This may be just me, but most of the times the Web, reading emails, and messaging interfere with my concentration without adding real value. Emacs is my peace of mind. I turn to it just for writing, knowing well it is not ready to fetch emails or chatting with my wife or a co-worker because that’s how it is set up. There is no technological secret here. It’s all about the psychological pleasure of a maximized Emacs window with little more than my precious text in it.

This line of reasoning has led me to an Emacs configuration that does not require that much fiddling with any more. I have to admit that not seeing buffers from my .emacs.d always presented by helm-mini feels a bit strange. At the same time, though, I am sure they will pop up again as soon as the next irresistible package will reach ELPA or MELPA. Until then, Elisp can go on a well-deserved holiday and have a couple of drinks on me.

Paper Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 24 Jul 2020 00:00:00 +0000

Since I moved to bullet-journaling, most of the time I have been writing on paper. Even though I’ve not restricted my Emacs time to Clojure programming, paper and fountain pen have changed the way I approach my favourite text editor for prose.

As I was writing articles for my blogs, I’ve discovered that I wanted my text-editing environment as close as possible to the beautiful, distraction-free feeling of a blank page. There are plenty of themes and modes out there to suit this particular need, but the combination of settings and packages I am about to describe has proven to be the most satisfying so far.

Theme

A light theme is the obvious choice to mirror the paper look. Since I have been using modus-operandi for a while now, there is no reason to look for something else. Everything in markdown-mode is supported, and with a variable-pitch font (FiraGO in my case) the buffer stops resembling code for once.

Editing modes

I write all my articles in Markdown, but to achieve the desired distraction-free effect I rely on Protesilaos Stavrou’s tips, slightly adjusted to my preferences: “Focused editing tools” for Emacs and Emacs: configuring mixed fonts in Org mode. I am using a variant of Olivetti like him, the only difference being the use of text-scale-increase to increase the text size and text-scale-decrease to restore it back to normal when leaving the mode.

On top of that I use freeze-it, which is like having someone slapping my hands away from the text before the current paragraph. Harsh, yes, but for the obsessive-compulsive writer an effective way to keep the mind focused on one thing at the time. I can always review the previous paragraphs later, and with the big picture in front of me editing often becomes deleting.

Mode-line

Once again, I find myself tweaking the mode-line. Setting modus-operandi-theme-3d-modeline has been enough thus far, but something less prominent can be closer to the no-frills of my Bujo. Luckily William Rankin, the author of Olivetti and freeze-it, shared his magic tricks and I followed his lead. I merely threw in coloured indicators for modified, read-only, and remote buffers. Sorry, I can’t resist a little bit of fanciness.

Final notes

There is more than this to my writing environment. For instance, I wrote about spell-checking before and I use Artur Malabarba’s suggestions on paragraph movements. Not to mention the default Emacs facilities for marking, killing, yanking, and moving around the buffer. Nonetheless, this should be enough to write prose in a quieter and more fruitful way.

My reliable English dictionary

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 13 Jun 2020 00:00:00 +0000

Despite my best efforts, my English needs constant work.¹ I mostly write in this language when I am online, but good prose is a matter of trying, failing, trying again, failing again, and never give up. A bloody battle of words.

An ever-present companion during my writing sessions is the dictionary. Since I don’t want distractions of any kind, I want the dictionary to be offline and easy to use. The more time I spend away from my text, the easier it is for my mind to drift off.

WordNet meets my expectations almost exactly. It’s quickly installable on my Ubuntu machine, a breeze to use, and it comes with a command-line tool (wn) and a graphical one (wnb) which are simple and fast.

However, I don’t want to leave Emacs for a task like this. I want to be able to search for the word at point or to type something and see if what I have in mind makes any sense at all. Why not taking advantage of the power of Helm? That’s why I wrote helm-wordnut.

As I explain in the README, using WordNet within Emacs was already possible through helm-wordnet and wordnut, but in both cases it doesn’t look like there is much maintenance going on. I liked the idea of the former and the nice output of the latter, and so I devised a package with what in my opinion is the simplest and ideal Helm interface for WordNet. I can type what I want or just hit M-n to pick up the word a point. Pressing RET on the desired candidate opens a buffer with a detailed definition of the word. How much detail one needs is customizable through helm-wordnut-cmd-options, but the default covers more than enough already for my usual writings.

Given the existence of helm-wordnet and wordnut, I have not published helm-wordnut on any package archive at the moment. If somebody else finds it a better alternative to the existing solutions, do reach out and let me know. I’ll see what I can do about convincing the MELPA masterminds to accept yet another WordNet front-end.

The same can be said for my Italian, but let’s not dig too deep into my shortcomings please. ↩︎

Search only in visible buffers

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 05 Jun 2020 00:00:00 +0000

Among the things that I dropped when I moved to Helm, Swiper was one of the first ones to go. Actually, the built-in Isearch replaced Swiper first. Then I found out about CTRLF, and now I have the best of both worlds: I can use CTRLF for no-fuss searches and I can rely on helm-occur for a Swiper-like feeling.

However, I often find myself with two buffers in the same window, and sometimes I want to restrict my searches to just those two buffers. CTRLF and helm-occur are not suitable for this task, because they both work on a single buffer. And mu-helm-rg is way too much for this, because it is best used in specific directories or project-wise.

Luckily enough, Thierry Volpiatto has recently introduced helm-occur-visible-buffers in Helm. Like the name says, this command runs helm-occur on all visible buffers. The results are grouped by buffer, making them really easy and clear to navigate. When run in one buffer, helm-occur-visible-buffers behaves just like helm-occur, so if you have a key binding for the latter you can safely point it to the former and retain the functionality you were accustomed to.

I don’t know if my use-case is a niche one, but it’s good to know Helm got me covered once again.

Lockdown Beam: volatile-highlights

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 27 Apr 2020 00:00:00 +0000

In the middle of a frantic editing session one can use some help. You are there sweating, firing key bindings with a smugness you can barely keep at bay, with buffers and windows appearing and disappearing. Point is visibly tired of your powerful skills because, let’s face it, jumping around is not always pleasurable.

In situations such as this, you may find yourself killing a paragraph or a block of code in order to yank it somewhere else. If that “somewhere else” is another buffer (e.g., a Clojure file others worked on), I for one don’t want to make a mess. This is precisely where Keitaro Miyazaki’s volatile-highlights finds its place.

Keitaro’s package adds a temporary highlight to the yanked text which makes the addition stand out briefly, and so I get a sense of what I am doing in a buffer I’m not entirely familiar with yet. There are other commands that benefit from it, as the volatile-highlights README explains. For instance, I find the highlights around undo operations and occur-mode occurrences very helpful.

Although I didn’t play with it, volatile-highlights can be extended to support other packages and commands. Check out vhl/define-extension and vhl/install-extension if you want to go down that road.

This is the last entry in my “Lockdown Beam” series. I was hoping to outlast the lockdown, but I lost the battle eventually. Anyway, do give these packages a chance. It’s easy to overlook a little gem in the ever-growing Emacs ecosystem.

Lockdown Beam: native-complete

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 20 Apr 2020 00:00:00 +0000

If you have followed this blog long enough, you know it’s been a while since I embraced shell-mode. I even have a nice setup to handle its windows and to apply better colours to it.¹

However, before Troy Hinckley’s native-complete fixed it for me, tab-completion in shell-mode wasn’t quite the same experience as the one on a separate terminal emulator. To be honest, I didn’t investigate far enough to understand whether this was due to my Bash configuration or to Emacs itself. The only thing I know is that Troy’s package got me where I wanted to be.

On MELPA you will find two packages: native-complete and company-native-complete. I use both, but if you are not a Company user you can live with the former alone.

Anyway, I set up native-complete with a hook to shell-mode that runs native-complete-setup-bash, then another hook adds company-native-complete to company-backends. Tom explained everything you need to start and other useful details in the package README, so head over there for more details. The only thing I can add is that I have TAB bound to company-complete in shell-mode-map.

Now that there is a libvterm integration for Emacs, staying with shell-mode may sound anachronistic, because proper terminal emulation with your favourite shell is just a package away. But if you, like me, are happy with Bash in shell-mode, I can’t recommend native-complete and company-native-complete enough. By the way, Troy’s work supports csh and other fancy things too, so you’re not strictly limited to Bash.

Next time we will see highlights disappear suddenly. Is the Evil Genius operating my Emacs? Who knows.

Stay safe.

Note that the Modus Themes have built-in support for that, so I don’t customise xterm-color-names and xterm-color-names-bright any more. ↩︎

Lockdown Beam: mark-thing-at

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 13 Apr 2020 00:00:00 +0000

Until I noticed that I was hardly using everything it has to offer, Leo Liu’s easy-kill was one of the packages I used the most. Specifically, I wasn’t really taking advantage of its capability of repeating mark commands, nor its keys to modify the current selection. Although it doesn’t seem actively maintained this day, check it out if you want to extend your mark/kill actions.

As for me, Paul Landes’s mark-thing-at has become my best pal when it comes to marking. Granted, it’s way less powerful than easy-kill, but combine it with Emacs regular key bindings for killing and there is nothing more that I need.

You will find mark-thing-at on MELPA, and if you follow my lead, you can enable mark-thing-at-mode and be happy with it. Note that if you do not configure mark-thing-at-keymap-prefix you end up with C-x m as a prefix for all the mark-* commands now available at your fingertips. This means that you will lose the key binding for compose-mail, but I’m fine with it.

Whatever the prefix you end up with just append C-h to it and you will see the many commands at your disposal. You probably won’t need them all, but it’s good to have a nice way to leverage these marking facilities.

Next time we will explore a better completion system for shell-mode.

Stay safe.

Lockdown Beam: hide-mode-line

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 06 Apr 2020 00:00:00 +0000

Fun fact: the mode-line is the one Emacs thing I’ve probably spent most of my tinkering time on. Why? Hard to tell. I consider it a place for useful information, but the only interaction I have with it is looking at it. It’s not like some of those fancy packages offering you all manners of interactive commands and assorted key bindings.¹ It’s a, well, it’s a line.

Among the several iterations, this one has lasted the longest. But then again, not too long ago I felt the irresistible call of minimalism, and so I ended up with this other one. And yet, despite the immoderate amount of care I spent on it, there are times where I just want it out of my way.

For instance, I have no use for the mode-line in shell-mode or when I am reading the latest news via Elfeed. Luckily, Henrik Lissner’s hide-mode-line is out there for this kind of messy work.

Provided the mode you don’t want to see the mode-line in has a hook, you can add #'hide-mode-line-mode to it with add-hook. For Elfeed, however, a different solution is needed:

(defun mu-elfeed-open ()
  "Open elfeed and hide the mode-line."
  (interactive)
  (mu-save-window-config-then-call #'elfeed)
  (hide-mode-line-mode 1))

Have a look at Passing the prefix argument around if you want to know what mu-save-window-config-then-call does.

Obviously you can go berserk and hide the mode-line everywhere with Henrik’s package. But would you really do that? Don’t be cruel and think about it.

Next time we are going to mark things, so keep your markers around.

Stay safe.

M-x ^mode-line actually gives me ten entries, so what do I know? ↩︎

Lockdown Beam: git-identity

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 30 Mar 2020 00:00:00 +0000

The situation doesn’t seem to get any better, does it? We are still confined in our homes, still wary about our movements and contacts. Since not even running outside is allowed, I am getting lazy, to the point that I’ve never thought I’d miss the gym so much. It’s time to resort to in-house crunches and push-ups, I suppose.

Meanwhile, let’s not forget about Emacs. Last time I hinted at a Git-related package, but at this point wouldn’t writing about Magit again be out of fashion?¹

When it comes to Git repository, the only thing I am not using Magit for is checking and setting my identity. I’m not sure this is a common problem, but I have to handle two Git identities on the same machine, one for personal repositories and one for work projects.

Without Akira Komamura’s git-identity this situation was leading me to confusion, because more often than not I found myself committing and pushing work stuff with my personal identity. One could manually edit .git/config every time or use Git own commands to deal with this, but to me these are both cumbersome alternatives compared to the simplicity of Konamura’s package.

The only configuration needed for me after the installation was binding I to git-identity-info in magit-status-mode-map. Now once I cloned a new repository I can easily check whether the identity is correct or not.

Furthermore, git-identity can help even if for some random reason I didn’t rely on git-identity-info. With git-identity-magit-mode enabled, git-identity makes sure that on magit-commit a global or a local identity is actually set.

Next time we are going to play hide and seek with the mode-line.

Stay safe.

I am kidding, Magit is always stylish. ↩︎

Lockdown Beam: eldoc-eval

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 23 Mar 2020 00:00:00 +0000

As mentioned briefly at the end of the previous entry, today we are going to play with Emacs' Eldoc. Sometimes I forget about it, but eldoc-mode is one of those subtle things which improve my daily Emacs routine. Besides giving me useful information in Elisp, eldoc-mode is always helpful when I am programming in Clojure thanks to its integration with CIDER.

However, there is another place where Eldoc comes in handy. You surely know that when you press M-: you can type an expression in the minibuffer and then evaluate it by pressing RET. But wouldn’t it be great to have Eldoc for these quick runs to?

The answer is not “Well, yes!”, but “Hey, there is a mode for it!”, which is what an Emacser regularly replies when asked about any matter whatsoever. This time the mode comes with the package of the day: Thierry Volpiatto’s eldoc-eval.

Once installed, activating eldoc-eval is easy. Turn on eldoc-in-minibuffer-mode and everything is set.

Nice and simple. You may not like the Eldoc information appearing in the mode-line, but Thierry got you covered with eldoc-in-minibuffer-show-fn. If you use tooltips, try setting this to #'tooltip-show. There are other features in eldoc-eval worth of notice, so be sure to check out its README if you want more juice.

As for me, I am happy with just enabling eldoc-in-minibuffer-mode. I patched eldoc-show-in-mode-line to fit the help message properly in my custom mode-line, but that’s it. If you are using your own mode-line too, I am leaving that as a little exercise.¹

Next time we will meet a Git-related package which doesn’t include the letters “m” and “a” in its name.

Stay safe.

I used el-patch for this. ↩︎

Lockdown Beam: bm.el

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 19 Mar 2020 00:00:00 +0000

I guess there is no need to explain the choice of the word “lockdown” in the title. I don’t know about you, but here in Italy things are getting worse and worse. Every time I look outside the window I see desolation, and for a George Romero fan this is getting scarier and scarier. I am lucky, though. I can work from home (thank you, 7bridges) and study from home (thank you, Ca’ Foscari). But I can also take the time to spread words of love about some Emacs packages I rarely talk about.

Lockdown Beam aims to be a series of small articles on packages that deserve more attention, but I can’t tell now how long this series is going to run. I tend to use all the packages configured in my init.el, and most of them are fairly popular, so it’s not like digging obscure entries from the dust of my setup. However, out of more than 100 packages, I am pretty sure I can find a decent amount of poor neglected things in there.

Let’s start with Jo Odland’s bm.el.

There are many great ways to bookmark things in Emacs,¹ but sometimes a visual clue just adds a good feeling of immediacy one (e.g., myself) can find pleasant. The README says this is a feature from Visual Studio that the author was missing in Emacs, but you will have to check for yourself whether this is something Visual Studio does. You know there is no such thing as a different text editor for me.

Following the documentation, setting up bm.el is easy. If you use use-package, there is a nice example ready for copy-and-paste at Configuring bm.el with use-package. I started from there, but I replaced the hook on vc-before-checkin-hook with a hook on magit-pre-refresh-hook.

I find bm.el really useful when studying source code from others, or when I want to quickly set jumping points in a log file cluttered with stacktraces. It’s quicker then moving around with Isearch or helm-occur, and unlike avy it’s not limited to what is currently visible on the screen.

That’s all for today. Next time a little friend will help me exploit Eldoc.

Stay safe.

Check out what Protesilaos Stavrou has to say about registers. ↩︎

Light is right, alright?

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 16 Mar 2020 00:00:00 +0000

For a long, long while I was a happy Solarized Light user. Then, somehow, I switched to Steve Purcell’s version of Tomorrow Night, and no other theme has been able to take me away from that colour scheme. There were times where I found myself looking for a new light theme, but the lack of a pleasant one¹ left me in the comfortable palettes of Tomorrow Night. I even put on MELPA what at first looked like the light I needed, but the dark side still kept me within its reach.

Why didn’t I go back to Solarized Light if the experience had been so joyful? I guess getting older distanced me somehow from the pleasures of a yellowish background. Don’t get fooled by my grumpiness, though. It’s still one of the best Emacs themes out there, so be sure to check it out if you are after a light theme.

As for me, I’ve recently seen the light again. Protesilaos Stavrou open sourced a couple of beautiful themes, modus-vivendi and modus-operandi, both available at modus-themes, on ELPA, and on MELPA. I am sure the apt readers remember that modus-vivendi first appeared on these pages right at the end of Ripgrepping with Helm: the mode-line, but since then modus-operandi has become the default.

What I found intriguing in Protesilaos’ work is the reasoning behind the themes. I have never cared about the Web Content Accessibility Guidelines, which is a shame considering how poor my eyesight has been since I was a kid. The Modus Themes are built with those guidelines in mind and it shows immediately. The text is always readable, it doesn’t matter what face is applied over it. It’s not only a matter of being able to read, but to always distinguish specific contexts. For instance, comments are clearly separated from the rest of the code without sacrificing legibility. I know this sounds reasonable and it may already be the case for the theme you are currently using, but for my eyes it has never been so easy. And yes, I did tend to prefer beauty over accessibility.

Another remarkable thing about the Modus Themes is that both variants cover a wide range of Emacs packages, something not so axiomatic in the Emacs theme world. Admittedly, I bothered Protesilaos with some issues about Helm and few other packages, but he quickly tamed my wild sensibility. “If a compromise is ever necessary between aesthetics and accessibility, it shall always be made in the interest of latter”, the README points out. So far no complaints from the aesthetics department, though.

Protesilaos explained his ideas in My accessible Emacs themes, a valuable presentation which you should watch before My Modus Themes are in ELPA. Considering that I came from years with a dark background, the switch to a light one has been less traumatic than it may seem. It could be due to the fact that Solarized Light was there way before the dark age, why not? Nevertheless, the new colour scheme is as simple and beautiful as it is effective. See you around, Sith Lord.

An obvious matter of personal taste. ↩︎

A better approach at searching with Helm

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 13 Mar 2020 00:00:00 +0000

When I wrote about how I use ripgrep with Helm in Ripgrepping with Helm, I overlooked something. Actually, let’s be honest. I didn’t study my usual search habits like I should’ve had to.

Looking closely at my per-project searches, there are two patterns I tend to follow:

searching for the thing at point in the current project;
searching for something in the current project.

The first pattern is somehow addressed by the previous incarnation of mu-helm-rg, but it can be improved by leveraging helm’s :input option.

For the second pattern helm-sources-using-default-as-input needs to be temporarily disabled, otherwise helm would start with the thing at point as :default and would run an initial search that most of the times is not what I need. I can still pick up the thing at point with M-n if needed, but in this case I prefer typing what I want to find.

To achieve this, I decided to reimplement helm-grep-ag-1 according to my needs:

(defun mu--helm-rg (directory &optional with-tap type)
  "Build the Helm command for `mu-helm-rg'.

For DIRECTORY, WITH-TAP, and TYPE see `mu-helm-rg'. This command
disables `helm-sources-using-default-as-input' temporarily to
avoid the automatic search which starts when :default is set to
`thing-at-point' (the default behaviour). The search starts
automatically only with WITH-TAP."
  (let ((helm-sources-using-default-as-input nil)
        (command (helm-grep--ag-command))
        (input (when with-tap
                 (thing-at-point 'symbol 'no-properties))))
    (setq helm-source-grep-ag
          (helm-make-source (upcase command) 'helm-grep-ag-class
            :header-name (lambda (name)
                           (format "%s in %s"
                                   name (abbreviate-file-name directory)))
            :candidates-process (lambda ()
                                  (helm-grep-ag-init directory type))))
    (helm-set-local-variable 'helm-input-idle-delay helm-grep-input-idle-delay)
    (helm :sources 'helm-source-grep-ag
          :keymap helm-grep-map
          :history 'helm-grep-ag-history
          :input input
          :truncate-lines helm-grep-truncate-lines
          :buffer (format "*helm %s*" command))))

Now mu-helm-rg must be updated, but the changes are trivial. I only need to consider a new parameter, with-tap, and call mu--helm-rg properly.

(defun mu-helm-rg (directory &optional with-tap with-types)
  "Search in DIRECTORY with RG.

With WITH-TAP, search for thing at point. With WITH-TYPES, ask
for file types to search in."
  (interactive "P")
  (require 'helm-adaptive)
  (mu--helm-rg (expand-file-name directory)
               with-tap
               (helm-aif (and with-types
                              (helm-grep-ag-get-types))
                   (helm-comp-read
                    "RG type: " it
                    :must-match t
                    :marked-candidates t
                    :fc-transformer 'helm-adaptive-sort
                    :buffer "*helm rg types*"))))

Finally, let’s see the new mu-helm-rg in action:

(defun mu-helm-project-search (&optional with-types)
  (interactive "P")
  (mu-helm-rg (mu--project-root) nil with-types))

(defun mu-helm-project-search-at-point (&optional with-types)
  (interactive "P")
  (mu-helm-rg (mu--project-root) t with-types))

(defun mu-helm-file-search (&optional with-types)
  (interactive "P")
  (mu-helm-rg default-directory nil with-types))

Spell-checking and Helm

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 07 Mar 2020 00:00:00 +0000

Helm provides so many great commands I am still discovering new gems in it, like the useful helm-regexp, which lets you build your regular expression pattern, see the results of your search live in the Helm buffer, and optionally pass the query to query-replace-regexp. So neat.

This is why I haven’t written a Helm command of my own until recently. To be fair, as I am going to show there is not even the need for this command to exist, but coding it has been a fun exercise anyway.

When it comes to spell-checking my buffers, I have been relying on mu-cycle-ispell-languages to change dictionaries and flyspell-correct-helm to pick the correct word I happened to misspell. Since I am already using Helm with Flyspell, then, why not using it to select the dictionary too?

First, the actual dictionaries.

(defvar mu-dictionaries '(("en_GB" . "English")
                          ("it_IT" . "Italian")))

Note that I use hunspell for spell-checking as I explained in Spell-checking with Hunspell and flyspell-correct.

Next, my new command.

(defun mu-select-dictionary ()
  "Select the dictionary for the spell-checker."
  (interactive)
  (helm :sources
        (helm-build-sync-source "Dictionaries"
          :candidates (map-values mu-dictionaries)
          :action (lambda (candidate)
                    (let ((dict (car (rassoc candidate mu-dictionaries))))
                      (ispell-set-spellchecker-params)
                      (setq ispell-dictionary dict
                            ispell-local-dictionary dict
                            ispell-local-dictionary-overridden t)
                      (ispell-internal-change-dictionary)
                      (setq ispell-buffer-session-localwords nil)
                      (run-hooks 'ispell-change-dictionary-hook))))
        :preselect (map-elt mu-dictionaries ispell-dictionary)
        :buffer "*helm select dictionary*")
  (flyspell-buffer))

I merely followed the guidelines on the Helm wiki, but let’s break it down.

(helm :source
      (helm-build-sync-source "Dictionaries"

The source of my Helm command comes from the simple alist defined before (mu-dictionaries), so helm-build-sync-source is enough.

:candidates (map-values mu-dictionaries)

Here I am using the excellent map.el to get the clearer “English” and “Italian” labels as :candidates for the Helm buffer.

:action (lambda (candidate)
          (let ((dict (car (rassoc candidate mu-dictionaries))))
            (ispell-set-spellchecker-params)
            (setq ispell-dictionary dict
                  ispell-local-dictionary dict
                  ispell-local-dictionary-overridden t)
            (ispell-internal-change-dictionary)
            (setq ispell-buffer-session-localwords nil)
            (run-hooks 'ispell-change-dictionary-hook)))

The anonymous function for :action is a small version of ispell-change-dictionary, containing only what I need for this operation to complete successfully. Note the use of rassoc: this is how I get the key corresponding to the value of candidate in mu-dictionaries. I didn’t find a similar facility in map.el, but rassoc and car get the job done.

:preselect (map-elt mu-dictionaries ispell-dictionary)

Here I am using the current dictionary as the preselected element in the Helm buffer. I could use :input to have it offered on the prompt, but I prefer to have the prompt empty in this case.

If you look closely at ispell-change-dictionary source code, you can understand the triviality of mu-select-dictionary: ispell-change-dictionary uses completing-read, so in my case it already pops up a Helm buffer. But I am still happy with this solution, and not just because I prefer “Dictionaries” instead of “ispell-change-dictionary” as the source name displayed in my Helm buffer. (Yes, of course it’s mostly because of it.)

As a bonus, thanks to flyspell-buffer the current buffer is spell-checked right after the new dictionary is selected.

Ripgrepping with Helm: the mode-line

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 01 Mar 2020 00:00:00 +0000

Last time I tailored my own helm-do-grep-ag to show you how I use ripgrep within Helm. However, I missed something: the mode-line.

The default mode-line Helm offers for helm-do-grep-ag doesn’t fit well with my custom one, which is a minimal¹ version of the excellent doom-modeline. It’s a two-fold issue: my mode-line is bigger than the default one and I don’t need all the information usually printed by helm-do-grep-ag.

By inspecting Helm source code one can easily find out what helm-do-grep-ag does on mode-line-format. Basically, among other things helm-grep-ag-init sets up the value for mode-line-format according to the number of results. Very well, then, it’s time to bring el-patch back in the game.

First, though, aesthetics.

(set-face-bold 'helm-grep-finish t)

I am just making helm-grep-finish bold, nothing serious.

(el-patch-defun helm-grep-ag-init (directory &optional type)
  "Start AG process in DIRECTORY maybe searching only files of type TYPE."
  (let ((default-directory (or (el-patch-swap
                                 helm-ff-default-directory
                                 (mu--project-root))
                               (helm-default-directory)
                               default-directory))
        (cmd-line (helm-grep-ag-prepare-cmd-line
                   helm-pattern (or (file-remote-p directory 'localname)
                                    directory)
                   type))
        (el-patch-remove
          (start-time (float-time)))
        (proc-name (helm-grep--ag-command)))
    (set (make-local-variable 'helm-grep-last-cmd-line) cmd-line)
    (el-patch-remove
      (helm-log "Starting %s process in directory `%s'"
                proc-name directory)
      (helm-log "Command line used was:\n\n%s"
                (concat ">>> " cmd-line "\n\n")))
    (prog1
        (start-file-process-shell-command proc-name helm-buffer cmd-line)
      (set-process-sentinel
       (get-buffer-process helm-buffer)
       (lambda (process event)
         (let* ((err (process-exit-status process))
                (noresult (= err 1))
                (el-patch-add
                  (proc (concat " HELM " proc-name))))
           (el-patch-swap
             (cond (noresult
                    (with-helm-buffer
                      (insert (concat "* Exit with code 1, no result found,"
                                      " command line was:\n\n "
                                      (propertize helm-grep-last-cmd-line
                                                  'face 'helm-grep-cmd-line)))
                      (setq mode-line-format
                            `(" " mode-line-buffer-identification " "
                              (:eval (format "L%s" (helm-candidate-number-at-point))) " "
                              (:eval (propertize
                                      (format
                                       "[%s process finished - (no results)] "
                                       ,(upcase proc-name))
                                      'face 'helm-grep-finish))))))
                   ((string= event "finished\n")
                    (helm-log "%s process finished with %s results in %fs"
                              proc-name
                              (helm-get-candidate-number)
                              (- (float-time) start-time))
                    (helm-maybe-show-help-echo)
                    (with-helm-window
                      (setq mode-line-format
                            `(" " mode-line-buffer-identification " "
                              (:eval (format "L%s" (helm-candidate-number-at-point))) " "
                              (:eval (propertize
                                      (format
                                       "[%s process finished in %.2fs - (%s results)] "
                                       ,(upcase proc-name)
                                       ,(- (float-time) start-time)
                                       (helm-get-candidate-number))
                                      'face 'helm-grep-finish))))
                      (force-mode-line-update)
                      (when helm-allow-mouse
                        (helm--bind-mouse-for-selection helm-selection-point))))
                   (t (helm-log
                       "Error: %s %s"
                       proc-name
                       (replace-regexp-in-string "\n" "" event))))
             (if noresult
                 (with-helm-buffer
                   (setq mode-line-format
                         `(""
                           mu-mode-line-bar
                           " "
                           (:eval
                            (propertize
                             (format "%s [no results]" ,proc)
                             'face 'helm-grep-finish)))))
               (with-helm-window
                 (setq mode-line-format
                       `(""
                         mu-mode-line-bar
                         " "
                         (:eval
                          (propertize
                           (format "%s [%s results]"
                                   ,proc (helm-get-candidate-number))
                           'face 'helm-grep-finish))))
                 (force-mode-line-update))))))))))

Let’s break down my changes:

(default-directory (el-patch-swap
                     (or helm-ff-default-directory
                         (helm-default-directory)
                         default-directory)
                     (or (mu--project-root)
                         (helm-default-directory)
                         default-directory)))

This has nothing do to with the mode-line, actually, but why not re-use mu–-project-root here? Exactly.

I also removed all the helm-log references, because I am confident my Elisp-fu will not need debugging.² Anyway, I want the buffer identification to look like the rest of the Helm buffer identifications in my mode-line:

(proc (concat " HELM " proc-name))

I am going to use only ripgrep for my searches, so proc-name is usually rg here, but one never knows what will come next.

When there are no results to be shown, I don’t want a message in the Helm buffer, just a clean feedback:

(setq mode-line-format
      `((:eval mu-mode-line-bar)
        " "
        (:eval
         (propertize
          (format "%s [no results]" ,proc)
          'face 'helm-grep-finish))))

The same goes for one or more results:

(setq mode-line-format
      `((:eval mu-mode-line-bar)
        " "
        (:eval
         (propertize
          (format "%s [%s results]"
                  ,proc
                  (helm-get-candidate-number))
          'face 'helm-grep-finish))))

mu-mode-line-bar is what makes my mode-line bigger and I borrowed it from doom-mode-line, so go check its fantastic code to find out about this magic trick.

Finally, this is how the mode-line looks after M-? when the ripgrep process finishes:

And for the sake of completeness, this is how it looks when I move through the results with C-p and C-n:

By the way, the colours are courtesy of modus-vivendi, a great theme by Protesilaos Stavrou I’ve recently switched to.

As in “what is enough for me?”. ↩︎
It’s not that I am that good, it’s just that I can worry about debugging later. ↩︎

Ripgrepping with Helm

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 22 Feb 2020 00:00:00 +0000

Sometimes curiosity leads me to use alternative packages for built-in solutions which I should have explored better. For instance, it took me moving through helm-ag and helm-rg¹ before realising Helm already comes with a functionality suitable for my needs: helm-do-grep-ag.

By now I expect you to be familiar with the wonders of ripgrep. I was heavily relying on counsel-rg back in my Ivy days, and I needed a similar command in Helm. Truth be told, helm-do-grep-ag is not the replacement I was looking for, but understanding its code helped me devise my own utilities for super fast searches.

First of all, let’s use ripgrep instead of ag:

(setq helm-grep-ag-command (concat "rg"
                                   " --color=never"
                                   " --smart-case"
                                   " --no-heading"
                                   " --line-number %s %s %s")
      helm-grep-file-path-style 'relative)

Note that the string for helm-grep-ag-command comes from its documentation. I chose relative for helm-grep-file-path-style because I find relative file paths in the search result buffer more useful than their base name.

Now, helm-do-grep-ag defers to helm-grep-ag, which in turns defers to helm-grep-ag-1, and this is the Helm facility I can leverage for my own ripgrep variant.

(defun mu-helm-rg (directory &optional with-types)
  "Search in DIRECTORY with RG.
With WITH-TYPES, ask for file types to search in."
  (interactive "P")
  (require 'helm-adaptive)
  (helm-grep-ag-1 (expand-file-name directory)
                  (helm-aif (and with-types
                                 (helm-grep-ag-get-types))
                      (helm-comp-read
                       "RG type: " it
                       :must-match t
                       :marked-candidates t
                       :fc-transformer 'helm-adaptive-sort
                       :buffer "*helm rg types*"))))

It’s basically helm-grep-ag with minor aesthetic changes, but you know me. Note the with-types parameter. If I use this command with C-u I get to pick one or more file types to narrow the search down to. I don’t remember if this is possible with counsel-rg, but in large projects it is an absolute must have. Furthermore, the symbol at point, if any, is the default search parameter. Why is this awesome? Keep reading.

With mu-helm-rg in place, I can build a couple of commands to make my life easier.

(defun mu-helm-project-search (&optional with-types)
  "Search in current project with RG.
With WITH-TYPES, ask for file types to search in."
  (interactive "P")
  (mu-helm-rg (mu--project-root) with-types))

(defun mu-helm-file-search (&optional with-types)
  "Search in `default-directory' with RG.
With WITH-TYPES, ask for file types to search in."
  (interactive "P")
  (mu-helm-rg default-directory with-types))

In case you are wondering, mu–-project-root is a trivial function to figure out the current project’s root directory.

(defun mu--project-root ()
  "Return the project root directory or `helm-current-directory'."
  (require 'helm-ls-git)
  (if-let (dir (helm-ls-git-root-dir))
      dir
    (helm-current-directory)))

I don’t need mu-helm-file-search as often as mu-helm-project-search, which is why I’ve bound the latter to M-?. I use this key binding so much it must be a quick one. And this is why having the symbol at point automatically picked up by mu-helm-rg is so important: it just makes the whole search operation as simple as possible.

Oh wait, the symbol at point is not what you are after? No problem, you can start typing whatever you want and have Helm ripgrepping your files.

Both packages seem hardly maintained these days. ↩︎

Helmify some completion mechanisms

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 30 Dec 2019 00:00:00 +0000

Last year I wrote about making Company completion popup appear on demand. There I also briefly mentioned dabbrev-expand and dabbrev-completion, but I have never mentioned hippie-expand, and that it has been pretty much covering my completion needs.

However, moving to Helm prompted me to give helm-dabbrev a try. helm-dabbrev works similarly to dabbrev-completion, but when you hit helm-dabbrev-cycle-threshold (which defaults to 5), it takes you to a Helm buffer with all the benefits that come with it.

Two settings are necessary to have helm-dabbrev behave like I want to. First, I turned off Helm’s show completion, a feature which displays candidates in the current buffer. I don’t like popups, as you may have noticed, and I prefer Helm to always show candidates in the same position of the screen.

(setq helm-turn-on-show-completion nil)

Then, I made helm-dabbrev look for completions in all the available buffers.

(setq helm-dabbrev-related-buffer-fn nil)

By default, helm-dabbrev scans buffers with the same major mode as the current one, but this doesn’t help when, for instance, I am writing a commit message and I want a symbol to be completed. Binding helm-dabbrev to C-. is all that’s left to do.

Moreover, Helm improves on Company too. With the help of helm-company¹ is possible to narrow down the candidates through Helm smart UI. C-TAB is my go-to key binding for helm-company.

Since Helm has become a great companion during my Emacs sessions, it makes sense to rely on it for everything concerning completion.

I used to maintain helm-company before discovering Ivy, and now I’m back to it. The Emacs world is full of surprises. ↩︎

Developing Helm actions

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 23 Dec 2019 00:00:00 +0000

One of the central pieces of my recent return to Helm is helm-ls-git, which empowers helm-browse-project with everything I need to move through my Git projects smoothly. Combine that with helm-projects-history, and you can see why I don’t need Projectile any more. Well, sort of. It’s true that I’ve stopped using Projectile since Helm took over my Emacs configuration, but it’s also true that I had to code the “helmified” version of a couple of features I was heavily relying upon.

In Helm, you can leverage actions to extend the available utilities.

(defun mu--candidate-directory (candidate)
  "Find the directory containing CANDIDATE.
Default to `helm-current-directory' when none can be found."
  (if (fboundp 'helm-ls-git-root-dir)
      (let* ((dir (cond ((stringp candidate)
                         (file-name-directory candidate))
                        ((and (bufferp candidate)
                              (buffer-file-name candidate))
                         (file-name-directory (buffer-file-name candidate)))
                        (t default-directory)))
             (root-dir (helm-ls-git-root-dir dir)))
        (if root-dir
            root-dir
          (helm-current-directory)))
    (helm-current-directory)))

(defun mu-helm-project-dired ()
  "Open Dired buffers at project root from a Helm session."
  (interactive)
  (dolist (cand (helm-marked-candidates))
    (dired (mu--candidate-directory cand))))

(defun mu-helm-project-shell ()
  "Open shell buffers at project root from a Helm session."
  (interactive)
  (dolist (cand (helm-marked-candidates))
    (let* ((default-directory (mu--candidate-directory cand))
           (buffer (concat "*shell "
                           (file-name-nondirectory
                            (directory-file-name default-directory))
                           "*")))
      (mu-shell-open buffer))))

The actions are self-explanatory (see Passing the prefix argument around for mu-shell-open). I often need to jump to a Dired or a shell-mode buffer of a project different from the current one, so I want the possibility to use the current candidate in helm-projects-history as a starting point.

To be fair, mu--candidate-directory does a little more than what I need here. That’s because I use mu-helm-project-dired and mu-helm-project-shell in helm-mini and helm-browse-project too. The latter lists special buffers (e.g., *scratch*) as buffers of the current project. Since they do not live in any specific directory, default-directory is the obvious choice.

Now I have to plug the actions into helm-projects-history. Unfortunately, it doesn’t have a keymap to extend, so I need another solution.

(defvar mu-helm-projects-history-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map helm-map)
    (define-key map (kbd "C-c d") (helm-exit-and-run! (mu-helm-project-dired)))
    (define-key map (kbd "C-c s") (helm-exit-and-run! (mu-helm-project-shell)))
    map)
  "Keymap for `mu-helm-projects-history'.")

(defun mu-helm-projects-history (arg)
  "A `helm-projects-history' with custom actions."
  (interactive "P")
  (require 'helm-ls-git)
  (helm :sources
        (helm-build-sync-source "Project history"
          :candidates helm-browse-project-history
          :action (lambda (candidate)
                    (with-helm-default-directory candidate
                      (helm-browse-project
                       (or arg helm-current-prefix-arg))))
          :keymap mu-helm-projects-history-map)
        :buffer "*helm browse project history*"))

mu-helm-projects-history adds only two things to the original helm-projects-history. I require helm-ls-git early because I need its capabilities inside my actions, and I use my own mu-helm-projects-history-map to make them available in the Helm buffer opened by this command.

Last but not least, helm-exit-and-run! is a helpful macro to avoid dry repetitions:

(defmacro helm-exit-and-run! (&rest body)
  "Define an action with BODY to be run after exiting Helm."
  (declare (doc-string 1))
  `(lambda ()
     (interactive)
     (with-helm-alive-p
       (helm-exit-and-execute-action (lambda (_candidate) ,@body)))))

Note that in my actions I am ignoring the _candidate parameter on purpose. Since helm-marked-candidates grabs the current candidate when none of them is selected, I can use my actions on multiple candidates if I feel wild enough. Yeah, sometimes I can be crazy like that.

The aesthetics of patching

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 01 Dec 2019 00:00:00 +0000

In describing my move to Helm I quickly mentioned another package from Thierry Volpiatto: psession. psession is a light session saving mechanism and it comes with built-in integration for Helm among other things, which of course renders it a valuable improvement to my setup. The installation instructions are pretty clear, so there is no need to bother you with obvious code snippets.

Instead, I want to bother you with my obsessive-compulsive disorder. You see, I am fond of how my beloved text editor looks, especially after boot. I disabled every message, toolbar, scrollbar, menu, and buffer Emacs can throw at me on startup, and the theme is applied as late as possible to ensure nothing obstructs my way to another great day of text editing.

What’s “wrong” with psession then? In order to make the previous sessions available, psession loads some compiled files when Emacs starts. This is what I expect it to do, because there would be no point in saving sessions without restoring them. My only “problem” with this behaviour is the file loading itself.

(cl-defun psession--restore-objects-from-directory
    (&optional (dir psession-elisp-objects-default-directory))
  (let ((file-list (directory-files dir t directory-files-no-dot-files-regexp)))
    (cl-loop for file in file-list do (and file (load file)))))

The code is not hard to understand. What constitutes a rude attack at my delicate aesthetic feelings is that (load file) right before the good-looking closing parentheses. Calling load in this manner causes a bunch of messages to “interfere” with a clean Emacs boot: they show up in the echo area during the loading of my init.el and they hurt so bad!¹

Let’s examine the documentation of the function load:

load is a function defined in lread.c.

Signature

(load FILE &optional NOERROR NOMESSAGE NOSUFFIX MUST-SUFFIX)

Documentation

Execute a file of Lisp code named FILE.

[…]

Print messages at start and end of loading unless optional third arg NOMESSAGE is non-nil (but force-load-messages overrides that).

[…]

Perfect. Now I just have to hack psession--restore-objects-from-directory and make sure load is called with a non-nil value for NOMESSAGE. Usually when I want to silence a command I rely on inhibit-message. Let’s say I want to silence the activation of helm-adaptive-mode:

(let ((inhibit-message t))
  (helm-adaptive-mode 1))

However, psession--restore-objects-from-directory is sort of a private function, so I need something else to change it according to my plans. There are probably several good ways to patch psession--restore-objects-from-directory, but my go-to package in these situations is Radon Rosborough’s el-patch.

(el-patch-feature psession)
(with-eval-after-load 'psession
  (el-patch-cl-defun psession--restore-objects-from-directory
    (&optional (dir psession-elisp-objects-default-directory))
    (let ((file-list (directory-files dir t directory-files-no-dot-files-regexp)))
      (cl-loop for file
               in file-list
               do (and file (el-patch-swap (load file)
                                           (load file nil 'nomessage nil)))))))

Only nine lines of code to please my sense of aesthetic. Beauty is always within reach when we are dealing with Emacs.

Note that at the moment of this writing, el-patch-cl-defun is on the develop branch of el-patch.

I know this is silly, but I hope the double quotation marks and the light tone make the irony clear enough. The point is having fun at hacking Emacs, not insulting Thierry. ↩︎

At the helm of my configuration

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 16 Nov 2019 00:00:00 +0000

It was a cold winter back in December 2014. If memory serves me well, it was time spent at tinkering with old hardware and obscure window managers, reading my first books on functional programming, and dealing with something about text editors I can’t quite put my finger on.

I was also reading about Helm and the praises everywhere in the Emacs community for this package: it can do this, it improves that, it will take you closer to Emacs Nirvana. So yeah, I believed the hype, because it came from trusted sources, especially the Nirvana-guy. Soon Helm took over my configuration and I was using it for everything: switching buffers, selecting bookmarks, in-buffer and per-project searches. Anything involving candidate completion was in the wise hands of Helm.

After a while Ivy came along, and the rest is history. I have been using Ivy/Counsel for such a long a time I might as well say they have become the central drivers of my Emacs setup. Along with the likes of counsel-projectile, these are the packages I use the most during the day.

Lately I’ve been following some conversations about completion-styles, and when I learned that Thierry Volpiatto was working on leveraging Helm for this I just could not resist. Note that Thierry is still devising the implementation, so there is no need to rush at opening issues and scream at him. Anyway, Helm was back in my radar now, and so I took the chance to see if I could come up with a setup which would mirror my everyday workflow with Ivy/Counsel.

I immediately noticed that the theme I use lacked proper support for some Helm faces, but nothing stopped me to do something about it. Much like Ivy/Counsel, Helm provides its own version for common operations such as helm-M-x, helm-find-files, helm-mini, helm-recentf, helm-bookmarks, helm-show-kill-ring, and helm-resume. These are the core features for me, and they work as expected. I also enabled helm-adaptive-mode and helm-autoresize-mode, fixing the Helm window height to my preferences.

As I did with Ivy/Counsel, I made buffer switching (i.e., helm-mini) ignore some files:

(require 'helm-buffers)
(setq helm-ff-skip-boring-files t)
(dolist (regexp '("\\`\\*direnv" "\\`\\*straight" "\\`\\*xref"))
  (cl-pushnew regexp helm-boring-buffer-regexp-list))

My projects are all Git-versioned, hence I installed helm-ls-git, which superseded Projectile and the related helm-projectile in an instant. In order to make per-project lookups with Helm as easy as they were with Ivy/Counsel, I went with helm-ag and helm-xref. To make it even better, I added psession and configured it to persist the things I need from my Emacs sessions. The only goodies I put on top of this setup are helm-bibtex and helm-tramp.

Back in the day, Helm felt heavier and more bloated than Ivy/Counsel, but that is nonsense and was probably due to me being still young and inexperienced at Emacs tweaking. In fact, it still takes less than one second for my Emacs to boot, and so far there is nothing in terms of functionalities I have been missing from my previous configuration. We could argue about UI minimalism and design choices as long as we want, or we could simply try what the Emacs ecosystem offers and decide for ourselves what suits our text editor best.

Thirty straight days

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 02 Nov 2019 00:00:00 +0000

It’s already been a month since I moved from package.el to straight.el, and if it wasn’t for the constant fiddling with my Emacs configuration, I would have hardly noticed the differences in package management. A proof of the solid work behind straight.el, sure, but also a demonstration of how painless package management can be for someone who bypasses the provided UI and relies on use-package snippets to install and setup their packages.

However, with straight.el a new approach to updates is needed. First of all, I compulsively track the state of the packages I have installed, and I tend to update all of them every morning. This is an operation that follows the pulling of the latest developments on the Emacs master branch.

On the one hand, this approach could lead to breaking changes and tears of sadness. On the other hand, I like to report bugs as soon as I discover them, and hopefully help the great developers out there who make my text editing a wonder.

Considering how vital to my computing Emacs is, this may sound like complete madness, I know. In my defence, I mostly rely on stable and long-term support software on my computer. Emacs is just the special kind of madness that drags me to it in spite of the risks. Furthermore, as I wrote last time, straight.el makes it easier to revert to a previous unbroken version of a package, so I can find a functional environment without too much of a hassle.

In my package.el days, package updating was handled by Paradox. In a matter of a couple of key bindings, it took care of notifying me about new versions and installing the selected updates. straight.el is less fancy, though. It provides the necessary commands to install and update a package, as well as the big brother that will pull every package in, but all the UI it offers is the user’s completing-read framework—ivy-read in my case.

Well, like the first line of the README says, straight.el is a tool for the Emacs hacker, so let’s play with it. All I had to do to get a more interactive user experience when updating packages was devising a small wrapper around straight.el’s facilities.

(defun mu-straight-pull-or-prune (&optional prune)
  "Update all available packages via `straight'.
With PRUNE, prune the build cache and the build directory."
  (interactive "P")
  (if prune
      (when (y-or-n-p "Prune build cache and build directory?")
        (straight-prune-build-cache)
        (straight-prune-build-directory))
    (when (y-or-n-p "Update all available packages?")
      (straight-pull-all))))

(bind-key* "<f7>" #'mu-straight-pull-or-prune)

Pretty straightforward, isn’t it? (Pun intended.)

Straight ahead

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 04 Oct 2019 00:00:00 +0000

I have never found Emacs appealing without external packages. From the colour theme to the best Git UI one could ask for, I can’t imagine using Emacs without external packages. The built-in package.el has served me well for a long time. Configured with the usual package archives, it has offered me easy access to new packages and updates for the currently installed ones.

However, digging a little deeper reveals some of its shortcomings. For instance, downgrading has to be done manually, because package.el gives access only to the latest version of a package. This also means it is impossible to get a specific version of said package without getting the source and loading it by yourself.

As you install and configure more and more tools to enhance your Emacs experience, you are adding layers of complexity. Dependencies are pulled in and new releases could bring breaking changes: either you never upgrade your packages, or you learn to live on the bleeding edge. I love that edge as much as your next Emacs hacker, but to approach it with steadiness I need more control over the packages I use.

This is where straight.el fits in. I have to admit that Radon Rosborough played dirty with my feelings: by describing straight.el as purely functional he knew perfectly well a developer in love with functional programming could not resist. But there is more to it, of course.

First of all, I love the documentation. The effort put into explaining the rationale behind it, the comparisons with other package managers, and the basics to get started is simply amazing. Even the process of reproducing bugs is documented. It may seem like a lot to take in, but it’s clear and it’s something I want to know before changing one of the key features of my text editor.

Moreover, it takes a few lines of code to bootstrap straight.el. It would probably take fewer lines to set up package.el, that’s true, but straight.el is far more customisable. It also works seamlessly with use-package, so I didn’t have to reinvent my Emacs configuration just to try a new package manager.

Finally, you can freeze your package state at any time with straight-freeze-versions. This creates a lockfile with the current versions of your packages, meaning you can reproduce your exact configuration with a simple straight-thaw-versions. Stability is just a couple of commands away.

There must (should?) be a moment when the Emacs hacker knows they exploited their beloved editor as much as possible, the eureka light bulb leading the way through a thick fog of setq and defun. Valhalla is there, Emacs hacker, you know it. As for me, I decided to accept the murkiness for now, and look for the bulb that will get me out of here eventually another time.

Open Magit from Ibuffer

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 07 Aug 2019 00:00:00 +0000

It’s amazing how many packages for our beloved editor exist out there. ELPA and MELPA keep growing and growing, and curiosity is always pushing me out to look for a new package to try.

Last year I wrote about Eyebrowse, a cool workspace manager that has proven to be a reliable friend until recently. Eyebrowse is a helpful extension, but as it turns out the built-in Ibuffer is enough to make sense of all of the buffers available. I open it with `C-x C-b, which is one of the most used key bindings in my everyday Emacs interactions.

Ibuffer presents a customizable list of buffers on which, much like Dired, we can apply different kinds of operations: filter, sort, group, mark, delete, bury, visit. Just press h in Ibuffer to get an idea.

Since I mainly work on projects versioned on Git, ibuffer-vc helps with grouping the buffers in a project-based fashion and operate on them. For instance, to quickly close a project and its related buffers, mark the project header for deletion with d and then press x.

One thing I was missing in Ibuffer was an integration with Magit. I wanted to open magit-status in the project the current buffer (i.e., the buffer where point is on) belongs to.

(defun mu-ibuffer-magit ()
  "Open `magit-status' for the current buffer."
  (interactive)
  (let ((buf (ibuffer-current-buffer t)))
    (magit-status (cdr (ibuffer-vc-root buf)))))

I’ve bound this function to v in ibuffer-mode-map. Note that v was previously calling ibuffer-do-view, so you may want to pick the key that suits you best.

Format XML like a pro

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 18 Jul 2019 00:00:00 +0000

Years ago I wrote about a custom function that uses shell-command-on-region to run xmllint on an XML buffer.

There is nothing wrong with this function, but a simpler approach is using reformatter, a nice tool from the prolific mind of Steve Purcell.

Once installed, defining a new formatter is trivial:

(reformatter-define xml-format
  :program "xmllint"
  :args '("--format" "-")
  :mode nil)

Now I can add a key binding for xml-format or simply type M-x xml-format in an XML buffer to have it nicely printed.

Note that setting :mode to nil tells reformatter-define to not create a minor mode, which I don’t need in this particular case. The minor mode could be useful if you want your formatter to be called automatically when you save a buffer. For instance, without changing the default setting for :mode you could set up the formatter in a project via .dir-locals.el with:

((nxml-mode
  (mode . xml-format-on-save)))

You can also specify other options when creating a formatter, so be sure to check the documentation of reformatter-define (C-h f reformatter-define).

Motivate yourself

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 06 Jul 2019 00:00:00 +0000

Life is such an ephemeral thing. When you really think about it, the time spent on the planet we are destroying day after day is not that much, especially compared to the entire history of humankind. Luckily enough, I can allow myself to indulge in thoughts about life and time. I tend to avoid laziness as much as possible, saving spare time for gratifying leisure: morning runs and basic workout, books, cinema, collecting vinyls, occasional cooking. I like to think of myself as someone who is not set on a predictable path for the rest of his life.

Lassi Kortela’s memento-mori has recently appeared on MELPA. It’s a small package which aims to display your age in the mode-line. The age is displayed with two decimals and it gets updated after a few days once you turned on memento-mori-mode. Thus you have a reminder of how long you have been on Earth, a somehow inspirational indicator to question the time at your disposal. We are entering philosophical worlds here.

However, I don’t like having too much stuff in my mode-line. I want it simple and with only the information I need. That’s why I use minions to hide all the minor-modes. But I can still use memento-mori to display a message on Emacs startup.

(defun mu-display-memento-mori ()
  "Display my current age by leveraging `memento-mori-age-string'."
  (interactive)
  (let ((first-name (car (s-split-words user-full-name)))
        (age (s-trim memento-mori-age-string))
        (msg "%s, you are %s, don't waste your time!"))
    (run-with-timer 2 nil
                    (lambda ()
                      (message msg first-name age)
                      (run-with-timer 3 nil
                                      (lambda ()
                                        (message nil)))))))

I am using s facilities to manipulate strings, but more importantly the trick is using run-with-timer as explained on Emacs.StackExchange. After two seconds, the message is shown, and three seconds after being visible it will disappear.

Provided you set memento-mori-birth-date and activate memento-mori-mode, adding the function to after-init-hook does the rest.

Note that you need to activate lexical binding in your init file to use mu-display-memento-mori.¹

Thanks to Martin Buchmann for pointing this out. ↩︎

Bury shell buffers

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 01 Jul 2019 00:00:00 +0000

Last time I refactored my windows restoring configuration in order to pass the prefix argument around. This is a nice solution to leverage my wrappers for commands like shell, but I can push it a little further.

I have already discussed a couple of functions to restore my windows configuration when I exit a fullframed buffer.

(defun mu-restore-window-configuration (config)
  "Kill current buffer and restore window configuration in CONFIG."
  (interactive)
  (kill-this-buffer)
  (set-window-configuration config))

(defun mu-pop-window-configuration ()
  "Restore previous window configuration and clear current window."
  (interactive)
  (let ((config (pop mu-saved-window-configuration)))
    (if config
        (mu-restore-window-configuration config)
      (if (> (length (window-list)) 1)
          (delete-window)
        (bury-buffer)))))

However, with these functions the buffer I am leaving gets killed. This is fine when moving away from, say, Ibuffer or Paradox, but it’s less than optimal for shell buffers which may be running a long-run process.

Once again, the prefix argument can help:

(defun mu--restore-window-configuration (config &optional bury-buffer)
  "Kill current buffer and restore the window configuration in CONFIG.
With BURY-BUFFER bury the buffer instead of killing it."
  (if bury-buffer
      (bury-buffer)
    (kill-this-buffer))
  (set-window-configuration config))

(defun mu-pop-window-configuration (&optional bury-buffer)
  "Restore the previous window configuration and clear current window.
With BURY-BUFFER bury the buffer instead of killing it."
  (interactive "P")
  (let ((config (pop mu--saved-window-configuration)))
    (if config
        (mu--restore-window-configuration config bury-buffer)
      (if (> (length (window-list)) 1)
          (delete-window)
        (bury-buffer)))))

Now that the functions can make use of the prefix argument, I just need to call them properly from a shell buffer:

(defun mu-shell-bury ()
  "Bury the shell window."
  (interactive)
  (let ((current-prefix-arg 4))
    (call-interactively #'mu-pop-window-configuration)))

I’ve bound this to C-c C-q, so I can still kill a shell buffer using C-x k (kill-this-buffer in my configuration) if needed.

Passing the prefix argument around

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 21 Jun 2019 00:00:00 +0000

Last year I blogged about a solution to a common problem I had with windows in Emacs. I wanted to be able to exit particular fullframed buffers and restore the windows as they were before opening those buffers.

The core of my solution is the following function:

(defun mu-save-wins-then-call (func &optional args)
  "Save current window configuration, then call FUNC optionally with ARGS."
  (interactive)
  (push (current-window-configuration) mu-saved-window-configuration)
  (cond
   ;; We have arguments for the function
   ((bound-and-true-p args) (funcall func args))
   ;; The function requires exactly one argument, and we want it to be nil
   ((equal args "nil") (funcall func nil))
   ;; The function does not expect arguments
   (t (funcall func))))

This function works fine for most of my cases, but it doesn’t take the prefix argument into account. Since I rely heavily on shell-mode, at times I need to open more than one shell buffer, and the documentation of the shell command specifies that the prefix argument can be used to open new buffers on demand:

Run an inferior shell, with I/O through BUFFER (which defaults to `shell'). Interactively, a prefix arg means to prompt for BUFFER.

Hence, I need to mimic C-u M-x shell in mu-save-wins-then-call:

(defun mu-save-wins-then-call (func &optional args)
  "Save current window configuration, then call FUNC optionally with ARGS."
  (interactive "P")
  (push (current-window-configuration) mu--saved-window-configuration)
  (cond
   ;; We have the prefix argument
   ((= (prefix-numeric-value args) 4)
    (let ((current-prefix-arg 4))
      (call-interactively func)))
   ;; We have arguments for the function
   ((or (bound-and-true-p args) 
        (stringp args)) 
    (funcall func args))
   ;; The function does not expect arguments
   (t (funcall func))))

Now I can open as many fullframed shell buffers as I want with C-u F1:

(defun mu-shell-open (&optional new-buffer)
  "Save window configuration and call `shell'.
With NEW-BUFFER open a new buffer."
  (interactive "P")
  (mu-save-wins-then-call #'shell new-buffer))

(with-eval-after-load 'shell
  (fullframe shell mu-pop-window-configuration))

(bind-key "<f1>" mu-shell-open)

mu-pop-window-configuration is detailed over at Restoring the window configuration in Emacs.

Better colours in Emacs shell

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 14 Jun 2019 00:00:00 +0000

I have ve been using shell-mode regularly for almost two years now. It has helped me a lot in staying focused on what I’ve been doing in Emacs instead of switching back and forth between the buffer and GNOME Terminal.

A recent discovery made shell-mode even snappier and more pleasant to use: xterm-color.

By simply following the guidelines in the README you get a working setup for shell-mode. Note that there are also examples for EShell and compilation buffers, so it’s up to you to decide where you want to use xterm-color.

Honestly I complied. I only changed the default colours to match those of my favourite theme:

(defvar mu--tomorrow-night-colours ["#1d1f21" "#cc6666"
                                    "#b5bd68" "#f0c674"
                                    "#81a2be" "#b294bb"
                                    "#8abeb7" "#c5c8c6"])
(setq xterm-color-names mu--tomorrow-night-colours
      xterm-color-names-bright mu--tomorrow-night-colours)

By the way, the ls alias I was using is not needed any more.

It never occurred to me

manuel.uberti@inventati.org (Manuel Uberti) — Tue, 14 May 2019 00:00:00 +0000

Years of Emacs, and I am still learning something new that improves my daily workflow.

Recently I’ve had to deal with CSV files, generated by a little Clojure program using data from different databases. The CSV files are then imported in another database through a new shiny application bought by our customer. Data integration, exactly.

While the data extraction is just a matter of SQL queries, the CSV files must match the stringent requirements of the new application. We ended up with messy CSV files, close but not that close to the expected results. Needless to say, sometimes we have to edit the files manually, and this is where Emacs once again shines.

The problem is simple: how can I list only the matches I am looking for in a CSV file, without printing the whole lines the matches belong to? I need a clean list of occurrences, nothing more, because debugging these files is already painful as it is.

I am so used to swiper-isearch and counsel-rg that I tend to forget Emacs built-in occur. As per the documentation:

When NLINES is a string or when the function is called interactively with prefix argument without a number (`C-u' alone as prefix) the matching strings are collected into the *Occur* buffer by using NLINES as a replacement regexp.

Hence, I just need to:

press C-u M-s o (or the equivalent but longish of C-u M-x occur)
type the string I am looking for
hit RET

It doesn’t get easier than this.

Switching buffers (Take 2)

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 16 Mar 2019 00:00:00 +0000

Last month I wrote about the neat nswbuff, but there is another way to implement buffer switching without introducing a new package.

Since I already use counsel-projectile, why not leverage it to my needs?

(defun mu-switch-to-project-buffer-if-in-project (arg)
    "Custom switch to buffer.
With universal argument ARG or when not in project, rely on
`ivy-switch-buffer'.
Otherwise, use `counsel-projectile-switch-to-buffer'."
    (interactive "P")
    (if (or arg
            (not (projectile-project-p)))
        (ivy-switch-buffer)
      (counsel-projectile-switch-to-buffer)))

(bind-key* "C-x b" #'mu-switch-to-project-buffer-if-in-project)

Pretty self-explanatory. By default, when not in a project counsel-projectile-switch-to-buffer asks you for the project to switch to.

However, if I am not in a project chances are I want to switch to a buffer that doesn’t belong to a project, especially since I usually enter a project before switching to one of its buffers.

nswbuff has previews and back-and-forth navigation, so it still offers a nicer solution to buffer switching. This is Emacs, of course, so you know the deal: endless possibilities.

Jump around

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 14 Feb 2019 00:00:00 +0000

Last time I shared my preferred choice for buffer switching, so let’s keep jumping around. The House of Pain reference is a bit tacky, I know, but 90s nostalgia is still flying pretty high from what I’ve heard.

Quickly moving in a buffer is something every Emacs knight do multiple times a day. I distinguish in-buffer jumps in two tags:

jumps that encompass all the buffer content
jumps limited to what is currently visible

The first movements are covered by Oleh Krehel’s Swiper, but I am more interested in the second kind of jumps this time. There are plenty of solutions both bundled in Emacs (e.g., pop/mark commands) and in the wild. My favourite is Avy, again from Oleh Krehel.

(use-package avy-jump                   ; Jump to characters in buffers
  :ensure avy
  :bind (("C-j" . avy-goto-char-in-line)
         ("M-j" . avy-goto-char)))

As it always happens with Oleh’s packages, avy is well-documented, easy to extend, and full of useful commands. I only added bindings for the ones I use the most, and I really use these two all the time.

avy-goto-char allows me to move anywhere following the character I am after. It’s quicker than typing the whole candidate in Swiper, and obviously better than manually moving point with C-p/C-n or, worse, the arrow keys.

avy-goto-char-in-line behaves in much the same way, but it is limited to the current line. If you remember iy-go-to-char mentioned years ago on Emacs Rocks, this is Oleh’s own variant.

Both commands push point to the mark-ring, so the default Emacs key binding C-u C-SPC takes you back to your original position.

However, there is an even quicker alternative when I want to jump between occurrences of the symbol where point currently is, which turns out to be pretty handy when coding.

(use-package symbol-overlay             ; Highlight symbols
  :ensure t
  :bind (:map symbol-overlay-mode-map
              ("M-h" . symbol-overlay-put)
              ("M-n" . symbol-overlay-jump-next)
              ("M-p" . symbol-overlay-jump-prev))
  :hook ((conf-mode . symbol-overlay-mode)
         (html-mode . symbol-overlay-mode)
         (prog-mode . symbol-overlay-mode)
         (yaml-mode . symbol-overlay-mode)))

Symbol Overlay not only highlights all the occurrences of the current symbol, but it lets you move quickly among them with symbol-overlay-jump-prev and symbol-overlay-jump-next without asking for a character to look for.

Moreover, Symbol Overlay works on all the buffer content, so in this particular case is quicker than Swiper too.

Switching buffers

manuel.uberti@inventati.org (Manuel Uberti) — Tue, 05 Feb 2019 00:00:00 +0000

One of the most valuable packages I rely on everyday is counsel-projectile. Combining the power of counsel and Projectile, this great work from Eric Danan has been governing my project management in Emacs for quite a while.

One nifty feature of counsel-projectile is counsel-projectile-switch-to-buffer, bound to C-c p b, which lets you pick the buffer to switch to from the current project’s open buffers.

However, old habits never die. Years and years of Ctrl-TAB and Ctrl-Shift-TAB in my web browser window are hard to forget. And so enters Joost Kremers’ nswbuff.

(use-package nswbuff                    ; Quick switching between buffers
  :ensure t
  :bind* (("<C-tab>"           . nswbuff-switch-to-next-buffer)
          ("<C-S-iso-lefttab>" . nswbuff-switch-to-previous-buffer))
  :config (setq nswbuff-buffer-list-function #'nswbuff-projectile-buffer-list
                nswbuff-display-intermediate-buffers t
                nswbuff-exclude-buffer-regexps '("^ .*" "^\\*.*\\*")))

~~I am loading it from a specific path, because at the time of this writing the package is not on MELPA.~~

The key setting here is the value of nswbuff-buffer-list-function. Using nswbuff-projectile-buffer-list activates nswbuff integration with Projectile, and so I can quickly move between my project buffers hitting the good ol’ Ctrl-TAB.

Make your company behave

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 17 Jan 2019 00:00:00 +0000

Sometimes it just takes a little thing to make your day.

I have been using company-mode for ages, becoming accustomed to the list of candidates popping up whenever the automatic completion kicks in.

However, more often than not what I need is in-buffer, context-aware completion, and in this case dabbrev-expand or dabbrev-completion, which I have bound to C-, and C-. respectively, are enough.

It’s pretty simple to turn off company-mode automatic completion:

(setq company-idle-delay nil)

That’s it.

To get the list of candidates back when I need, I have company-complete bound to C-c c.

Nice and easy.

Playing hide-and-seek with my REPLs

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 19 Dec 2018 00:00:00 +0000

Emacs users know their beloved editor has a penchant for throwing windows and buffers around. Smart Emacs users know how to make Emacs behave with a careful configuration of display-buffer-alist. For instance, I like to have all of my REPLs in a bottom side window, taking up half of the screen size.

(setq display-buffer-alist
      `((,(rx bos (or "*cider-repl"     ; CIDER REPL
                      "*intero"         ; Intero REPL
                      "*idris-repl"     ; Idris REPL
                      "*ielm"           ; IELM REPL
                      "*SQL"))          ; SQL REPL
         (display-buffer-reuse-window display-buffer-in-side-window)
         (side . bottom)
         (reusable-frames . visible)
         (window-height . 0.50))))

I then have a couple of custom functions, lifted from Sebastian Wiesner’s archived configuration, to quickly close the REPL and go back to the buffer I was editing.

(defun mu-find-side-windows (&optional side)
  "Get all side window if any.
If SIDE is non-nil only get windows on that side."
  (let (windows)
    (walk-window-tree
     (lambda (window)
       (let ((window-side (window-parameter window 'window-side)))
         (when (and window-side (or (not side) (eq window-side side)))
           (push window windows)))))
    windows))

;;;###autoload
(defun mu-quit-side-windows ()
  "Quit side windows of the current frame."
  (interactive)
  (dolist (window (mu-find-side-windows))
    (when (window-live-p window)
      (quit-window nil window)
      ;; When the window is still live, delete it
      (when (window-live-p window)
        (delete-window window)))))

(bind-key "C-c w q" #'mu-quit-side-windows)

All of this usually works fine. However, CIDER has recently introduced a new session system which doesn’t play well with this setup. Basically, using quit-window on a CIDER REPL results in a buffer without its related REPL available.

The solution is trivial.

;;;###autoload
(defun mu-hide-side-windows ()
  "Hide side windows of the current frame."
  (interactive)
  (dolist (window (mu-find-side-windows))
    (when (window-live-p window)
      (delete-window window))))

(bind-key "C-c w h" #'mu-hide-side-windows)

Now I just hide the side windows of the current buffer, and the linked REPL is always a key binding away.

Notice that if you are only visiting one buffer and a REPL, pressing C-x 0 in the REPL window or C-x 1 in the buffer where the REPL window was opened has the same effect of C-c w h.

What’s the theme?

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 01 Jun 2018 00:00:00 +0000

Last time I explained how to display your Emacs version with extra useful details. I closed the article saying that there could be more interesting stuff to display, and here I am with something new.

Sometimes I happen to report missing font-locking or other small issues with faces in a mode I use. Why not have my current colour theme name displayed along with the bits and pieces gathered in the previous article?

As Steve Purcell explained on StackExchange, the concept of current theme is a bit fuzzy in Emacs. You can have multiple themes on at the same time, just have a look at M-x customize-themes. Moreover, activating a theme means applying its settings to the faces and variables it specifies.

Thus I came up with this little function:

(defun mu--colour-theme ()
  "Get the currently applied colour theme."
  (replace-regexp-in-string
   "[\t\n\r ]+" ""
   (let* ((command (concat "rg load-theme " user-emacs-directory))
          (res (shell-command-to-string command)))
     (nth 1 (split-string res "'")))))

Basically I run ripgrep in my .emacs.d to get the lines containing load-theme. Obviously this will return the line in mu–-colour-theme as well. However, since I use split-string with ' as separator I can get the element I need from the result of ripgrep. nth 1 gives me what I am looking for: sanityinc-tomorrow-night.

Now I can have the active colour theme displayed in my environment details buffer:

;;;###autoload
(defun mu-env-info ()
  "Display Emacs version and system details in a temporary buffer."
  (interactive)
  (let ((buffer-name "*env-info*"))
    (with-help-window buffer-name
      (with-current-buffer buffer-name
        (insert (emacs-version) "\n\n")
        (insert "Repository revision: " emacs-repository-version "\n")
        (when (and system-configuration-options
                   (not (equal system-configuration-options "")))
          (insert "Configured using:\n"
                  system-configuration-options))
        (insert "\n\nEmacs uptime: " (emacs-uptime) "\n")
        (insert "Colour theme: " (mu--colour-theme) "\n")
        (insert "Operating system: " (mu--os-version) "\n")
        (insert "Window system: " (getenv "XDG_SESSION_TYPE") "\n")
        (insert "Desktop environment: " (mu--gnome-version))))))

A fancy Emacs version

manuel.uberti@inventati.org (Manuel Uberti) — Fri, 25 May 2018 00:00:00 +0000

If you like to play diligently and kindly with the Emacs community, you will end up reporting bugs or asking for new features to your favourite package maintainers.

My skills at bug reporting have improved over the years. From the angry “it doesn’t work, man!!1!” to more polite questions, I am always looking for better reports to help debug and solve the problems I encounter.

Usually, package maintainers ask you to reproduce the bug in a clean emacs -Q environment. And that’s good. But they are also happy when you provide as much information as possible about the system you are using.

That’s why I came up with a custom function to gather details about my Emacs version and where I am running it. It all started with this answer from Drew Adams on Emacs StackExchange. His code does way much more than I need, though, so I stripped down the inessential and turned everything into this:

(defun mu--os-version ()
  "Call `lsb_release' to retrieve OS version."
  (replace-regexp-in-string
   "Description:\\|[\t\n\r]+" ""
   (shell-command-to-string "lsb_release -d")))

(defun mu--gnome-version ()
  "Call `gnome-shell' to retrieve GNOME version."
  (replace-regexp-in-string
   "[\t\n\r]+" ""
   (shell-command-to-string "gnome-shell --version")))

;;;###autoload
(defun mu-display-version ()
  "Display Emacs version and system details in a temporary buffer."
  (interactive)
  (let ((buffer-name "*version*"))
    (with-help-window buffer-name
      (with-current-buffer buffer-name
        (insert (emacs-version) "\n")
        (insert "\nRepository revision: " emacs-repository-version "\n")
        (when (and system-configuration-options
                   (not (equal system-configuration-options "")))
          (insert "\nConfigured using:\n"
                  system-configuration-options))
        (insert "\n\nOperating system: " (mu--os-version) "\n")
        (insert "Window system: " (getenv "XDG_SESSION_TYPE") "\n")
        (insert "Desktop environment: " (mu--gnome-version))))))

By using M-x mu-display-version I now get a handy temporary buffer with all the details I want.

A simple q will close the buffer, and I am pretty sure I can add more useful stuff in there. For now, it suffices.

Beauty lies in the segments of the mode line

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 10 Mar 2018 00:00:00 +0000

Since I basically spend much of my computing in Emacs, it’s no surprise I have come to love customizing it. One Emacs facet I keep returning to is the mode line.

To be honest, it’s hard to remember everything I tried on this little but very useful tool. For a long while smart-mode-line has been my go-to package. I considered powerline briefly, but even spaceline didn’t last long. Eventually, I rolled my own spin and never looked for an external solution again.

Recently, Jonas Bernoulli — of Magit fame — unveiled two new packages expressly dedicated to the mode line: minions and moody.

Ever being annoyed by the long list of minor modes taking up precious space? Or are you just tired of adding :diminish every time you install a new package via use-package? minions to the rescue.

minions replaces the minor mode list with a customizable lighter, which upon click reveals a menu with an entry for every minor mode available. You can enable or disable a specific mode or explore its settings in a breeze. minions reduces the clutter while making it easier to check on your minor modes.

On the other hand, moody is for the true artist. I love sparkling Emacs with some beauty, but as much as sanityinc-tomorrow-night helps me with that, I haven’t been able to accomplish something really satisfying with the mode line before trying moody.

Now look at that. It feels awesome.

The number 2 on the left is my little variation on the Eyebrowse segment I found in spaceline.

Refactoring my windows restoring solution

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 03 Mar 2018 00:00:00 +0000

Following my last article on restoring window configurations with custom functions, Clément Pit-Claudel got in touch with me and suggested a little improvement. Clément pointed out the built-in Emacs command winner-undo, which I promptly used to simplify my solution.

Let’s enable winner-mode, first, because winner-undo comes with it.

(use-package winner                     ; Restore old window configurations
  :init (winner-mode t))

winner-mode automatically takes care of storing window configurations, thus I can safely remove functions like mu-ibuffer-open:

(defun mu-ibuffer-open ()
  "Open Ibuffer after storing the current window configuration."
  (interactive)
  (mu-push-window-configuration)
  (ibuffer))

Now I only need to call winner-undo when I exit the desired, fullframed buffer.

(defun mu-pop-window-configuration ()
  "Kill current buffer and restore the previous window configuration."
  (interactive)
  (kill-this-buffer)
  (let ((inhibit-message t))
    (winner-undo)))

I wrapped (winner-undo) with (inhibit-message t) to get rid of the superfluous message about the restored window configuration number.

This is a much cleaner solution. I still have to use fullframe, of course, but by reusing an inner Emacs functionality I get the same result with less code.

However, this code has a problem. winner-mode does not save the configuration of a frame with a single window. In this case winner-undo has nothing to undo and it usually takes me back to a completely different buffer than the one I started from.

Therefore I revised my functions and made them a bit more general. Basically, I removed mu-push-window-configuration and added mu-save-wins-then-call.

(defun mu-save-wins-then-call (func &optional args)
  "Save current window configuration, then call FUNC optionally with ARGS."
  (interactive)
  (push (current-window-configuration) mu-saved-window-configuration)
  (cond
   ;; We have arguments for the function
   ((bound-and-true-p args) (funcall func args))
   ;; The function requires exactly one argument, and we want it to be nil
   ((equal args "nil") (funcall func nil))
   ;; The function does not expect arguments
   (t (funcall func))))

The "nil" check is kind of a hack just for paradox-list-packages, which expects one non-optional argument. Since &optional args evaluates to nil when non present, I need the check to avoid calling (funcall func) in this particular case. I am sure there is a better solution, but I’ll leave that for another time.

Nonetheless, functions like the previously mentioned mu-ibuffer-open becomes cleaner.

(defun mu-ibuffer-open ()
  "Save window configuration and call `ibuffer'."
  (interactive)
  (mu-save-wins-then-call 'ibuffer))

(defun mu-elfeed-open ()
  "Save window configuration and call `elfeed'."
  (interactive)
  (mu-save-wins-then-call 'elfeed))

(defun mu-paradox-open ()
  "Save window configuration and call `paradox-list-packages'."
  (interactive)
  (mu-save-wins-then-call 'paradox-list-packages "nil"))

With the help of funcall I have a generic wrapper that can be applied wherever I need.

Thanks again to Clément Pit-Claudel who helped me dig further into my idea and explore new paths.

Restoring the window configuration in Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 24 Feb 2018 00:00:00 +0000

Last time I explained how I customised Magit to kill its buffers upon quitting magit-status. My solution uses magit-restore-window-configuration, which does exactly what the name suggests. Wouldn’t it be great if a similar handy trick could be applied to any Emacs functionality?

Specifically:

I’d like to run some modes in a window that takes up the whole frame
I’d like to quit them with the previous window configuration completely restored

Two modes that I use daily would definitely become more pleasant: ibuffer-mode and org-agenda-mode. Fortunately, the Emacs community has already devised everything I need.

First, I have to save the current window configuration.

(defvar mu-saved-window-configuration nil)

(defun mu-push-window-configuration ()
  "Save current window configuration."
  (interactive)
  (push (current-window-configuration) mu-saved-window-configuration))

I can now create a command to open the desired mode.

(defun mu-ibuffer-open ()
  "Open Ibuffer after storing current window configuration."
  (interactive)
  (mu-push-window-configuration)
  (ibuffer))

A buffer can be visited in a single window per frame with fullframe.

(with-eval-after-load 'ibuffer
    (fullframe ibuffer mu-pop-window-configuration))

The first argument to fullframe indicates that I want the function ibuffer to be executed in a single window of the current frame. The second argument is the command[^1] invoked when quitting Ibuffer, which will have to restore the previous window configuration.

(defun mu-restore-window-configuration (config)
  "Kill current buffer and restore window configuration in CONFIG."
  (interactive)
  (kill-this-buffer)
  (set-window-configuration config))

(defun mu-pop-window-configuration ()
  "Restore previous window configuration and clear current window."
  (interactive)
  (let ((config (pop mu-saved-window-configuration)))
    (if config
        (mu-restore-window-configuration config)
      (if (> (length (window-list)) 1)
          (delete-window)
        (bury-buffer)))))

These little functions are just my personal take on the awesome gems I discovered in John Wiegley’s Emacs configuration.

Nothing can stop me now from applying the same pattern to any mode I want. Once again, Emacs shows a degree of customizability second to none.

Exterminate Magit buffers

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 17 Feb 2018 00:00:00 +0000

Some say that Emacs users rarely kill buffers. Instead they smoothly dance away to another buffer using their preferred switching mechanism, and just keep on working with no hiccups whatsoever. In my case ivy-switch-buffer is usually doing all the the dancing, with Ibuffer coming in when the situation gets out of hand.

However, I do not enjoy having more open buffers than what I really need. Call it obsessive-compulsive disorder, call it whatever you like, I want my buffers list clean and on point.

Magit has a penchant for open buffers. Jonas Bernoulli already explained the reasoning behind this behaviour, but he also suggested a solution to clean up Magit-related buffers when the work is done.

Following Jonas’ tip, this is what I devised:

(defun mu-magit-kill-buffers (param)
  "Restore window configuration and kill all Magit buffers."
  (let ((buffers (magit-mode-get-buffers)))
    (magit-restore-window-configuration)
    (mapc #'kill-buffer buffers)))

(validate-setq magit-bury-buffer-function #'mu-magit-kill-buffers)

The function is simple: first it collects the available Magit buffers, then restores the window configuration as it was before calling magit-status, and finally applies kill-buffer on the buffers previously collected. kill-buffer will not ask for confirmation, so now pressing q in magit-status has the desired effect.

Something is weird in that function, though. Why pass param to mu-magit-kill-buffers if there is no need for it in the function body?

Let’s break this down. The value of magit-bury-buffer-function is a function.[^1]

(defcustom magit-bury-buffer-function 'magit-restore-window-configuration
  "The function used to bury or kill the current Magit buffer."
  :package-version '(magit . "2.3.0")
  :group 'magit-buffers
  :type '(radio (function-item quit-window)
                (function-item magit-mode-quit-window)
                (function-item magit-restore-window-configuration)
                (function :tag "Function")))

Looking at the code of magit-restore-window-configuration, we can see that it accepts an optional argument.

(defun magit-restore-window-configuration (&optional kill-buffer)
  "Bury or kill the current buffer and restore previous window configuration."
  (let ((winconf magit-previous-window-configuration)
        (buffer (current-buffer))
        (frame (selected-frame)))
    (quit-window kill-buffer (selected-window))
    (when (and winconf (equal frame (window-configuration-frame winconf)))
      (set-window-configuration winconf)
      (when (buffer-live-p buffer)
        (with-current-buffer buffer
          (setq magit-previous-window-configuration nil))))))

Thus param in mu-magit-kill-buffers is only there to match the signature of the function passed to magit-bury-buffer-function. If I leave it out, I will get this error message:

magit-mode-bury-buffer: Wrong number of arguments: ((t) nil "Kill all Magit buffers." (let ((buffers (magit-mode-get-buffers))) (magit-restore-window-configuration) (mapc #'kill-buffer buffers))), 1

If you’re wondering why I am using the sharp quote (#') when setting the value of magit-bury-buffer-function, you can simply trust the sage advice of Artur Malabarba.

There is still one problem to solve. Setting magit-bury-buffer-function this way makes q always kill every Magit buffer. This is not what I need when I am using, for instance, magit-log-buffer-file.

Hence it’s better to make my custom function interactive and apply it only for magit-status-mode-map:

(defun mu-magit-kill-buffers ()
  "Restore window configuration and kill all Magit buffers."
  (interactive)
  (let ((buffers (magit-mode-get-buffers)))
    (magit-restore-window-configuration)
    (mapc #'kill-buffer buffers)))

(bind-key "q" #'mu-magit-kill-buffers magit-status-mode-map)

Bonus point: the unused param is gone.

Refactoring power-ups

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 10 Feb 2018 00:00:00 +0000

Any programmer knows the importance of refactoring. It’s even hard to believe a programmer can live without it. There are plenty of use cases for refactoring, but the following happens often enough that I am glad Emacs sits next to me every day.

Imagine you are working on a medium-to-big size project. You have functions everywhere, maybe constants here and there to make your life easier. Functional programmers have no time for variables, so I won’t go down that road.

At one point you discover a function that could use a different name. Clarity, readability, or just mere kindness towards your fellow co-workers prompts you to come up with something better. Naturally, the function is used in many places around the codebase, so it’s time to bring out the heavy guns.

There are plenty of ways to solve this problem, especially in Emacs, but this is how I approach the situation:

C-c p s r brings up counsel-projectile-rg
If point is on the function name, I just hit M-n to use it as the search term, otherwise I type it in
C-c C-o now runs ivy-occur and all the candidates end up in a dedicated buffer
C-x C-q, bound to ivy-wgrep-change-to-wgrep-mode, makes the new buffer editable. It’s easy to remember because it’s the same key binding to enable Wdired from Dired
C-s invokes counsel-grep-or-swiper and I type in the function name
M-q takes me to swiper-query-replace, and I just need to enter the new function name, hit RET and then C-c C-c to confirm my modifications
C-x s followed by ! is all it takes now to save the files involved in my refactoring

If it looks like a lot to remember, well, it is. Only the first times, though. After a while it becomes second nature, and editing an occurrence in multiple files feels like a gentle breeze down your neck.

Projectile and Ivy/Counsel/Swiper are really invaluable tools.

Inspecting log files with Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 11 Nov 2017 00:00:00 +0000

As a software developer, I cannot avoid log files. Application servers and LAMP machines are always around the corner waiting for me, so I must accept log files and do my best.

There are two kinds of log files I work with:

static: the server wrote the content and never touched the file again
dynamic: the server keeps appending content as the monitored process continues

The log files could be on my hard disk or located on a remote machine. During my workflow, a “remote machine” can also be a Docker container.

I leave the math to you, but it should be clear that different combinations arise. Luckily, with Emacs everything goes smoothly and I can move seamlessly across any scenario.

When it comes to static files there are no surprises. If the log file is local, inspecting it with counsel-grep-or-swiper is pretty much all I need. Since I rarely need to modify a log file, I usually enable read-only-mode with C-x C-q to prevent accidental edits. For a remote static file, the same easily applies thanks to TRAMP.

Things get more interesting with dynamic logs. On local files, with auto-revert-mode I can see the changes in the buffer as soon as the underlying file changes. If I want something fancier, auto-revert-tail-mode behaves like the good old tail -f. Dynamic remote logs, however, require a different approach. Activating auto-revert-mode is not enough, I also need to set auto-revert-remote-files to t for the desired behaviour.

What if years of tail -f made you totally indifferent to such niceties? You can follow Michael Albinus suggestion and use dired-do-shell-command in Dired.

Actually, you can even improve a little on his tip. Leave the ending & out, and go straight with dired-do-async-shell-command which in Dired is aptly bound to &. Refer to the manual for further details: Shell Commands in Dired.

Magit, the one and only

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 09 Nov 2017 00:00:00 +0000

Nowadays it is basically impossible to land in a group of Emacs enthusiasts without someone talking rapturously about the wonders of Magit. If you listen closely, the words resemble a chant: “You wish you could do it with Git, until you experience the great Magit.”

Be warned: the following story goes along those magic lines.

Magit makes me look back at my experiences with CVS, SVN and Mercurial and laugh about my clumsiness with tools like Tortoise. Before Magit, I touched the regular Git command-line interface for simple tasks such as cloning a repository, always scared away by the large number of options at my disposal. I had to deal with Eclipse’s own Git client when I was working with Java, but please let me spare you the gruesome details.

Magit has never been so necessary and useful as it has been since I started my new job back in April. Git is our only version-control sytem, and the command-line is still the preferred tool in the office. Not for me, though. Magit has become a natural extension of pretty much all of my coding.

I regularly create branches, being it for an issue to fix or a new feature to implement. If the project is based on gitflow, we are covered in Magit thanks to magit-gitflow. Otherwise, rebasing and merging on master are just a few key bindings away.

Although impressive, it is not only a matter of speed. Magit taught me more about Git than every tutorial out in the wild. Especially when it comes to rebasing and cherry-picking, both of which are hard to get wrong now. Rewording a commit, exploring the repository history, dealing with submodules: it all makes sense through an interface that could not be more helpful.

The one thing against Magit I have for the haters is this:

(unbind-key "C-c C-w" git-commit-mode-map)

That binding is my prefix for Eyebrowse. Not much of a complaint, I know.

Magit brings order, balance and elegance to the powers of Git. It is the only version-control system I need.

Simplify my Docker workflow with Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Thu, 19 Oct 2017 00:00:00 +0000

Up until a few weeks ago, I had never messed with Docker. Not that I had anything against it per se, but never before had I felt the need to isolate my work in containers that can be readily built up and torn down.

Docker and its helpful companion Docker Compose come with a rich command-line interface. Nonetheless, I don’t want to leave Emacs for simple tasks such as building a Docker image or preparing the containers with Docker Compose.

Fortunately, the Emacs ecosystem is ready to help. Four packages have improved my workflow with Docker:

The first two packages add syntax highlighting, completion and a bunch of useful key bindings to work with Dockerfile and docker-compose.yml.

The real magic, though, happens with docker-tramp. The beauty of interacting directly with the contents of a container is impressive. Combine docker-tramp with the handy completion of counsel and the power of Dired and you might feel like Henry Dorsett Case in his ecstatic hunt for the Neuromancer.

Through docker-tramp I can also run EShell on any available container and that is where eshell-bookmark shines. I just have to bookmark a remote EShell buffer and use counsel-bookmark to jump back to it. Managing containers hardly gets any faster than this.

A little advice if you use both counsel and eshell-bookmark: do not set counsel-bookmark-avoid-dired to t, otherwise selecting a bookmark with counsel-bookmark will take you to counsel-find-file instead of opening the desired EShell buffer.

To shell or not to shell

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 07 Oct 2017 00:00:00 +0000

As much as most of my daily workflow revolves around Emacs, I always have GNOME terminal ready to fly with Fish shell and tmux. I keep EShell next to me for quick tasks, but I have never relied on shell-mode or ansi-term for other CLI-intensive work.

I don’t know what happened to the lovely “Emacs Chat” series from Sacha Chua, but more than three years ago she interviewed Mickey Petersen. Mickey talked with great enthusiasm about shell-mode and at the time I admittedly made a mental note about giving it a try. Regretfully, I have only recently come back to that note.

My first M-x shell didn’t look that great. I haven’t debugged the compatibility issues with Fish, probably something related to my heavily customised config.fish. Anyway, falling back to Bash is enough.

(validate-setq explicit-shell-file-name "/bin/bash")

Note that I am using validate-setq as I have already explained

Another thing I have noticed is the lack of colours for the output of ls. Fortunately, Emacs StackExchange has an answer for that, so I have added this line to my .bash_aliases file:

alias ls="TERM=ansi ls --color=always"

The input echoing is easily turned off following the instructions on the manual. Also, the history is much cleaner and easier to navigate with counsel-shell-history.

(unbind-key "C-c C-l" shell-mode-map)
(bind-key "C-c C-l" #'counsel-shell-history shell-mode-map)

Note that unbind-key and bind-key are macros from bind-key.el, which is part of the fantastic use-package.

Last but not least, I like to have my shell buffer filling the whole window in the current frame. Thus, display-buffer-alist to the rescue.

(validate-setq
 display-buffer-alist
 `(
   ;; … other stuff …
   (,(rx bos "*shell")
    (display-buffer-same-window)
    (reusable-frames . nil))
   ;; … other stuff …
  ))

Taming closing delimiters in my s-expressions

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 17 Sep 2017 00:00:00 +0000

As I explained when I wrote about my daily Clojure workflow I rely heavily on Smartparens for my editing. With Lisp-like languages in particular, I enable smartparens-strict-mode to keep my s-expressions balanced even when I happen to use delete-char or kill-word dangerously near a closing parenthesis.

I have sp-kill-sexp bound to C-M-k, however out of habit I often use C-k to kill a line, which in my configuration is set up as Artur Malabarba explained. Doing that in the middle of an s-expression creates unnerving chaos.

Smartparens comes with a handy binding to temporarily disable the enforced balancing and let me insert a closing delimiter. Just pressing C-q followed by the desired matching parenthesis brings the order back.

Unfortunately, it’s not always that easy. Take this snippet which appears at the end of a ClojureScript function:

(when-not (empty? @data)
            [:div
             {:style {:padding "1em" :text-align "center"}}
             [graph]])]]))))

Carelessly hitting C-k near [graph] disrupts an otherwise elegant s-expression. I could undo, of course, but what if after C-k I do other kill-and-yank edits?

This is exactly why I have come to love syntactic-close.

(use-package syntactic-close            ; Automatically insert closing delimiter
  :ensure t
  :bind ("C-c x c" . syntactic-close))

As soon as I discover an unbalanced s-expression, I can use C-c x c as many times as needed to add back the right closing delimiters.

A better workflow with workspaces

manuel.uberti@inventati.org (Manuel Uberti) — Wed, 02 Aug 2017 00:00:00 +0000

I am not a big fan of workspaces on my desktop environments, maybe because to me Alt-Tab is enough. To be honest, I was using workspaces back in my Ratpoison days, but that is not the case any more.

Nevertheless, my daily workflow in Emacs improved so much with eyebrowse I can’t imagine going back to a configuration without it.

(use-package eyebrowse                  ; Easy workspaces creation and switching
  :ensure t
  :config
  (validate-setq eyebrowse-mode-line-separator " "
                 eyebrowse-new-workspace t)

  (eyebrowse-mode t))

As you can see, I am pretty much leaving eyebrowse with its default settings. I removed the comma that was used as a separator between the workspace numbers and made switching to a new workspace start from the *scratch* buffer.

Now my daily workflow in Emacs is thus organised:

Workspace #1: this is dedicated to my GTD project, which simply follows the steps Nicolas Petton describes in Orgmode for GTD.
Workspace #2: this is for Clojure and ClojureScript development, so everything from CIDER to project specific Magit buffers and EShells ends up here. In the rare case I need to work on a different project, I create a new workspace.
Workspace #3: this is the “I need a break!” place. Elfeed is my preferred choice for a quiet and informative distraction. Otherwise, if I just want to hack on my Emacs configuration I do it here.

Combined with Projectile, eyebrowse is the definitive piece of the puzzle I was missing to have an optimised work environment.

Every feed in its right place

manuel.uberti@inventati.org (Manuel Uberti) — Tue, 01 Aug 2017 00:00:00 +0000

Writing about Christopher Wellons’ elfeed is the least I can do to describe how thankful I am for this gem, especially since it’s one of the Emacs packages I use the most.

Up until last month, Twitter was useful to keep in touch with the IT and the film criticism communities. However, for a while I had been finding myself in dire need of a vacation from social media. The amount of time lost in pointless time-line scrolling looking for the latest hip comment screamed to be spent otherwise.

I have always been a fan of RSS feeds, because having the news aggregated in one place spares me the time of wandering the Internet. Twitter fought against my feeds, giving the impression it was offering more up-to-date content along with the false promise of an interaction that in fact was rarely happening.

Before elfeed, I tried my luck with different feed readers. Since a carefully tmux-ed terminal window is always part of my daily workflow, I fell in love with Newsbeuter a couple of years ago.

However, as any Emacs fanatic would tell you, why leave the comfort of your favourite text editor for something as mundane as RSS feeds?

elfeed is more than a Newsbeuter replacement, though. Tags, filters and the power of Emacs beneath its lean interface make feeds management easier than ever. It’s also trivially extensible. Look at this simple trick to mark all the feeds read when I am feeling too lazy.

(defun mu-elfeed-mark-all-read ()
  "Mark all feeds as read."
  (interactive)
  (call-interactively 'mark-whole-buffer)
  (elfeed-search-untag-all-unread))

(bind-key "R" #'mu-elfeed-mark-all-read elfeed-search-mode-map)

elfeed sorts feeds by time, with the most recent on top. This had been a bit confusing at first, as I was used to having the feeds grouped by items with Newsbeuter. Nevertheless, after a while this approach felt more natural, maybe because it reminds me of the Twitter time-line.

RSS feeds are an essential tool in this age of perennial distractions. Having them readily available at my fingertips is invaluable.

Keeping your .emacs.d clean

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 17 Jun 2017 00:00:00 +0000

How often do you have a look at your .emacs.d directory? If you’re anything like me, not that often. It’s no wonder then that upon opening it I was horrified to see it cluttered with all sorts of files from all the packages I regularly use.

Jonas Bernoulli, of Magit fame, must be feeling similar concerns. Otherwise, why did he come up with a package like no-littering?

Installation is trivial, especially if you use the great use-package:

(use-package no-littering               ; Keep .emacs.d clean
  :ensure t
  :config
  (require 'recentf)
  (add-to-list 'recentf-exclude no-littering-var-directory)
  (add-to-list 'recentf-exclude no-littering-etc-directory))

No extra setup is required. Place this snippet somewhere at the beginning of your init.el file and you are set. Use Emacs for a while and then go back checking .emacs.d: nice, huh?

To be honest, I wiped out my .emacs.d directory and started from fresh with no-littering installed. Too much, maybe, but I was eager to see how good this package is. And yes, it is good.

House-cleaning has never been so easy.

Dynamically change font size in Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Sun, 26 Feb 2017 00:00:00 +0000

I take my Emacs configuration with me on every computer I use. I also plug a big external display —and the awesome Das Keyboard 4 Ultimate— during long coding sessions, so it is only natural that I have to tailor my setup to accommodate different font sizes.

Being the customizable editor that Emacs is, it wasn’t hard to devise a neat trick to please my needs.

First, a simple function to set the default fonts.

(defun mu-setup-main-fonts (default-height variable-pitch-height)
  "Set up default fonts.

Use DEFAULT-HEIGHT for default face and VARIABLE-PITCH-HEIGHT
for variable-pitch face."
  (set-face-attribute 'default nil
                      :family "Source Code Pro"
                      :height default-height)
  (set-face-attribute 'variable-pitch nil
                      :family "Fira Sans"
                      :height variable-pitch-height
                      :weight 'regular))

Now I just have to call this function with the proper values for :height according to the screen size.

(when window-system
  (if (> (x-display-pixel-width) 1800)
      (mu-setup-main-fonts 150 160)
    (mu-setup-main-fonts 130 140)))

Of course, more specific settings for various display resolutions are just a cond away.

Automatic language detection for Flyspell

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 04 Feb 2017 00:00:00 +0000

I am always looking for new ways to improve my Emacs experience. Months ago, it happened to my spell-checking configuration thanks to the work of Nicolas Petton.

(defvar mu-languages-ring nil "Languages ring for Ispell")

(let ((languages '("en_GB" "it_IT")))
  (validate-setq mu-languages-ring (make-ring (length languages)))
  (dolist (elem languages) (ring-insert mu-languages-ring elem)))

(defun mu-cycle-ispell-languages ()
  (interactive)
  (let ((language (ring-ref mu-languages-ring -1)))
    (ring-insert mu-languages-ring language)
    (ispell-change-dictionary language)))

This handy code lets me cycle quickly through the languages I need in Flyspell. However, wouldn’t it be easier if Emacs was capable of automatic language detection?

That’s the hole the guess-language package fills.

(use-package guess-language         ; Automatically detect language for Flyspell
  :ensure t
  :defer t
  :init (add-hook 'text-mode-hook #'guess-language-mode)
  :config
  (setq guess-language-langcodes '((en . ("en_GB" "English"))
                                   (it . ("it_IT" "Italian")))
        guess-language-languages '(en it)
        guess-language-min-paragraph-length 45)
  :diminish guess-language-mode)

Notice how I set guess-language-langcodes. It has to be set this way to make guess-language work with my setup for Hunspell.

Support for different languages and language detection for multiple languages in the same document are provided out of the box. guess-language is still young, but it’s already making spell-checking in Emacs so much easier.

Format XML in Emacs

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 03 Dec 2016 00:00:00 +0000

Since I deal with many SOAP web services for work, I also have to deal with lots of XML files. In the application server log they usually appear on one line, which makes the reading unnecessarily painful. Fortunately, Emacs coupled with the handy xmllint comes to the rescue.

First, I installed xmllint with: sudo apt-get install libxml2-utils

Now I could format my XML buffers with: C-x h C-u M-| xmllint -format - RET

However, this is Emacs, so there is always a more productive way to solve problems. Why should I have to input the options for xmllint or remember the necessary key bindings all the times?

(defun mu-xml-format ()
  "Format an XML buffer with `xmllint'."
  (interactive)
  (shell-command-on-region (point-min) (point-max)
                           "xmllint -format -"
                           (current-buffer) t
                           "*Xmllint Error Buffer*" t))

Since I only need this utility in XML buffers, I bound it for nxml-mode-map.

(use-package nxml-mode                  ; XML editing
  :mode "\\.xml\\'"
  :bind (:map nxml-mode-map
              ("C-c m f" . mu-xml-format))
…

Scala in Emacs with ENSIME

manuel.uberti@inventati.org (Manuel Uberti) — Tue, 01 Nov 2016 00:00:00 +0000

As an amateur Clojure developer, I am particularly fond of CIDER. It brings everything I need to program with Clojure right inside my favourite text editor.

Therefore, when I approached Scala one of the first things I did was looking for something similar to CIDER. I hate leaving Emacs for programming tasks, so having it ready for Scala was paramount. Fortunately, it did not take me long to find my way: ENSIME was right around the corner.

ENSIME supports the famous sbt build tool, and the documentation gently guides you through all the necessary steps to achieve a working setup. It is really a matter of minutes.

A nice trick I grabbed straight from Sam Halliday init.el is:

(remove-hook 'post-self-insert-hook
             'scala-indent:indent-on-parentheses)

(sp-local-pair 'scala-mode "(" nil
               :post-handlers '(("||\n[i]" "RET")))
(sp-local-pair 'scala-mode "{" nil
               :post-handlers '(("||\n[i]" "RET") ("| " "SPC")))

This code lets the awesome Smartparens take care of parentheses in Scala buffers. Another handy solution comes from Sebastian Wiesner:

(defun mu-scala-pop-to-sbt (new-frame)
    "Open SBT REPL for this project, optionally in a NEW-FRAME.

Select the SBT REPL for the current project in a new window.  If
the REPL is not yet running, start it.  With prefix arg, select
the REPL in a new frame instead."
(interactive "P")
;; Start SBT when no running, taken from `sbt:command'
(when (not (comint-check-proc (sbt:buffer-name)))
  (sbt:run-sbt))
(let ((display-buffer-overriding-action
       (if new-frame '(display-buffer-pop-up-frame) nil)))
  (pop-to-buffer (sbt:buffer-name))))

(with-eval-after-load 'scala-mode
  (bind-key "C-c m s" #'mu-scala-pop-to-sbt scala-mode-map))

I just started my journey with Scala but I can safely say ENSIME could be the perfect companion.

Schema validation for my Emacs configuration

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 17 Sep 2016 00:00:00 +0000

Maintaining an ever-growing Emacs configuration is both fun and exhausting. It is easy to forget why I picked that value for a variable or how in the name of Elisp that weird snippet ended up in my init.el. The more packages I install to extend my beloved text editor, the harder it is to keep track of all the changes the prolific authors put out every day.

Artur Malabarba must understand my frustration pretty well, or at least that was my first reaction to his recent validate library.

The library has a pretty neat API, which I am sure will turn out to come in handy for all the Elisp developers out there. However, so far I have been focusing on the validate-setq macro only. validate-setq adds validation to the regular setq, making it super-easy to catch mistakes that can be surprisingly hard to find.

An example:

(use-package nrepl-client               ; Client for Clojure nREPL
  :ensure cider
  :defer t
  :config (validate-setq nrepl-hide-special-buffers 'yes))

If I evaluate this expression, I get a clear error message:

Error (use-package): nrepl-client :config: Looking for ‘(boolean)' in
‘yes' failed because: not a boolean

I was setting a lot of variables before the related package was required. I also found settings for variables that do not exist any more. Why Emacs was not catching these errors upon loading is still an ongoing investigation.

validate is available on GNU ELPA. Do not miss it.

Adding CHICKEN Scheme support to Flycheck

manuel.uberti@inventati.org (Manuel Uberti) — Sat, 23 Jul 2016 00:00:00 +0000

There is no need for me to tell you how great Flycheck is. If you do not trust me, at least trust Mickey Petersen on this.

Since I have been playing around with CHICKEN Scheme for quite some time now, it seemed only natural to wish for on-the-fly syntax checking. Why limit myself to wishing, though? Why do not push it a little further and try to help Flycheck maintainers?

Before starting any coding, I took the time to read the Contributor’s Guide. Like all of Flycheck documentation, the Contributor’s Guide is well-written and easy to understand. The guidelines about pull requests and commit messages, in particular, put me on the right track.

I forked the Flycheck’s repository and started going through the code in flycheck.el. The lack of experience brought me to shamelessly copying the Racket checker and trying to figure out how it worked. It was not too hard to understand, but maybe starting with the Perl checker — see here — would have been a better choice. Nonetheless, I stole the idea of having Geiser as a requirement from the Racket checker.

Anyway, it was not time to code yet. I needed to understand if on-the-fly syntax checking in CHICKEN Scheme would be possible at all. Flycheck gives you the power to work with different syntax checkers within the same interface, but I didn’t know of a similar checker for CHICKEN Scheme.

With some help on the #chicken IRC channel and from Vítor De Araújo on Twitter, I was able to devise my first attempt and create the proper pull request.

And that is when the real magic started.

I knew Flycheck maintainers are kind and helpful because I had already had some chances to interact with them, but I cannot remember the last time I worked on something with this kind of patient assistance.

Questions promptly answered, suggestions readily available. My code kept getting better and better. Useless lines were removed, documentation was added and the integration test felt like the right thing to do.

I learnt a lot and could not be happier with the result. I hope I will be able to contribute to Flycheck again. Moreover, I do hope every project I wish to contribute to can follow the Flycheck’s community example.

Now go enjoy your on-the-fly syntax checking with CHICKEN Scheme.

Spell-checking with Hunspell and flyspell-correct

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 06 Jun 2016 00:00:00 +0000

In order to simplify the portability of my Emacs setup, I devised a useful shell script to install everything my needs.

Recently I abandoned aspell in favour of hunspell, so the script has been updated accordingly. However, hunspell needs some dictionaries to work with and they are not readily available as Debian packages, but as LibreOffice Extensions. Therefore, I just need to copy the files over to /usr/share/hunspell.

A quick test with hunspell -D shows all is set up correctly.

$ hunspell -D
[…]
AVAILABLE DICTIONARIES (path is not mandatory for -d option):
/usr/share/hunspell/en_GB
/usr/share/hunspell/it_IT
/usr/share/hunspell/en_US
[…]

Emacs Lisp takes care of the rest.

(setq ispell-program-name (executable-find "hunspell")
      ispell-dictionary "en_GB")

I write both in English and Italian, so the spell-checker must be able to switch dictionary on demand.

(bind-key "C-c I"
          (lambda ()
            (interactive)
            (ispell-change-dictionary "it_IT")
            (flyspell-buffer)))

(bind-key "C-c E"
          (lambda ()
            (interactive)
            (ispell-change-dictionary "en_GB")
            (flyspell-buffer)))

To make things nicer, flyspell-correct makes Flyspell propose the suggested corrections via the always reliable Ivy.

(use-package flyspell-correct-ivy
  :ensure t
  :demand t
  :bind (:map flyspell-mode-map
              ("C-c $" . flyspell-correct-word-generic)))

Recentre the buffer when leaving Swiper

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 30 May 2016 00:00:00 +0000

I always talk enthusiastically about Ivy. As a once heavy Helm user, I remember being afraid of regretting the complete switch to Ivy after a few days. It did not happen, and since I made the move I have only found Ivy — and the related packages Swiper and Counsel — consistently getting better and better.

Swiper has soon become my preferred in-buffer searching tool. Only one minor thing was disturbing me. After selecting the right candidate with RET, the screen scrolled unpredictably at the top, centre, or bottom of the buffer.

This is due to calculations behind the scenes about windows size, as Oleh Krehel explained here. Fortunately, he was kind enough to introduce a handy defcustom.

;; Always recentre when leaving Swiper
(setq swiper-action-recenter t)

Now every time I leave Swiper the screen is left centred. Furthermore, it is possible to keep the screen centred even during candidate selection in Swiper by pressing C-M-n or C-M-p instead of C-n or C-p.

I do not mind the scrolling when Swiper is active, but I do like having my eyes focused on one point of the screen when I find what I am looking for.

Ignore some buffers in Ivy

manuel.uberti@inventati.org (Manuel Uberti) — Mon, 23 May 2016 00:00:00 +0000

If you use the great company-statistics to improve your experience with company-mode, chances are that you already noticed an entry called company-statistics-cache.el when you switch buffers with your favourite key binding.

Hitting RET on company-statistics-cache.el could result in unpleasant consequences. In my case, Emacs hangs indefinitely, distracting me from my work and forcing me to a horrible restart.

Fortunately, Oleh Krehel introduced a new value for ivy-use-ignore-default: 'always.

;; Always ignore buffers set in `ivy-ignore-buffers'
(setq ivy-use-ignore-default 'always)
;; Ignore some buffers in `ivy-switch-buffer'
(setq ivy-ignore-buffers '("company-statistics-cache.el"))

With the above setup, company-statistics-cache.el will never sneak in your buffer switching again.