Daw-Ran Liou's website

The Biggest Positive for Emacs

2021-03-18T00:00:00Z

I came across the interview with Henrik Lissner, the creator of Doom Emacs, and it really resonated with me about the biggest positive for Emacs (starting at 48:37):

The biggest positive for Emacs, hands down (that addresses all its negatives) is self-documenting, which primarily means documentation is a first-class citizen in ELisp. You can easily look it up any variable, function, macro, face, whatever, even something that’s not defined in ELisp but defined in the C code you can look it up. […]

If you use Emacs you’re living in a REPL: you have direct, unfeathered access to its guts. And if you want to know anything about the current state of Emacs, you can just ask it directly. That’s something I don’t think any other editors can do quite at that level.

Living inside the REPL (or working inside a running program) is such a powerful technique in programming. That’s also one of the reasons drove me towards Emacs after learning Clojure, even though the two LISPs have very different ideals or philosophies.

Rewriting My Emacs Config

2020-11-06T00:00:00Z

Since the last post, I had switched over to Doom Emacs for a while and then, hopefully, have switched back to my hand-crafted emacs config for the last time. I wanted to try Doom for some reasons:

I didn’t like the startup time of my previous handcrafted emacs config,
I found painful to look at my emacs config, and
I wanted to learn more from this very successful community-driven project.

Even prior to switching over to Doom, I took a lot of inspirations from it to enhance my config. One main frustration of using Spacemacs was its think layers of abstracts. I didn’t find such frustration with Doom. Doom is very well documented and stays true to its mantras:

Close to metal. There’s less between you and vanilla Emacs by design. That’s less to grok and less to work around when you tinker. Internals ought to be written as if reading them were part of Doom’s UX, and it is!

Trying various modules, it’s fun exploring various pre-configured packages without the hustle to configure them pre-maturely. As an example, I like the org module just work out of the box with various of plugins.

However, eventually I grew tired of looking at all the keybindings that I wasn’t using. All the keybindings and functionalities that I wasn’t using, or didn’t spark joy in me, made me sad. For every single unused keybinding, it is an extra mental burden in my workflow. If I get rid of all the unnecessary keybindings I could improve the efficiencies on the ones I use most often, because I no longer need the long nested key strokes anymore.

Also, I found the System Crafters YouTube serious Emacs From Scratch. It really was a godsend to me to help me start writing my Emacs config again. My current Emacs Config drew a lot of inspirations from it and from the author’s, David Wilson’s, own config.

So far, I really like that I have total control over my emacs configuration, and the start time wasn’t too terrible either.

Links: - Doom Emacs - Emacs From Scratch - My current Emacs Config - My current Emacs theme

Advise Eglot to Support Clojure Monorepo Setup

2022-03-28T00:00:00Z

Updates 2022-03-28: A Better Solution

Since I published the original solution, I've found certain things were not working as I claimed. There's a better solution, which is mentioned shortly in this section, without hacking Emacs lisp code. Because my intent to write this article is less about giving you the solution but more about demonstrating a way to tweak Emacs' package to fit your own desires, I decided to keep its original content alive, with the hope that it would still be insightful to some of you.

Here's the updated solution! Since clojure-lsp issue #752, clojure-lsp uses the classpath to discover the source code to analyze. The trick is to merge all the classpaths from the monorepo's sub-projects. Conveniently, lein-monolith provides a way to Merge Source Profile. Therefore we can invoke the command lein monolith with-all classpath instead. Your clojure-lsp configuration file that goes to <monorepo-root>/.lsp/config.edn should look like this:

{:project-specs [{:project-path "project.clj"
                  :classpath-cmd ["lein" "monolith" "with-all" "classpath"]}]}

Note that if you have a large monorepo, you might need to bump the eglot-connect-timeout to a larger number to let clojure-lsp finish analyzing all the source code. I set my eglot-connect-timeout to 600 currently.

The following is the original content.

Abstract

The advice system and dynamic scoping are two powerful facilities in Emacs. In this article, I'll show you how to use them to tweak Emacs' behaviors and facts to workaround the eglot package while setting up clojure-lsp for a monorepo.

Background

In Emacs, there are two popular LSP clients: lsp-mode and eglot. Although historically, there were more noticeable differences between the two packages in terms of their usage and their UI, these days, I'm pretty happy with both of them. I can achieve pretty minimal UI in lsp-mode (as eglot always is 🙂) by tweaking several custom settings, and both work well with built-in packages, which I've grown accustomed to over the years.

Over the past few years of using Emacs, I started to prefer the class of packages that work very closely with the Emacs' built-in facilities instead of inventing their isolated world¹. Such packages provide a narrow focus that enhances a specific part of Emacs. I love this class of packages because I can simply reject a dependency if it's not essential to my workflow. Therefore, I decided to hop back from lsp-mode to eglot for its simplicity.

Because of clojure-lsp's limitation on discovering source code (issue #191 and issue #551) with the lein-monolith setup and my needs at work, I didn't change the :project-paths setting as others did (e.g., this comment and this gist). Instead, I run a different clojure-lsp server session for each sub-project. In lsp-mode, this can be done by customizing the project root the first time launching the clojure-lsp. Next, I'll show you the issue I faced using eglot and how to teach it (or advise it 😉) to work around it.

Problem

When eglot starts the clojure-lsp server, it infers² the project root by utilizing the project.el built-in package. Out of the box, Emacs consider the project root to be the current version-controlled root directory. If you are using git, the project root is the parent folder of the .git/ folder. While this inference is correct most of the time, I want this to be different for my monorepo project at work, which has the directory structure like this:

root/
  |--- .git/
  |--- projects.clj
  |--- project-a/
  |      |--- projects.clj
  |      |--- src/
  |--- project-b/
  |      |--- projects.clj
  |      |--- src/
  .
  .
  .
  |--- project-n
         |--- projects.clj
         |--- src/

The root/ is the root of our monorepo, which uses the projects.clj file and lein-monolith to tie all of its sub-projects together. All sub-projects are version-controlled together under root/. The root/ project itself does not contain any source code, whereas the sub-projects do.

With this setup, editing any source file in any sub-project will connect to the clojure-lsp server session at root by default. The question is: how to tweak eglot to use the sub-project root as the clojure-lsp server session?

Solution

I came up with this solution that ensures the eglot-ensure function will try to locate the clojure-project-dir as the project root when launching an LSP session. If clojure-project-dir isn't found, it falls back to using the version-control root to launch the LSP server.

;; My personal settings that you might not require
;;(add-hook 'clojure-mode-hook 'eglot-ensure)
;;(custom-set-variables '(eglot-connect-timeout 300))

(defun project-try-clojure-project (dir)
  "Try to locate a Clojure project."
  (when-let ((found (clojure-project-dir)))
    (cons 'transient found)))

(defun find-clojure-project-advice (orig-fun &rest args)
  "Fix project-root for the clojure monorepo setup."
  (let ((project-find-functions
         (cons 'project-try-clojure-project project-find-functions)))
    (apply orig-fun args)))

(advice-add 'eglot-ensure :around #'find-clojure-project-advice)

But how does this work?

Teaching Emacs new tricks by giving it dynamic advices

Aspect-Oriented Programming page on Wikipedia:

In computing, aspect-oriented programming (AOP) is a programming paradigm that aims to increase modularity by allowing the separation of cross-cutting concerns. It does so by adding additional behavior to existing code (an advice) without modifying the code itself, instead separately specifying which code is modified via a "pointcut" specification, such as "log all function calls when the function's name begins with 'set'".

I only learned the concept of AOP because of Emacs. It fits surprisingly well for a plug-in system in programs like Emacs. The users of Emacs are empowered to enrich their experience with third-party packages and are empowered to hack the behaviors (functions) of any package from afar through the advice system without touching the source code of those packages.

Not only are the behaviors hackable, but the facts (variables) are also modifiable thanks to Dynamic Scoping. Dynamic Scoping gives the Emacs users the power to change variable bindings with a dynamic extend.

(defun project-try-clojure-project (dir)
  "Try to locate a Clojure project."
  (when-let ((found (clojure-project-dir)))
    (cons 'transient found)))

Here we define a backend for the project-find-functions. If a clojure-project-dir is found, project-try-clojure-project returns the tuple (transient . <PROJECT DIR PATH STRING>), otherwise nil. This function's signature will satisfy as an element in the project-find-functions. However, we don't want to change the behavior across the board. We want to limit the scope of the modified project-find-functions variable. So we use a let-binding to change the dynamic scope:

(defun find-clojure-project-advice (orig-fun &rest args)
  "Fix project-root for the clojure monorepo setup."
  (let ((project-find-functions
         (cons 'project-try-clojure-project project-find-functions)))
    (apply orig-fun args)))

The find-clojure-project-advice function binds the project-find-functions variable with the project-try-clojure-project function as the first element in the list. This binding only exists to the extent of this function call. Therefore, invoking project-current function under other contexts will not be affected.

(advice-add 'eglot-ensure :around #'find-clojure-project-advice)

Lastly, we use the add-advice to advise the eglot-ensure function to invoke the find-clojure-project-advice. The :around keyword denotes that we want to compose the advising function (find-clojure-project-advice) around the advised function (eglot-ensure) so the let-binding can enter the dynamic scope of eglot-ensure.

Conclusion

To recap, this article:

Provides an alternative way of setting up clojure-lsp with the eglot LSP client when working with a monorepo,
Demonstrates how to use Aspect-Oriented Programming and Dynamic Scoping in Emacs.

Without modifying any source code of Emacs or its packages, we can change the behavior (the eglot-ensure function) and the fact (the project-find-functions variable) to satisfy a specific use case while keeping other parts of Emacs intact. I think this is a great example to showcase why Emacs is so powerful and valuable to its users.

Footnotes

This philosophy plays well with my favorite programming language, Clojure. The community has learned to work together by creating single-purpose libraries that strongly prefer to use Clojure data as the universal language.↩︎
eglot--guess-contact is the internal function that makes this inference.↩︎

Compiling Emacs from Source on MacOS Big Sur

2021-11-09T00:00:00Z

Recently I started to compile the Emacs master branch from source for daily use instead of using one of the popular formulas on Homebrew.¹ It’s pretty cool to try the latest features like the native compilation and the native emoji before the stable releases. Also it’s quite a satisfying experience to be able to compile Emacs from source. It took me several tries to get it right but I think I documented everything. Here are the steps:

Install dependencies

libxml2
Optional for native compilation
- gcc
- libgccjit

brew install libxml2 gcc libgccjit

Follow the post-installation instruction from libxml2 to fix the path and environment variables.

If you need to have libxml2 first in your PATH, run:
  echo 'export PATH="/usr/local/opt/libxml2/bin:$PATH"' >> ~/.zshrc

For compilers to find libxml2 you may need to set:
  export LDFLAGS="-L/usr/local/opt/libxml2/lib"
  export CPPFLAGS="-I/usr/local/opt/libxml2/include"

For pkg-config to find libxml2 you may need to set:
  export PKG_CONFIG_PATH="/usr/local/opt/libxml2/lib/pkgconfig"

Compile

I configured my Emacs with the following options. I’m not exactly sure what each meant but this combination seems to work on my machine:

--with-cairo - enable Cairo drawing
--with-imagemagick - enable ImageMagick support
--with-xwidgets
--with-native-compilation - enable native compilation

./autogen.sh
./configure --with-cairo --with-imagemagick --with-xwidgets --with-native-compilation
# Build MacOS App bundle, `install` doesn’t actually install anything.
make clean install

The Emacs.app App bundle should now be in the nextstep/ directory. Simply copy it to the /Applications folder to use it.

References

Footnotes

Probably the popular options are: emacs-mac, emacs-plus, and emacs-head. I was mostly using emacs-mac in the past.↩︎

Rethink Syntax Highlighting

2020-11-06T00:00:00Z

Update 2021-02-28: My color themes are now released! Check it out!

A screenshot of my current editor theme - sketch-white

I’m a minimalist when it comes to how I like to highlight my code - my code editor is usually almost monochromatic, just black, white, three shades of gray, and an accent color like orange. If those colors sounds a lot to you, I have to assume you either are an extreme minimalist in code highlighting or you’ve never give code highlighting a second thought and just use whatever the theme creators throws at you. If you are the latter, this post is for you.

A screenshot of my alternative editor theme - sketch-black

We live in a world of distractions. Everything is constantly trying to grab your attentions, your text messages, phone notifications, emails, social medias, ads, also your friends and families. It is because: your attentions are, indeed, valuable. We too often got distracted, not because we are bad at focusing, (maybe some of us are), but more importantly, the world around us is constantly demanding our attentions. When everything’s in focus, nothing actually is. When everything are signals, every one becomes a noise.

Same as your code syntax highlighting. When every single text is highlighted with different colors, they are all just distractions and noises. Take a look at the Alabaster theme by tonsky:

A screenshot of alabaster theme

I like how the motivations describes:

Most color themes highlight everything they can, ending up looking like a fireworks show. Instead, Alabaster uses minimal highlighting; it defines just four classes: * Strings * All statically known constants (numbers, symbols, keywords, boolean values) * Comments * Global definitions

This makes a lot of sense to me. The reason that we even need syntax highlighting to begin with is because we, the programmers rather than the machines, need to parse the text differently when we read it. For example, we don’t even need to parse the comments when reading code. Strings are in a sense very similar to code comments. Strings are usually for the end users, not the programmers. When I saw a string in code, I usually just skim through it and make a mental note that “there’s a string here.”

Personally I don’t like to highlight numbers, symbols, and keywords in code because those to me are just parts of the code. I don’t want them to stand out too much because I still need to read them. I don’t need additional visual aids to help me understand they are different from the rest of the code. There used to be a time that I embolden the keywords and highlight the global definitions, but now I’ve made a conscious decision that leaving keywords unstyled works better for me. I do have global definitions embolden because I like them to stand out a little more.

How I like to highlight my code aligns with how I think about code. Your mileage might vary. But remember this: less is more. The less colors you use will have greater impacts. Have some thoughts about your syntax highlighting. How do they help you in your work flow? Do you really need all the colors to help you program? It’s pretty easy to customize color themes and syntax highlighting for pretty much all the major code editors. Try building your own color theme if necessary.

Cheers!

Structural editing in vanilla Emacs

2021-10-23T00:00:00Z

Strict structural editing

Last time I switched from the lispy/lispyville combo for structural editing s-expressions to paredit for its simplicity. However, I started to realize that I kept unbinding commands from the paredit-mode-map such as C-d, C-k because they were unnecessarily restraining. Quote from this reddit thread:

I tend to think that all of the slurping, burping, gurgling, snorting, and barfing, which devotees consider handy, are just contrivances to try to make a virtue out of necessity. From the moment that you’ve automatically, prematurely introduced a closing paren, you naturally find a need to try to find a way to work around it. If you don’t box yourself in, in the first place, then there’s no such need.

I still do premature paren closing with electric-pair-mode in my current setup. However, this thread really got me thinking. “Do I really want to have balanced parenthesis at all times, at all costs?” To answer the question, I ask myself: a) What problems does it solves, and b) What are the costs?

To me, the main cost is the freedom of expressing experimental code as I laid out in the Back to paredit post.

I think the main problem it solves is to “Avoid uncompilable source files by accident.”

However, I don’t care much about this problem nowadays since I don’t often edit the source code line-by-line or character-by-character and unbalanced parens are rarely an issue. Whenever I do accidentally introduce unbalanced parens, I can usually quickly spot the error and fix it¹. It isn’t very hard once I learn to navigate and edit S-exps, which I’ll show in the next section.

From there, it’s a simple decision to ditch paredit and the strict structural editing rules it imposes and revise my workflow with vanilla Emacs commands.²

S-expression workflow in vanilla Emacs

For the code examples in the following sections, I’ll be using <!> as the point, also known as the cursor or the caret, and <@> as the mark.

Navigate S-exp

Here are the ones I use most often: - C-M-d - Go down the S-exp tree - C-M-u - Go up the S-exp tree - C-M-f - Go forward to the next S-exp at the same level - C-M-b - Go backward to the previous S-exp at the same level - C-M-a - Go to the start of the top-level S-exp (or the previous top-level S-exp) - C-M-e - Go to the end of the top-level S-exp (or the next top-level S-exp)

I don’t use these that often because they kinda overlap with C-M-(f|b) in a way: - C-M-n - Go to the next S-exp - C-M-p - Go to the previous S-exp

I often use the navigation commands to quickly put the point at the beginning of the S-exp or the end of the S-exp. This is quite important because the next few operations require the point to be at the right spot.

Example (point is <!>, mark is <|>):

(+ (+ 1 2<!>) 3 4)

After hitting C-M-u:

(+ <!>(+ 1 2) 3 4)

Mark S-exp

C-M-<SPC> - mark-sexp (Mark the S-exp after the point)

Example:

(+ <!>(+ 1 2) 3 4)

Hit C-M-<SPC> the first time will mark the first S-exp following the point, i.e. (+ 1 2).

(+ <!>(+ 1 2)<@> 3 4)

Hit C-M-<SPC> the second time will mark the next two S-exps, i.e. (+ 1 2) 3.

(+ <!>(+ 1 2) 3<@> 4)

Kill S-exp

C-M-k - Kill S-exp after the point

When I’m working on lispy languages, I rarely use C-k to kill stuff. I use line-based navigation commands + the S-exp navigation commands to locate the opening paren than do C-M-k. I found this method more precise than using C-k.

Example:

(+ <!>(+ 1 2) 3 4)

After hitting C-M-k,

(+ <!> 3 4)

Drag S-exp

C-M-t - Drag downward
C-M-- C-M-t - Drag upward

Dragging downward is almost equivalent to transposing. The only difference is that transposing requires the point to be after the S-exp to be dragged downward.

Example:

(+ (+ 1 2)<!> 3 4)

After hitting C-M-t:

(+ 3 (+ 1 2)<!> 4)

In the case of dragging upward, I usually kill the S-exp and then yank it to the position I want. Alternatively, using the negative argument with transposing does it too.

Example:

(+ 3 (+ 1 2)<!> 4)

After hitting C-M-- C-M-t:

(+ (+ 1 2)<!> 3 4)

Wrap S-exp

This requires the electric-pair-mode. To do wrapping, I’ll place the point at the beginning of the S-exp(s) that I want to wrap, press C-M-<SPC> to mark the following few S-exp(s), and then hit the opening paren ( (or ", [, {) to wrap the S-exp.

Example:

(+ <!>(+ 1 2) 3 4)

Mark the next two S-exp by hitting C-M-<SPC> twice

(+ <!>(+ 1 2) 3<@> 4)

Hit ":

(+ "<!>(+ 1 2) 3" 4)

Raise S-exp

By default, Emacs doesn’t bind the raise-sexp to any keys. In my current setup, I bind this to:

C-M-r

Example:

(+ <!>(+ 1 2) 3 4)

After hitting C-M-r:

(+ 1 2)

Splice S-exp

Splicing is really a special case of raising S-exp - basically, it “raises” all the sibling S-exps. So my workflow is to use C-M-<SPC> to select all the siblings and then hit C-M-r to raise all of them.

Example:

(+ <!>(+ 1 2) 3 4)

Mark the next three S-exp with three C-M-<SPC>s.

(+ <!>(+ 1 2) 3 4<@>)

Hit C-M-r:

<!>(+ 1 2) 3 4

Slurp & barf

There are no equivalent commands out-of-the-box. However, I don’t miss those commands much. In the case of slurping, I can just remove the closing paren, forward one S-exp, and then insert the closing paren back:

Example:

(+ (+ 1 2)<!> 3 4)

DEL:

(+ (+ 1 2<!> 3 4)

C-M-f:

(+ (+ 1 2 3<!> 4)

Insert ):

(+ (+ 1 2 3)<!> 4)

Alternatively, kill the next S-exp and yank it before the closing paren.³

Conclusion

I think the more I work on lispy languages, the better I become at working with S-exps. Previously, I had to rely on the external packages’ safety nets to edit the source code safely. Nowadays, I think I’m dangerous enough that I feel more productive without those safety nets. 😈

I think my experiment so far has been a success. I’ve been using the revised workflows for my day-to-day work for a while, and vanilla Emacs is all I need to be productive at navigating and editing lispy code.⁴

Footnotes

With the help of M-x check-parens and show-paren-mode.↩︎
I also came across the blog Why is Paredit is so un-Emacsy? after the switch. It’s a nice read! It kinda reassured me of my decision.↩︎
I might be able to write a function to automate slurping and barfing in the future. Stay tuned!↩︎
I also ditched evil-mode and learned code editing the Emacs way. That’s a story for another time.↩︎

Back to paredit

2021-08-14T00:00:00Z

To simplify my s-exp workflow

I had been using lispy and lispyville for general s-expression editing and navigation previously. My setup works pretty well, but I often found the packages are a bit of a feature bloat. Plus, I don’t use most of the transitive dependencies (ace-window, counsel, ivy, swiper, hydra). Over time, I started to realize what I like or want and what I don’t care about for my workflow. I decided to switch to a lighter package to help me to build the workflow. So here we are, back to the good old paredit, again, for its simplicity.

Here’s a list of features I actually want to use:

S-exp navigation
Killing s-exp
Closing parentheses automatically
Slurping and barfing s-exp
Wrapping and unwrapping (or splicing) s-exp
Dragging (or transposing) s-exp

Surprisingly, vanilla Emacs already supports half of the list! By default, C-M-(f|b|u|d|n|p) bounds to the s-exp navigation commands; C-M-k kills s-exp; C-M-t transposes s-exp that acts sort of like dragging s-exps. So I only need paredit to fill in the rest of the list.

To not-handle parentheses

I recently came across this reddit thread, which gave me a new perspective about handling parentheses for lispy languages. Actually, it’s about how not handling parentheses. The constraint of keeping parentheses balanced all the time is surprisingly unnecessary and restrictive. Without this constraint, I started finding myself enjoying a lot more freedom in my REPL workflow. For example, when I have the Clojure code:

(-> data
    transform-1
    transform-2
    transform-3
    transform-4)

(let [a 1
      b 1
      c (+ a b)
      d (+ b c)
      e (+ c d)]
  ;; some more computation
  )

To inspect the transformation, I can temporarily insert unbalanced closing parentheses and code and then evaluate the code by putting the point at -!-:

(-> data
    transform-1
    transform-2)-!-  ; eval this s-exp
    transform-3
    transform-4)

(let [a 1
      b 1
      c (+ a b)] c)-!-  ; eval this s-exp
      d (+ b c)
      e (+ c d)]
  ;; some more computation
  )

Once I got the results, removing the temporary code is all it takes to have perfectly balanced parentheses again.

This is more or less the same as using cider-eval-sexp-up-to-point, but I don’t want to memorize too many lesser-used keybindings. Plus, I prefer workflows that are more generic to other lispy languages.

To do this, I unbound a couple of commands from the paredit-mode-map, such as C-d and DEL. C-k is sometimes useful to delete code in bulk, so I still keep it bind to the paredit-kill command.

However, unlike what the reddit thread mentioned, I still find automatically inserting paren pairs helpful. This is probably because I work a lot in Clojure, which considers square brackets [] and curly braces {} as valid s-exp as well as parentheses (), so there are multiple ways to close an s-exp. Also, it’s one less keystroke to type 😛.

My Emacs Clojure Development Environment Overview

2020-11-12T00:00:00Z

Preface

To me, Emacs isn’t a text editor but rather an extremely flexible development environment that allows anyone to optimize their workflow. I used to be a Vim user and did everything inside the terminal: Vim for code editing, bash commands for running/testing code, and git cli for all other git operations. I wasn’t in any sense a Vim superuser. However, I felt pretty comfortable to do most of my day-to-day work inside the terminal.

For the past two years, I got into the Clojure programming community and made a very audacious move to learn Emacs at the same time. To me, learning Emacs was just as hard, if not harder, as learning Clojure itself. However, learning either subjects has paid off far more than I had expected. In this post, I will share an overview of my current development environment setup and explain my rationale of some of the key bindings that I use.

Magit - git porcelain

Magit is one of the most powerful powerful packages available on Emacs. It is also the package that made me rethink my entire workflow. If you don’t known, Magit is a git porcelain that makes all the fancy git operations within Emacs. I used to enjoy doing all git operations inside terminal. I rarely do it lately because of how great Magit is. If I were to stop using Emacs for writing code, I’d definitely continue using Magit until I find another comparable tool.

I bind magit-status to command+g (also <SPC> g g because of old habit using Doom Emacs.)

Cider - advanced Clojure integrated environment

I use Cider to manage the nrepl sessions and to evaluate code. I used to rely on Cider for more things like looking up code definition but lately I’ve been experimenting that with clojure-lsp which I’ll describe in the next section.

I bind the Cider keys under a local leader key <,>, which is only available in the clojure(script)-mode. This is a habit I developed during the time using Spacemacs and Doom Emacs though their keymaps are slightly different. Currently I only use it to evaluate code in three levels - to evaluate buffer, evaluate top-level vars, and evaluate s-expression. They are currently bound to <,> e b, <,> e f, and <,> e e, which I’ll probably simplify by removing the middle e later.

LSP - code jumping

LSP is the text editor-agnostic protocol for IDE-like operations. It separates the concerns of those IDE-like capabilities and the actual implementation. For example, the LSP defines the capability of textDocument/definition and the clojure-lsp implements how to find the definition of a particular Clojure symbol. In Emacs, AFAIK there are two packages to support LSP interactions, lsp-mode and eglot. I’ve tried both in the past but I’m sticking with lsp-mode at the moment.

I bind command+l to the lsp-keymap-prefix while I’m still learning it. So far I only need two functions: lsp-find-definition and lsp-find-references which are bound to command+l g g and command+l g r respectively. I’ll definitely re-bind those keys for easier access.

Lispy + Lispyville - general lisp s-expression editing

I use Lispy and Lispyville for most of the e-expression editing in Clojure mode instead of using smartparens or paredit or parinfer. I like the safe evil operations that are remapped by Lispyville so I don’t need to worry about unbalanced parens. However, I don’t use a lot of the keys other than slurping, barfing, and dragging s-expressions.

Dired - file management

I bind dired to <SPC> d with just two key strokes for easier access. Dired mode was a powerful package that I overlooked for so long. It finally came into my radar thanks to the amazing video by David Wilson. Dired was truly a missing piece in my workflow centered around Emacs. Having the ability to browse the filesystem naturally inside the Emacs buffer was absolutely a joy.

Eshell - direct shell access

This is bound to <SPC> e also for easier access. With all the packages above, there are rarely things I need to do directly in shell. For those things that has to be done inside shell, I usually do it in Eshell. However, there are times I do need something closer to the native terminal app on OSX, something I can start a long running process and bury it in the background. In these cases I’ll launch vterm instead. However, for some those off tasks like compiling code or start a docker container in the background, I prefer Eshell.

Links: - My current Emacs Config - Magit - Cider - clojure-lsp - lsp-mode - eglot - Lispy - Lispyville - David Wilson - System Crafters

My personal experience to learn Clojure and Emacs together

2021-07-19T00:00:00Z

I recently made a bit lengthy response in the Clojureverse discussion on the topic “GNU Emacs + Cider vs VS Code + Calva”. To summarize:

I recommend learning Emacs.
I recommend learning Emacs and Clojure at the same time. It’s going to be very challenging and fun and rewarding.

Quote:

Hi, I just want to provide another data point here. I started learning Clojure using my own free time back in 2018Q3 while having a full-time software engineering job in Java + Python. I picked up Emacs (Spacemacs at the time) around 2018Q4 for no particular reason other than I always gravitate toward ancient technologies. There’s just something about the aesthetics that I love about old technologies. I watched a few Clojure talks using Emacs on YouTube at the time and thought Emacs was pretty cool, and thought I wanted to be like those Clojure Emacs people. I was fairly fluent in Vim keybindings before that, so Spacemacs made the transition a bit easier.

There were lots of challenges to overcome to learn Clojure and Emacs at the same time. And oh boy, that was a lot of fun! I think both learning Clojure and learning Emacs are very rewarding experiences to me. The more time I spent on it, the more knowledge I gained, the more powerful I felt. I really think Clojure and Emacs are the two best things ever happen to my developer career so far.

I’d say that I got pretty fluent in Clojure by 2019Q4 when I got my first and current Clojure full-time position but was still a beginner Emacs. Today, I feel pretty comfortable rocking my own Emacs configuration without using any off-the-shelve Emacs distribution. I can read and write ELisp code (but not so fluently) and know a couple of tricks to debug/troubleshoot issues with 3rd party packages.

One benefit I found from learning Clojure and Emacs(Lisp) at the same time is that many of the concepts are transferable to one another. For example, the REPL driven development I love doing in Clojure is right there for you in Emacs, a highly moldable and inspectable Lisp machine like your Clojure REPL. Also, I couldn’t grasp the idea of dynamic vars in Clojure until I learned it from Emacs Lisp.

I know that the general sentiment towards Emacs is that it is too hard, and I get that. But I mean, what’s fun in learning it if it’s just easy? After using Emacs as my daily driver for almost 3 years, I am still having fun learning bits and bits about Emacs.

Don't kill my xref buffers

2023-02-12T00:00:00Z

I like buffers.

When I first started using Emacs, I used to feel paranoid about keeping too many buffers. Nowadays, I don't even notice the hundreds or thousands of buffers buried in Emacs.

I like xref.

The built-in package, xref, is an essential part of my workflow at Kira Systems (now acquired by Litera). We use a monorepo setup for our flagship Machine Learning contract analysis SaaS product written in Clojure and Go. It's crucial for my day-to-day work to be able to do project-wide searches for references. I use the project-find-regexp (a command from the built-in package, project.el, bound to C-x p g) to find matches for references in both Clojure and Go code. If I'm only interested in the Clojure source code, I can use xref-find-references (bound to M-?) to find all references with eglot.

There's one problem. xref doesn't like buffers.

Or every time the commands invokes xref, they reuse the *xref* buffer and effectively destroyed the results of the previous reference search.

Of course, this is Emacs. We can configure it ourselves. All it requires is a little gentle advice:

(with-eval-after-load 'project
  (defun project-find-regexp-with-unique-buffer (orig-fun &rest args)
    "An advice function that gives project-find-regexp a unique buffer name"
    (require 'xref)
    (let ((xref-buffer-name (format "%s %s" xref-buffer-name (car args))))
      (apply orig-fun args)))

  (advice-add 'project-find-regexp :around
              #'project-find-regexp-with-unique-buffer))

(with-eval-after-load 'eglot
  (defun xref-find-references-with-eglot (orig-fun &rest args)
    "An advice function that gives xref-find-definitions a unique
buffer name when eglot is enabled."
    (if (bound-and-true-p eglot--managed-mode)
        (let ((xref-buffer-name (format "%s %s"
                                        xref-buffer-name
                                        (symbol-at-point))))
          (apply orig-fun args))
      (apply orig-fun args)))

  (advice-add 'xref-find-references :around
              #'xref-find-references-with-eglot))

By leveraging Emacs's advice-function facility and dynamic scoping, the Elisp code above customize the existing project-find-regexp and xref-find-references to use a more descriptive buffer name for each invocation. The result is that I get to keep multiple xref reference buffers till I finish using those.

The configurability of Emacs is often brought up as the top reason to use Emacs. Yes, it took some time to traverse the source code of eglot.el, package.el, and xref.el. Still, the customization described in this article can be done without a deep knowledge of the Emacs source code or individual packages.

To me, this article is a perfect example of how Emacs adapts to the user's workflows instead of forcing the user to adapt to the editor's (or package authors') ideology. I hope this short article inspires you to start customizing your Emacs experience. Cheers! :)

From Vim to Emacs

2020-04-06T00:00:00Z

I was a Vim user a couple years back. I totally loved (and still love) the philosophy of Vim as well as the hjkl navigation. In contrast, Emacs didn’t make any sense to me. C-v for page down and M-v for page up? Does that even make any sense to anyone?

Yet here I am, after all those years, writing this article on my Emacs with all the keybinding craziness. I must confess, I enjoy Emacs quite a lot. However, the transition wasn’t easy for me. Here’s my journey so far.

The start of the cycle

In the mid 2018 I started teaching myself Clojure, a dialect of the Lisp family. I fell in love with the language but the thing that amazed me the most, was how the Clojure community do all the amazing presentations using Emacs. “Well,” I told myself, “maybe it’s time to finally see the other side of the Vim vs Emacs Editor War.”

I learned the basics from the Clojure for the Brave and True website, It turned out that learning Clojure and Emacs at the same time was too audacious for me at the time. Clojure itself alone already has a pretty steep learning curve. And then there was Emacs… I took a more strategic route and focus on Clojure solely for a while (using both VSCode and IntelliJ.) It was fine at the time (because I didn’t know what I was missing.)

Only knowing the foundamentals of Clojure, I started working on opensource projects to gain more real world experiences. It was then I was introduced to Spacemacs.

Into the Space

Spacemacs, on the website:

Spacemacs is a new way to experience Emacs – a sophisticated and polished set-up focused on ergonomics, mnemonics and consistency.

To me, the main selling point was the exceptional out-of-box configuration. The layer system makes adding packages almost no-brainers. And plus, I didn’t need to give up my Vim keybindings! Spacemacs truely made me start liking Emacs and wanted to explore more aspects of Emacs.

After learning a few basics, I was able to get pretty productive using Spacemacs and started understanding the superpower of Clojure, the REPL + Editor integration workflow. The “mnemonics” aspect of Spacemacs also made discovering and memorizing the useful functionalities so much easier.

I also made a switch to the develop branch of Spacemacs at the time because of a lot of the features and customizations can only be done there. I was learning quite a bit from both the official documentation and from Practicalli’s spacemacs tutorial.

Then, it was the late 2019’s that I started my first professional job as a Clojure/Script developer. During the first week at work I saw my collegue’s minimalistic Emacs init.el file that also uses evil-mode (which is the configuration that gives you the access to all the Vim keybindings.) I was pretty amazed by it.

Using Clojure and Spacemacs day in and day out, I wasn’t completely satisfied with the fact that I can only understand Emacs through the lense of Spacemacs. And so, just last week, I started diving into Emacs.

Embracing the Evil

Aaron Bieber has a great talk on “Evil Mode: Or, How I Learned to Stop Worrying and Love Emacs”. He helped me to set the right mindset from the start. I don’t really want to ditch all the keybindings, just yet. I also watched a lot of Mike Zamansky’s Emacs tutorials. It felt like an achievable goal to recreate the Spacemacs experiences myself.

Actually, someone has already done it:

Suyash Bire talked about Spin Your Own Spacemacs-lite
Bacterial Finches wrote about How to build your own spacemacs
And here’s a repo for Spacemacs-Lite

Those resources are awesome. They gave me so much hope that I knew my goal of making my own mini Spacemacs was an achievable project.

I really learned a lot in this stage. One of the most important lessons I learned is:

Emacs is a self-documenting editor

Instead of needing to go to Google to search for answers, Emacs has all those things built-in for you. Just like Clojure, I was given the tool I need to solve my problems. Learning a few commands and I was very well-suited to troubleshoot my editor. This is very powerful.

So far I’ve got most of the things I want working. You can check out the code here. Currently it’s about 500 LOC and I wrote every line of the code. I feel very good about it. If something isn’t working right, I know where to fix it (most of the time.)

To infinity and beyond

Emacs is truely an amazing piece of software that I had so much fun with. The reason it pushed me away in the first place was its out-of-box configuration. It required me to have opinions on almost every aspect of the editor on day one, and this intimidated me.

Spacesmacs was a godsend for me when I needed it the most. Till today, the way of Spacesmacs influences a lot of my opinion toward my Emacs configurations. I’m not giving up the things I like about Spacesmacs.

However, will I ever ditch Evil mode and embrace the holly form of Emacs? Maybe.

On Learning Emacs

2020-11-13T00:00:00Z

Classical learning curves for some common editors

I once came across a Tweet telling people how to use Emacs like this: step 1, download Emacs; step 2, spend the next 10 years configuring it. At first, this seems pretty silly, yet, there are some truths in it. I, for one, didn’t spend 10 years before becoming comfortable using Emacs as my daily driving horse in software development. However, I could very well imagine that after 10 years I’d still be tinkering my Emacs config with a sense of satisfaction.

In retrospect, I found it amusing that both of my two favorite tools in software development, i.e. Clojure and Emacs, don’t seem to care much about the friendliness for newcomers. Yes, the community is very welcoming. However, the tools themselves are pretty demanding for the newcomers. Clojure required a huge leap of faith to unlearn most of my previous OOP experiences, whereas Emacs required me to design my own text editor from scratch and to have some understanding of the ELisp programming language. Neither of them promise newcomers to “hit the ground running” or “learn it over the weekend”.

In my observation, the whole software industry puts too much spotlight on “the latest and the greatest” things. FOMO, the fear of missing out, has fueled a culture of desiring speed. The easiness of learning has become an advertising term for many of the software tools such as libraries and languages. However, the effectiveness of a tool would eventually outweigh the difficulty to learn it in the long run. If I saved myself 15 minutes for using Emacs every day at work, I already saved myself 65 hours last year. That is almost three extra days an year. Even if I initially had spent a full week do nothing but learning Emacs, I would still start seeing the payoffs in the third year, as well as the rest of my life. The math isn’t really important here. To be honest with you, I don’t think I merely saved 15 minutes a day for using Emacs. The important thing is this - the ROI of learning a new tool is a long game. The longer you stick with it, the less significant the initial investment is. What’s more important is the capability of the tool itself.

That brings me to the next key point: Emacs isn’t just a text editor. Some people think Emacs as their operating system. I like to think Emacs as an integrated development environment. Modern software development usually involves multiple tools: text editor, compiler, interpreter, repl, test runner, version control system, database client, or the browser. Every project is different and there is no one single IDE will meet all needs. We reach different tools for different purposes and inevitably are forced to make context switches. Context switches break our development flow. It’s draining for me to constantly reaching for a different tool with different key bindings or requires me to use the mouse. I really would prefer to stay inside one tool with the same universal key bindings all the time.

When I started off learning Emacs, I tried to find the best and most conventional way to set it up. I was also feeling wrong for using the Vim key bindings rather than the default Emacs key bindings. This idea seems silly to me now for there should be no one true way of using Emacs. Every one is using Emacs differently, with different background, under different context. I use a different keyboard than most people I know. I have a Planck keyboard that only has 50 keys. A lot of the special characters I cannot type without a modifier key already. I couldn’t afford to hit a key chord that requires hitting multiple modifier keys plus a special character. Something like C-M-$ would be pretty humanly impossible to press with one hand. I’m glad Emacs is flexible enough to fit my needs.

To recap, here’s my key points: 1. The effectiveness of a tool would eventually outweigh the difficulty to learn it in the long run. 1. Emacs is an integrated development environment rather than a text editor. 1. There’s no one true way of using Emacs.