Irreal: Clean Screen Writing

There’s a certain type of writer—mostly prose writers, I’d guess, but others too—who don’t want to be distracted by extraneous information from their editor. They don’t want to see the name of the file they’re editing, what line they’re on, or, in Emacs terms, what mode they’re in. They don’t want a mode line or anything else. The metaphor they’re seeking is the blank sheet of paper.

I remember coming across this same idea years ago; so many years ago I was still using WordStar for non-programming editing. I didn’t understand it then and I don’t understand it now. Knowledge is power, after all, and I never saw the benefit of unnecessarily doing without it1.

Needless to say, not everyone agrees. A few years ago, Bastien Guerry showed how to achieve a blank screen in Org mode. Now Pete Corey is doing the same thing in Spacemacs (although his approach will, mutatis mutandis, work with any Emacs configuration) using Olivetti. Corey’s approach isn’t limited to Org mode. He likes the blank screen even when he’s coding so he’s arranged for his mode to be active in text-mode and prog-mode buffers.

Most folks probably wouldn’t want such a setup but if you do, Corey shows how easy it is to obtain it with the help of Olivetti.



To be fair, I do use diminish to get rid of some minor modes but that’s mostly so that I can see all the important information on the mode line.

-1:-- Clean Screen Writing (Post jcs)--L0--C0--September 22, 2018 03:28 PM

Irreal: Why You Should Buy Into the Emacs Platform

I’ve been seeing a lot of references to Christoffer Stjernlöf’s (slightly old) post on Two Wrong about Why You Should Buy Into the Emacs Platform. It seems to me to offer a nice coda to my two posts on ancient editors. It fits in with that discussion because it looks at another reason to spend the time to learn and master Emacs.

The TL;DR is extensibility but that characterization misses the point of what Stjernlöf is saying. His thesis is that Emacs is really a framework for writing text-based tools. That means that it can be—if you like—more than an editor. You can use it to read mail, follow your RSS feed, play music, and all sorts of other things. But even considered as a text editor, the ease with which you can write editing tools is a powerful benefit.

Gosh, that fancy editor over there has this feature called multiple cursors. You don’t have to switch editors or beg maintainers to add the feature to Emacs, you can do it yourself just as Magnar Sveen did. What this means is other editors can’t be more powerful because whatever feature makes them seem that way can be added to Emacs relatively easily (Sveen had a first hack at multiple cursors working after just 2 hours). It can be added by an individual user even if no one else cares about or is interested in the feature.

Isn’t that a capability you’d like your editor to have? Different people have different needs and priorities but to my way of thinking that capability alone makes it worthwhile to spend the time mastering Emacs.

-1:-- Why You Should Buy Into the Emacs Platform (Post jcs)--L0--C0--September 20, 2018 05:44 PM

sachachua: 2018-09-17 Emacs news

Links from, /r/orgmode, /r/spacemacs, Hacker News,, YouTube, the changes to the Emacs NEWS file, and emacs-devel.

-1:-- 2018-09-17 Emacs news (Post Sacha Chua)--L0--C0--September 17, 2018 07:49 PM

Marcin Borkowski: Emacs directory variables

Many people know and use Emacs file variables. I think less people know about a similar concept of directory variables.
-1:-- Emacs directory variables (Post)--L0--C0--September 17, 2018 08:18 AM

Marcin Borkowski: Persisting Emacs variables

Some time ago I coded a certain Elisp tool (for internal use at Wiadomości Matematyczne) and I needed to preserve the value of some variable between Emacs sessions. I asked how to do this on the Emacs mailing list, and I received a whole lot of very interesting and worthwhile responses.
-1:-- Persisting Emacs variables (Post)--L0--C0--September 10, 2018 07:56 AM

Chen Bin (redguardtoo): Wucuo, a Emacs spell checker that works with camel case code

Now it's possible to spell check camel case code in Emacs using wucuo.

Setup is easy. Add (wucuo-start) into ~/.emacs, then use flyspell as usual.

Flyspell could use either aspell or hunspell. No extra setup for aspell or hunspell is required.

Wucuo starts an independent process to check camel case words. So your original flyspell setup is still valid.

For example, you could still use Spanish and English dictionaries in your existing flyspell setup.

Two flag wucuo-aspell-language-to-use and wucuo-hunspell-dictionary-base-name are used and only used to check camel case word through independent process.

Wucuo is generic enough to handle any programming language if its major mode inherits from prog-mode.

Even if the major mode does not inherit from prog-mode, it's still simple to use wucuo.

You only need find font face the camel case word is used by running M-x wucuo-current-font-face. Say the font face is js2-function-call.

Then we need setup wucuo-personal-font-faces-to-check,

(setq wucuo-personal-font-faces-to-check '(js2-function-call))

That's all.

Some optional tools to help you manage personal dictionaries:

  • M-x wucuo-create-aspell-personal-dictionary creates plain word dictionary ~/.aspell.en.pws for aspell
  • M-x wucuo-create-hunspell-personal-dictionary creates plain word dictionary ~/.hunspell_en_US for hunspell

BTW, please don't start flyspell-prog-mode when using wucuo.

Any suggestion is welcomed. For example, currently wucuo only check English camel case word. Ping me if you want to use other languages.

-1:-- Wucuo, a Emacs spell checker that works with camel case code (Post Chen Bin)--L0--C0--September 07, 2018 12:39 PM

sachachua: 2018-09-03 Emacs news

Links from, /r/orgmode, /r/spacemacs, Hacker News,, YouTube, the changes to the Emacs NEWS file, and emacs-devel.

-1:-- 2018-09-03 Emacs news (Post Sacha Chua)--L0--C0--September 03, 2018 11:00 PM

emacsninja: Fixing My #1 Annoyance With Emacs Lisp

Ah, Emacs Lisp. There are many reasons for loving and hating it. I disagree with most people name when they argue why the language sucks[1], for me it’s mostly two things that end up mattering in practice:

  1. The APIs are terrible. Font-locking is an enigma. It’s common for packages to use synchronous APIs because it’s far easier to do than The Right Thing™. Moving through buffers and editing them makes for incomprehensible and stateful code. I could go on, but most of these can be mitigated by writing your own APIs as you figure things out. This is not what this blog post is about.
  2. There is no namespace or module system. This means that every global identifier could end up clashing with another one unless you emulate namespacing by adding a unique prefix. While this could be fixed, it’s unlikely to happen[2]. Interestingly enough this situation is similar to C, but worse as there’s no visibility control, only the convention of using a double dash for global identifiers not considered public. This annoys me as I have to type out a potentially long prefix every time. This is what this blog post is about.

I initially considered one of the namespace packages. It would make for as little typing as possible, however this would require an additional dependency and break my existing workflows. Therefore I went for the alternative route, writing a command that inserts the package prefix of the current buffer at point. Bind that command to an easily reachable key binding and you’d save nearly as much effort with typing.

(defvar-local my-current-package-prefix nil)

(defun my-ensure-trailing-dash (string)
  (if (and (not (zerop (length string)))
           (not (= (aref string (1- (length string))) ?-)))
      (concat string "-")

(defun my-guess-current-package-prefix (arg)
    (goto-char (point-min))
    (if (and (not arg)
             (re-search-forward "^(defgroup \\(\\w+\\)" nil t))
        (setq my-current-package-prefix
              (my-ensure-trailing-dash (match-string 1)))
      (setq my-current-package-prefix
             (read-string "Package prefix: "

(defun my-insert-current-package-prefix (arg)
  (interactive "P")
  (when (or (not my-current-package-prefix) arg)
    (my-guess-current-package-prefix arg))
  (insert my-current-package-prefix))

(with-eval-after-load 'elisp-mode
  (define-key emacs-lisp-mode-map (kbd "C-.")

Guessing the prefix is done by looking for a (defgroup ...) form which is a good enough indicator for a prefix[3]. In case it’s not given, the above code prompts for a prefix and allows resetting it with a prefix argument. The trickiest part is ensuring the prefix ends with a dash. You could optimize this even further by looking whether a prefix has already been inserted, but honestly, undoing the change is simple enough.

Let’s see whether this reignites my drive to write more Emacs packages…

[1]Who cares if it’s slow? Who cares about the lack of regex literals? Yes, it’s not <insert your favorite language>. Despite all of this people wrote lots of it, far more than any of the haters would. Feel free to dream about an Emacs rewritten in something else, but it’s going to stay a pipe dream if that’s all you do. The topic deserves a separate blog post because it’s a common phenomenon in the Emacs community to place irrational hopes in a re-implementation to succeed the status quo.
[2]The topic came up on emacs-devel before, the main problem is that the tooling would need to be updated. Simple workflows the core team is used to (such as grepping the qualified name) would completely break apart.
[3]An even better indicator would be the :prefix option inside (defgroup ...), but let’s not go overboard.
-1:-- Fixing My #1 Annoyance With Emacs Lisp (Post Vasilij Schneidermann)--L0--C0--August 26, 2018 06:12 PM

Flickr tag 'emacs': Move

Lil' Mersereau posted a photo:


-1:-- Move (Post Lil' Mersereau ( 17, 2018 03:16 PM

Flickr tag 'emacs': You&Me

Lil' Mersereau posted a photo:


-1:-- You&amp;Me (Post Lil' Mersereau ( 14, 2018 07:48 PM

Emacs café: The new Indium

Now that Indium 2.0 is around the corner, it’s about time to write this post!

You can see this article as the third part of my series of articles describing how to make Emacs a JavaScript development environment. If you haven’t read it yet, you should jump to the first and second post first to get started.

About Indium 2.0

Indium 2.0 is not out yet, but if you’re installing Indium from MELPA, you’re already using it.

Indium is a JavaScript development environment for Emacs. It connects to a runtime (Browser or Node), and provides things like a REPL, inspector, live evaluation, and of course a stepping source debugger.

Indium debugger in action

New project configuration

The upcoming release of Indium will feature much better project configuration with sourcemap support for most, if not all JavaScript projects, including React, VueJS, Meteor, Angular, and basically any project that uses Webpack or other bundlers that produce sourcemaps.

New client/server architecture

The new Indium will also be based on a client/server architecture, and will require the installation of the indium server like the following:

npm install -g indium

There are several reasons for this change, the most important one being the ability to reuse existing JavaScript libraries for handling WebSockets, source-maps and the Chrome Debug Protocol.

You can read the documentation of the new TCP protocol here.

As a result, Indium will be much more responsive.

Setting up Indium

Let’s start with the creation of a React project built with the CLI tool create-react-app.

sudo npm install -g create-react-app
create-react-app my-app
cd my-app
npm install
npm start

We need to tell Indium how to connect to our new project my-app. To do that, let’s create a .indium.json file at the root of the project:

  "configurations": [
	  "name": "Web Browser",
	  "type": "chrome",
	  "url": "http://localhost:3000"

We only need one configuration, but Indium supports any number of configurations per project, including mixing NodeJS and Chrome.

Firing up Indium

To start Indium, you can either do M-x indium-connect to connect to a running JavaScript process (Chrome tab the example above), or do M-x indium-launch to start a new process and automatically connect to it.

For more information about setting up and starting Indium, read the Getting up and running section of the documentation.

Closing words

The new architecture of Indium is brand new, and I expect issues to be discovered. You can open issues on the GitHub issue tracker (please do!).

If you are unsure how to best report an issue for Indium, there’s a section in the manual for that!

-1:-- The new Indium (Post Nicolas Petton)--L0--C0--August 14, 2018 10:00 AM

Raimon Grau: Adopting org-gcal.el

I just wanted to announce that I recently adopted org-gcal.

This great emacs mode imports google calendar events to your org files, and has some support for exporting events to your google calendars.

The author went missing in action for more than a year, and there were some nasty bugs in master that made the initial experience quite disappointing. Most of the bugs had Pull Requests opened, but still pending to be merged. So I decided to adopt the package to give it some love, and since last week, the melpa link points to my repo instead of @myuhe's.

Big props to the original author and also the many users of the module that helped with the migration.

If you use org-gcal, my recommendation is to update the package, and it will only improve your experience. There's an ongoing big refactoring that uses oauth2.el to manage all the tokens and oauth, but it still have issues that I haven't figured out how to solve in an elegant way.
Of course, if you have suggestions (or even better, code) for org-gcal, please direct them to .
-1:-- Adopting org-gcal.el (Post Raimon Grau ( 12, 2018 10:33 PM

Trey Jackson: I'm so out of it

I didn't even realize that Emacs 26.1 was released 3 months ago!
-1:-- I'm so out of it (Post Trey Jackson ( 08, 2018 02:56 PM

emacspeak: Using Emacs Threads To Execute Commands Asynchronously

Using Emacs Threads To Execute Commands Asynchronously

1 Executive Summary

Emacs 26 has threads for executing functions asynchronously. Emacs
commands that call an external process and wait for that process to
finish make a good candidate for asynchronous execution — e.g.,
smtpmail-send-it for sending mail. The arrival of threads provides
an interesting option for running such commands asynchronously.

2 First Attempt — Custom Async gnus Command

I initially wrote a custom command for launching gnus asynchronously
— it was a one-line function that ran the following:

(make-thread #'gnus)

The above worked well — except when command gnus needed user input
— so I just had to be thoughtful about when I called it. But a few
weeks later, I wanted the equivalent for function smtpmail-send-it
for sending mail. I almost wrote myself one more command before
stepping back to create a more generic solution.

3 One Command To Thread Them All

I have now defined command emacspeak-wizards-execute-asynchronously
bound to C-' a.
Note that this command, though part of module emacspeak-wizards, has
no emacspeak dependencies.

(defun emacspeak-wizards-execute-asynchronously (key)
  "Read key-sequence, then execute its command on a new thread."
  (interactive (list (read-key-sequence "Key Sequence: ")))
      (let ((l  (local-key-binding key))
             (g (global-key-binding key)))
     ( (commandp l)
       (make-thread l)
      (message "Running %s on a new thread." l))
     ((commandp g)
      (make-thread g)
      (message "Running %s on a new thread." g))
     (t (error "%s is not bound to a command." key)))))

(global-set-key (kbd "C-' a") 'emacspeak-wizards-execute-asynchronously)

With this command bound to C-' a, I can now get rid of my custom
gnus-async command and its associated key-binding. I already have
command gnus bound to C-; g, so I can just press C-' a C-; g to
fetch news/mail asynchronously.

Similarly, when sending mail using smtpmail I can press C-' a C-c
in the *mail* buffer to send mail without Emacs blocking.

4 Final Caveats

Like other asynchronous solutions (see package async for instance)
one needs to make sure that the command being executed asynchronously
will not require user input. In the case of package async, the
asynchronous Emacs will block waiting for input; in the case of
make-thread, Emacs enters a blocking loop with the minibuffer
continuously displaying

No catch for ...

The only way to come out is to kill Emacs — so make sure to use
command emacspeak-wizards-execute-asynchronously only when you're
sure that the command being run asynchronously will not require user

Date: 2018-07-03 Tue 00:00

Author: T.V Raman

Created: 2018-07-03 Tue 14:37


-1:-- Using Emacs Threads To Execute Commands Asynchronously (Post T. V. Raman ( 03, 2018 09:57 PM

emacspeak: Effective Suggest And Complete In An Eyes-Free Environment

Effective Suggest And Complete In An Eyes-Free Environment

1 Executive Summary

Emacs has always provided a wealth of techniques for rapid keyboard
input (abbrev, dabbrev, hippie-expandand completion come to mind)
alongside a rich collection of tools for navigating among open
buffers. And these affordances have significantly increased over the
last few years with the arrival of packages like ido, company,
helm etc., each replete with different strategies for rapid task
completion such as flex and fuzzy matching. This article investigates
these tools in an eyes-free environment, specifically in the context
of Emacspeak and rapid task completion. I've not investigated every
possible package in this space — instead, I've picked a collection
of packages and techniques that have worked well in an eyes-free
context. Finally, the ultimate metric I use in each case is the time
to successful task completion — since at the end of the day, that's
the only metric that counts when it comes to user productivity.

2 Terminology

For this article, I will use terms suggestion and completion to
mean subtly different concepts. I'll also use terms explore and
filter in describing various phases in user interaction.

Offer the user some suggestions that help explore the space of choices. (metaphor: avoid the blank sheet of paper syndrome).
Filter the available choices based on user input with the goal of reaching the target as rapidly as possible.
User does not necessarily know what he is looking for, but expects to be able to recognize what he wants from the displayed choices.
User knows exactly what he wants, e.g., filename, or function-name, but would still like to get there with the fewest possible number of keystrokes, along with the needed memory aids to guide the decision.

Note that in practice, suggestions and completions work
hand-in-hand, with the visual display playing a central role in
guiding the user through the pace of available choices. In a typical
user interaction session, the space of suggestions gets filtered by
user input to produce the available completions (choices) for the next
round of user input — think of this as a
Suggest/Input/Filter/Target (SIFT) interaction loop. Similarly, explore and
target type activities typically go hand-in-hand, with explore
serving as a memory-aid for locating the target.

3 Tasks Where Suggestions And Completions Help Speed Up Task Completion

Here are exemplars of tasks that I perform often and where I require
all the help that Emacs can provide in completing the task as rapidly
as possible:

File Navigation
Navigating to and opening a file — either code or prose.
Content Navigation
Jump to a specific location (section, function, class/method, or pattern-match) in that file.
Buffer Navigation
Jump to an already open buffer in a long-running Emacs.

If that buffer existed — but has since been killed (by
midnight for example), then re-open that buffer.
I do everything in Emacs, so open buffers include a large
number of ORG and LaTeX documents, Web Pages opened in EWW
(news sites, documentation, blog articles), IM Chats (I use
jabber), Mail Buffers — both open folders and previously
sent messages, and much, much more.

Easily launch media streams including local and streaming media.
Open (or jump to an already open) EBook to continue reading.
Code Completion
Complete function/method-name as I type, with an easy affordance to move among the available choices. The Suggest/Input/Filter/Target interaction loop applies here as well.

Notice that as one performs all of these tasks, every target is an
Emacs buffer or Emacs buffer location. In the case of completion, the
target is a string that gets inserted at the current location.

4 Features Of Eyes-Free Interaction

Using spoken output — as opposed to a rich visual display — has
the following special features and/or drawbacks:

  1. A large visual display can offer the user many choices at a time,
    and the eye's ability to rapidly scan these choices makes for an
    extremely fast Suggest/Input/Filter/Target loop. As an example, an
    interface like helm can display a large number of initial
    choices, with the user filtering these down with a few strategic key-presses.
  2. Spoken output takes time — and there is simply no way around
    this — speeding up speech-rate helps to a point, but speaking
    50 choices very fast does not help the user in the explore
    phase. This means that effective filtering and ranking of the available
    choices takes on added importance.
  3. More importantly, picking a Suggest/Input/Filter/Target (SIFT)
    interaction loop that depends on a large display is sub-optimal
    for eyes-free interaction.
  4. Given (2,3), smart filtering, flex/fuzzy matching, and ranking
    based on past user behavior take on added importance in an
    eyes-free environment. As an aside, I have high hopes in this
    area for package prescient — though in my few days of usage,
    it has yet to make a difference in my productivity.
  5. For many of the tasks enumerated in the previous section, (2, 3
    and 4) make ido with flex and fuzzy matching extremely
    effective. In contrast, helm with similar flex and fuzzy
    matching (via packages helm-flx and helm-fuzzier) adds little
    extra benefit — and the fractional extra time to compute and
    display the choices can even lead to a minor productivity hit.
  6. When it comes to writing code with completion, package company
    has proven extremely effective. Notice that when writing code,
    one rarely if ever resorts to fuzzy matching — this may well
    be subjective. Speaking for myself, I cannot think of function
    or method names in the context of fuzzy matching — said
    differently, it's hard to think xl for function-name
    next-line — even though in a given filtering context, xl
    might define the shortest path through the available choices to
    the target next-line. Given this, emacspeak implements a
    company front-end that allows the user to navigate through the
    available choices with succinct spoken feedback, and I use those
    choices only after I have typed sufficiently many characters to
    have a manageable number of choices — said differently, though
    package company is set up to trigger after 3 characters have
    been typed, I usually end up typing more — and often resort to
    dabbrev or hippee-expand to input this longer prefix.
  7. Some of the shortcomings with eyes-free interaction enumerated
    above lead to my looking for effective work-arounds that might
    well work well outside the eyes-free context, e.g. when the
    available choices are too large to fit on a typical visual
    display. Interestingly, most of these have also been solved by
    mainstream Emacs developers in their never-ending/unerring quest for increased
    productivity — package ido and company are excellent exemplars.

  • Mapping Solutions To Tasks

This section maps the various solutions I use to speed up the tasks
enumerated earlier in this article.

4.1 File And Buffer Navigation

I use package ido with add-ons flx-ido and ido-completing-read+
(formerly ido-ubiquitous) as my primary/only solution for this
task. I've dabbled with package helm — primarily via command
helm-mini but have found almost no use-cases where I did better with
helm. I also use command org-switchb to quickly jump to any of my
open org buffers – since that automatically filters the choices
down for me — I can then get to the org-mode buffer I want with
one or two keystrokes. Notice that in all of these cases, I'm relying
on the fact that I mostly know what I want, i.e., the explore phase
does not start with an entirely blank sheet of paper.

4.2 Content Navigation

Incremental search is your biggest and most effective friend in
effective eyes-free interaction — this simply cannot be stressed
enough. That everything in Emacs is searchable via
incremental-search is a big win for eyes-free interaction. When you
have a large visual display, the human eye is the search interface of
first resort – you typically use a search-command only if the
target is below the fold or far away from the cursor. Because spoken
output takes time, I use isearch even when the target is one or two
lines away.

Structured navigation comes next in my toolbox for navigating content
imenu for code, and section navigation for documents (org,
LaTeX). I also use command occur to advantage since that provides a
quick way of finding all the desired targets in a document. Given that
program source-code uses indentation for displaying structure,
hbuilt-in command selective-display remains one of Emacs' hidden
treasures with respect to expanding/collapsing source-code.

Finally, I
use a combination of isearch and structured navigation in
org-mode buffres by collapsing the document, and then using
isearch to reveal the desired content fragment.
In the case of LaTeX documents, I use package reftex to
generate a navigation buffer that functions as an interactive table
of contents.

4.3 Locating And Playing Media

  1. I keep all my music content organized under ~/mp3.
  2. I keep playlist files that contain stream-links to my favorite
    Internet streams under emacspeak/media.
  3. The afore-mentioned techniques using ido enables me to launch
    local and streaming media with a small number of keystrokes. Once
    selected, the content is played via package emacspeak-m-player
    which provides Emacs bindings to all mplayer functionality
    via that program's slave-mode. In addition, Emacspeak also
    implements a smart emacspeak-m-player-locate-media which uses
    Emacs' integration with command locate to turn the located
    files matching a given pattern into an interactive play-list.

4.4 EBooks

Jumping to already open ebooks is no different than buffer
navigation. I organize all my ebooks under a single directory
tree, and module emacspeak-epub implements a bookshelf that
allows me to organize and browse my collection along various
axies. Finally, Emacspeak implements a light-weight bookmark
facility that works with eww so that I can save my place in an
ebook across Emacs sessions.

4.5 Code Completion

As covered earlier, I use company along with dabbrev and
hippee-expand while writing code. I also use yasnippet to
generate skeleton code. I use auto-correct-mode to
automatically correct repeated errors, and add abbrevs for
commonly occurring typos.

5 Summary

  1. Emacs' Suggest/Input/Filter/Target (SIFT) interaction loop is just as
    effective in eyes-free interaction — in fact more so .
  2. Fuzzy matching when filtering is a big win when working with spoken
    output — it leads to faster task completion.
  3. Navigating ones computing environment based on the underlying
    structure and semantics of electronic content is a major win —
    both when working with a visual or spoken display. The advantages
    just become evident far sooner in the eyes-free context due to the
    inherently temporal nature of spoken interaction.

Date: 2018-06-22 Fri 00:00

Author: T.V Raman

Created: 2018-06-23 Sat 17:22


-1:-- Effective Suggest And Complete In An Eyes-Free Environment (Post T. V. Raman ( 25, 2018 03:55 PM

Raimon Grau: emacs-like browsing in firefox and chrome

In this post we'll see how to make ctrl-n work as "next-line" in chrome, firefox, or any other app in your linux box.

Browsing is my only daily computing activity I can't do inside emacs. There are browser extensions that make your browser behave like vim or emacs to a certain extent, which is very useful but they don't give a complete experience to the user (often because of limitations in the browse extension system).

Bear in mind that myself being an evil user and heavy hjkl fan, my configs use j and k sometimes to mean down and up.


Long time ago, there was conkeror. which gave a very emacsy browsing experience, but after the whole change on browser extensions, conkeror is a feasible option anymore.  The same happened to keysnail. There were also some nifty hacks using mozrepl, which are long gone now.


The plugin is originally thought to give vim-like experience to chrome/firefox, but there's no reason you can't add shortcuts like "m-<" for "beginning-of-buffer" command.

Here's my config. Custom mappings:

Btw, pay attention to c-j and c-k. that's basically to be able to use j and k somehow in sites that override them (github, gmail). Also, note that we have a custom mapping for c-n and another for c-p, but unfortunately they do not work because those shortcuts are catched by the browser application before it arrives to the plugin.


This should be in your ~/.config/gtk-3.0/settings.ini :
With this you're allowing basic movements in address bar, search boxes, and input forms and text areas.


Yep, this is the tricky one. Both firefox and chrome take over ctrl-n, so you can't remap them and they always open a new window. Same happens with c-p showing the printing dialog. The trick then is to take over it ourselves going at Window manager level :).

In my case, I'm using ratpoison wm, so some of the commands used here won't work in your window manager, but you can find your way around using xdotool Look at this link for more info.

So we need 3 things:
  • - A way to guess which window is active (ratpoison -c "info") 
  • - A way to capture a keystroke (ratpoison's "definekey top" ) 
  • - A way to send an arbitrary keystroke to the active window. (ratpoison's "meta")
With these 3 capabilities, easy peasy:
It's dead simple, but I didn't write this till this week, and it's already made a huge difference in removing friction using firefox for me.


If you write long texts in text areas, you probably want to check atomic-chrome with ghost-text.

Also, mooz, the author of keysnail is now working in a generalized solution for what I just explained for C-n, using python (and requires root privileges) called xkeysnail. It appears to be very powerful and super customizable. Also, windowmanager agnostic, so you should probably give xkeysnail a try.

Also, /u/attrigh suggests giving next browser a try. Written in Common Lisp, built using webkit, and with a much richer experience than all those hacks put together.  I haven't tried it yet, but it's worth looking at in the near future.
-1:-- emacs-like browsing in firefox and chrome (Post Raimon Grau ( 24, 2018 07:27 PM

Wilfred Hughes: Helpful: One Year On

It’s been a year since the first release of Helpful! It’s gained a ton of new features, and I’d love to share the highlights with you.

Tool Integration

Emacs has some excellent built-in debugging tools that I wanted to expose within Helpful. These tools missed the first release, but I’ve now had the chance to build them.

From a Helpful buffer, you can now toggle edebug on a function. This allows you to easily step through code.

You can also toggle tracing. Tracing is an underrated built-in feature of Emacs. You can use it to confirm functions have the inputs and outputs you’re expecting. It’s really useful when exploring unfamiliar code.

In this example, I’ve enabled tracing on projectile-project-root to see when it’s called, and what values it’s returning.


After some great user feedback, Helpful buffers now start with a summary of what you’re looking at.

Users often want a direct link to the source code, so this is included in the summary. Helpful also mentions if a function is interactive or autoloaded, just like describe-function. If a user doesn’t know what that means, those words now link to the relevant part of the Emacs manual!


Helpful tries to show all relevant information for the current thing. I’ve overhauled aliases with this in mind.

For example, if you view make-hash-table, you can now see that there is another alias of this function, but it’s now deprecated.

Modifying Variables

It’s now possible to set variables directly from Helpful buffers. This was inspired by counsel-set-variable, which has an excellent similar feature.

If a variable is a defcustom, then Helpful also includes a link to the relevant part of Customize.

Even Better Docstrings

Helpful now handles all Emacs docstring syntax. It handles references to keybindings, keymaps, and even supports the obscure features like \<foo-map> and \='.

fortran-mode is a great example of a docstring that uses a lot of Emacs docstring features.

Recent versions of Helpful try even harder to save you keystrokes. URLs are now automatically converted to links.

Finally, my favourite new feature is Info manual links. If a docstring mentions a section of the manual, Helpful converts it to a link.

Even better, if a symbol is documented in the Emacs manual, Helpful automatically adds a link at the bottom of the docstring! This hugely helps discoverability.

Installing It

Helpful is available on MELPA and MELPA stable. It’s become an indispensable part of my Emacs workflow, and I’m sure it will benefit you too.

-1:-- Helpful: One Year On (Post Wilfred Hughes ( 22, 2018 12:00 AM

emacshorrors: Determining if the server is started, or the wonders of server-running-p

Update: Bug report thread with a workaround.

(This is a contributed post by thblt )

Trivia: How can you determine if the current Emacs instance has the Emacs server running?

A quick search gives us three potential candidates: server-mode, (daemonp) and (server-running-p). That’s way too much, but surely one of them is the right one, isn’t it? Well, no. Because the real answer to this trivial question is: you can’t.

  • server-mode is t if, and only if, the server was started using the function with the same name. But there are other ways to run the server, like M-x server-start or emacs --daemon.
  • (daemonp) returns t if, and only if, Emacs was started in daemon mode.

What about (server-running-p), then? Well, it may look friendly, but here be monsters.

It starts by looking promising: after M-x server-start, (server-running-p) now returns t! Do we have a winner? Not yet! Let’s pop a new Emacs instance and eval (server-running-p) without starting the server. t again!

What’s happening? The truth is that (server-running-p) is not what it seems to be. Here’s its complete source code:

(defun server-running-p (&optional name)
  "Test whether server NAME is running.

Return values:
  nil              the server is definitely not running.
  t                the server seems to be running.
  something else   we cannot determine whether it's running without using
                   commands which may have to wait for a long time."
  (unless name (setq name server-name))
  (condition-case nil
      (if server-use-tcp
            (insert-file-contents-literally (expand-file-name name server-auth-dir))
            (or (and (looking-at "127\\.0\\.0\\.1:[0-9]+ \\([0-9]+\\)")
                     (assq 'comm
                            (string-to-number (match-string 1))))
          :name "server-client-test" :family 'local :server nil :noquery t
          :service (expand-file-name name server-socket-dir)))
    (file-error nil)))

The horror starts as soon as the docstring. The -p suffix in the name promises a predicate, that is, a boolean function. But in server-running-p, non-nil is not a loud and clear “Yes!”, it’s a mumbled “well, maybe, who knows?”. Ternary logic, because Emacs is above the law of excluded middle.

But what does this function do? It tries to determine if a server called NAME is running, by assuming that this server would be configured exactly the same as the running instance. It may end up looking at the socket file of the current server, or it may try to initiate a TCP connection, which is extremely expensive. server-running-p is the kind of function you may be tempted to call while building the mode line: try it, and get an instant and unrecoverable Emacs freeze. What it’s supposed to be useful for is extremely unclear. It’s unable to determine if the running instance has a server — but it uses this server’s config to search for a potentially completely different server.

-1:-- Determining if the server is started, or the wonders of server-running-p (Post Vasilij Schneidermann)--L0--C0--June 20, 2018 07:51 AM

Chen Bin (redguardtoo): How to spell check function/variable in Emacs

CREATED: <2018-06-17 Sun>

UPDATED: <2018-09-06 Thu>

This article explains how to spell check name of function and variable while programming in Emacs.

It uses options --run-together from GNU Aspell to check camel cased word.

But this solution is not perfect. It wrongly identifies two character interior word as typo. For example, "onChange" is identified as typo because the interior word "on". Another issue is namespace of function name. For example, "MS" from "MSToggleButton" is alias of "Microsoft". If "MS" is identified as typo, every word containing namespace "MS" is regarded as typo.

In this article,

  • I will explain how Emacs spell checker works
  • Then we study the algorithm of aspell (We can learn nothing from hunspell because hunspell can NOT check camel case word at all)
  • Finally, I will show you a complete solution which works with either aspell or hunspell

In Emacs, a built in plugin Fly Spell is in charge of spell check. It passes the options and plain text to command line tool aspell. Aspell sends back the typos of text into Fly Spell. Fly Spell then select certain typos to display. For example, when flyspell-prog-mode is on, only typos in comments and strings are visible.

So aspell doesn't understand syntax of any programming language. It scans plain text and report all typos to Fly Spell.

In aspell, there are two extra "run-together" word options:

  • --run-together-limit is "Maximum number of words can be strung together"
  • --run-together-min is "Minimal length of interior words"

Let's study the code of aspell to understand these two options. The "run-together" algorithm in implemented in function Working::check_word of file "modules/speller/default/suggest.cpp".

In order to help you understand this function, I documented the code line by line,

class Working : public Score {
  unsigned check_word(char * word, char * word_end, CheckInfo * ci, unsigned pos = 1);
unsigned Working::check_word(char * word, char * word_end,  CheckInfo * ci,
                             /* it WILL modify word */
                             unsigned pos)
  // check the whole word before go into run-together mode
  unsigned res = check_word_s(word, ci);
  // if `res` is true, it's a valid word, don't bother run-together
  if (res) return pos + 1;
  // it's typo because number of interior words is greater than "--run-together-limit"
  if (pos + 1 >= sp->run_together_limit_) return 0;

  // `i` is the `end` of interior word, the poition AFTER last character of interior word
  for (char * i = word + sp->run_together_min_; 
       // already checked the whole word; besides, any interior word whose size is less 
       // than "--run-together-min" is regarded as invalid
       i <= word_end - sp->run_together_min_;
    char t = *i;

    // read the interior word by set the character at `end` position to '\0'
    *i = '\0';
    res = check_word_s(word, ci);
    // restore original character at `end` position
    *i = t;

    // Current interior word is invalid, we need append the character at current
    //  `end` position to creata new interior word.
    //  Inncrement `i` because `i` always points to the `end` of interior word
    if (!res) continue;

    // Current interior word is valid, strip it from the whole word to create a totally
    // new word for `check_word`, `check_word` is a recursive function
    res = check_word(i, word_end, ci + 1, pos + 1);
    if (res) return res;
  memset(ci, 0, sizeof(CheckInfo));
  return 0;

Let's use "hisHelle" as demo how check_word runs:

  • "word" points to string "hisHelle" (in C/C++, string is character array. The last character of array is character '\0')
  • "sp->run_together_min_" is 3, so "i" initially points to the character "H", at the end of interior word "his"
  • "check_word_s" return "true" for interior word "his"
  • So we strip "his" from "hisHelle" and recursively call "check_word" to check new word "Helle"
  • In the new context of "check_word", we extract "Hel" from "Helle" initially
  • "Hel" is invalid. So we extract "Hell" from "Helle" and get new word "e" and recursively apply "check_word" on "e"
  • "e" is not valid and at the end of recursion. So "hisHelle" is a typo

Here is our conclusion after studying the code:

  • --run-together-limit could not be bigger if your computer got enough memory. It's default value is 8. I prefer 16.
  • --run-together-min can't be 2 because too many typos are combination of "correct" two character interior words ("hehe", "isme", …)
  • --run-together-min can't be greater than 3, or else, too many "correct" three character interior words are regarded as invalid ("his", "her", "one", "two")
  • --run-together-min should always be 3 which is its default value. Actually, it should never be tweak-able by user at the beginning

Since --run-together-min is 3. the word "onChange" is always regarded as typo because of two character interior word "on". Since there is nothing we can do at aspell side, we have to turn to Emacs to fix this problem.

When Emacs got potential typo on Emacs side, we can strip out all the two character interior word from original word and spell check new word again.

Please note hunspell can't check camel case word at all while aspell can check camel case word but with a little noise. So there is nothing we can study in hunspell.

We will use Emacs Lisp to solve this problem completely, using either aspell or hunspell.

We can attach a predicate into specific major-mode. The predicate return t if current word at cursor is typo,

(defun js-flyspell-verify ()
  (let* ((font-face (get-text-property (- (point) 1) 'face))
         (word (thing-at-point 'word)))
    (message "font-face=%s word=%s" font-face word)
(put 'js2-mode 'flyspell-mode-predicate 'js-flyspell-verify)

As you can see from above code, we have full control on what typos should be displayed in js-flyspell-verify. So predicate is actually the last chance to fix wrongly identified typos.

Here is complete setup you can paste into .emacs (I setup for js2-mode and rjsx-mode but code is generic enough).

Please note function split-camel-case split a camel case word into a list of sub-words. I just assume any sub-word whose length is less than three is not a typo.

(defun split-camel-case (word)
  "Split camel case WORD into a list of strings.
Ported from ''."
  (let* ((case-fold-search nil)
         (len (length word))
         ;; ten sub-words is enough
         (runes [nil nil nil nil nil nil nil nil nil nil])
         (runes-length 0)
         (i 0)
         (last-class 0)
         (class 0)

    ;; split into fields based on class of character
    (while (< i len)
      (setq ch (elt word i))
       ;; lower case
       ((and (>= ch ?a) (<= ch ?z))
        (setq class 1))
       ;; upper case
       ((and (>= ch ?A) (<= ch ?Z))
        (setq class 2))
       ((and (>= ch ?0) (<= ch ?9))
        (setq class 3))
        (setq class 4)))

       ((= class last-class)
        (aset runes
              (1- runes-length)
              (concat (aref runes (1- runes-length)) (char-to-string ch))))
        (aset runes runes-length (char-to-string ch))
        (setq runes-length (1+ runes-length))))
      (setq last-class class)
      ;; end of while
      (setq i (1+ i)))

    ;; handle upper case -> lower case sequences, e.g.
    ;;     "PDFL", "oader" -> "PDF", "Loader"
    (setq i 0)
    (while (< i (1- runes-length))
      (let* ((ch-first (aref (aref runes i) 0))
             (ch-second (aref (aref runes (1+ i)) 0)))
        (when (and (and (>= ch-first ?A) (<= ch-first ?Z))
                   (and (>= ch-second ?a) (<= ch-second ?z)))
          (aset runes (1+ i) (concat (substring (aref runes i) -1) (aref runes (1+ i))))
          (aset runes i (substring (aref runes i) 0 -1))))
      (setq i (1+ i)))

    ;; construct final result
    (setq i 0)
    (while (< i runes-length)
      (when (> (length (aref runes i)) 0)
        (setq rlt (add-to-list 'rlt (aref runes i) t)))
      (setq i (1+ i)))

(defun flyspell-detect-ispell-args (&optional run-together)
  "If RUN-TOGETHER is true, spell check the CamelCase words.
Please note RUN-TOGETHER will make aspell less capable. So it should only be used in prog-mode-hook."
  ;; force the English dictionary, support Camel Case spelling check (tested with aspell 0.6)
  (let* ((args (list "--sug-mode=ultra" "--lang=en_US"))args)
    (if run-together
        (setq args (append args '("--run-together" "--run-together-limit=16"))))

;; {{ for aspell only, hunspell does not need setup `ispell-extra-args'
(setq ispell-program-name "aspell")
(setq-default ispell-extra-args (flyspell-detect-ispell-args t))
;; }}

;; ;; {{ hunspell setup, please note we use dictionary "en_US" here
;; (setq ispell-program-name "hunspell")
;; (setq ispell-local-dictionary "en_US")
;; (setq ispell-local-dictionary-alist
;;       '(("en_US" "[[:alpha:]]" "[^[:alpha:]]" "[']" nil ("-d" "en_US") nil utf-8)))
;; ;; }}

(defvar extra-flyspell-predicate '(lambda (word) t)
  "A callback to check WORD.  Return t if WORD is typo.")

(defun my-flyspell-predicate (word)
  "Use aspell to check WORD.  If it's typo return t."
  (let* ((cmd (cond
               ;; aspell: `echo "helle world" | aspell pipe`
               ((string-match-p "aspell$" ispell-program-name)
                (format "echo \"%s\" | %s pipe"
               ;; hunspell: `echo "helle world" | hunspell -a -d en_US`
                (format "echo \"%s\" | %s -a -d en_US"
         (cmd-output (shell-command-to-string cmd))
    ;; (message "word=%s cmd=%s" word cmd)
    ;; (message "cmd-output=%s" cmd-output)
     ((string-match-p "^&" cmd-output)
      ;; it's a typo because at least one sub-word is typo
      (setq rlt t))
      ;; not a typo
      (setq rlt nil)))

(defun js-flyspell-verify ()
  (let* ((case-fold-search nil)
         (font-matched (memq (get-text-property (- (point) 1) 'face)
         (rlt t))
     ((not font-matched)
      (setq rlt nil))
     ;; ignore two character word
     ((< (length (setq word (thing-at-point 'word))) 2)
      (setq rlt nil))
     ;; handle camel case word
     ((and (setq subwords (split-camel-case word)) (> (length subwords) 1))
      (let* ((s (mapconcat (lambda (w)
                              ;; sub-word wholse length is less than three
                              ((< (length w) 3)
                               ;; special characters
                              ((not (string-match-p "^[a-zA-Z]*$" w))
                               w))) subwords " ")))
        (setq rlt (my-flyspell-predicate s))))
      (setq rlt (funcall extra-flyspell-predicate word))))

(put 'js2-mode 'flyspell-mode-predicate 'js-flyspell-verify)
(put 'rjsx-mode 'flyspell-mode-predicate 'js-flyspell-verify)

Optionally, you could see for my real world setup.

UPDATE: Now you can use wucuo which is complete and out of box solution to spell check code.

-1:-- How to spell check function/variable in Emacs (Post Chen Bin)--L0--C0--June 17, 2018 03:16 AM | Emacs: Org Table Spreadsheet

My notes on Org Table Spreadsheet feature.


Table 1: Org table Normalizing
Normalized col $1 Normalized col $3 Ratio of col $2 / $4
Col $1 Col $2 Col $3 Col $4 Col $5
79922.1 6.85 0.146993824 4.27 1.60
79185.9 6.78 0.146976008 4.27 1.59
64041.0 5.48 0.147067031 4.27 1.28
15452.5 1.32 0.034456713 1.00 1.32
11675.7 1.00 0.034460162 1.00 1.00

Equations Breakdown

Equation: #+tblfm: $2=$1/@7$1;%0.2f::$4=$3/@7$3;%0.2f::$5=$2/$4;%0.2f

  • $2=$1/@7$1 – Assign the value of a field in column 2 ($2) to the value of the field in column 1 in the same row ($1) divided by the value of the field in row 7, column 1 (@7$1).
    • @ is row, $ is column.
    • Row and column numbers start with 1 (not 0).
  • $4=$3/@7$3 – Similar to above, but with different row/column numbers.
  • $5=$2/$4 – Assign the value of a field in column 5 ($5) to the value of the field in column 2 in the same row ($2) divided by the value of the field in column 4 in the same row as well ($4).
  • ; is used to separate the equation from the formatting.
  • For all the 3 equations, formatting is applied using %0.2f i.e. the numbers will be formatted with 2 decimal places. See Field Formatters in Org table for more info.
  • Each of those equations are applied to the same table by concatenating them with ::.

Evaluate the whole table

Do C-u C-c C-c with point anywhere in the table, or do C-c C-c with point on the #+tblfm line.


-1:-- Org Table Spreadsheet (Post Kaushal Modi)--L0--C0--June 13, 2018 02:24 PM

Emacs café: Using Ledger for YNAB-like envelope budgeting

Bye bye Elbank

I have to start this post with this: I will not be actively maintaining Elbank anymore, simply because I switched back to Ledger. If someone wants to take over, please contact me!

The main reason for switching is budgeting. While Elbank was a cool experiment, it is not an accounting software, and inherently lacks support for powerful budgeting.

When I started working on Elbank as a replacement for Ledger, I was looking for a reporting tool within Emacs that would fetch bank transactions automatically, so I wouldn’t have to enter transactions by hand (this is a seriously tedious task, and I grew tired of doing it after roughly two years, and finally gave up).

Since then, I learned about ledger-autosync and boobank, which I use to sync my bank statements with Ledger (more about that in another post).

YNAB’s way of budgeting

I only came across YNAB recently. While I won’t use their software (being a non-free web application, and, you know… there’s no M-x ynab), I think that the principles behind it are really appealing for personal budgeting. I encourage you to read more about it (or grab a copy of the book, it’s great), but here’s the idea.

  1. Budget every euro: Quite simple once you get it. Every single Euro you have should be in a budget envelope. You should assign a job to every Euro you earn (that’s called zero-based, envelope system).

  2. Embrace your true expenses: Plan for larger and less frequent expenses, so when a yearly bill arrives, or your car breaks down, you’ll be covered.

  3. Roll with the punches: Address overspending as it happens by taking money overspent from another envelope. As long as you keep budgeting, you’re succeeding.

  4. Age your money: Spend less than you earn, so your money stays in the bank account longer. As you do that, the age of your money will grow, and once you reach the goal of spending money that is at least one month old, you won’t worry about that next bill.

Implementation in Ledger

I assume that you are familiar with Ledger, but if not I recommend reading its great introduction and tutorial.

The implementation in Ledger uses plain double-entry accounting. I took most of it from Sacha, with some minor differences.

Budgeting new money

After each income transaction, I budget the new money:

2018-06-12 Employer
    Assets:Bank:Checking                        1600.00 EUR
    Income:Salary                              -1600.00 EUR

2018-06-12 Budget
    [Assets:Budget:Food]                         400.00 EUR
    [Assets:Budget:Rent]                         600.00 EUR
    [Assets:Budget:Utilities]                    600.00 EUR
    [Equity:Budget]                            -1600.00 EUR

Did you notice the square brackets around the accounts of the budget transaction? It’s a feature Ledger calls virtual postings. These postings are not considered real, and won’t be present in any report that uses the --real flag. This is exactly what we want, since it’s a budget allocation and not a “real” transaction. Therefore we’ll use the --real flag for all reports except for our budget report.

Automatically crediting budget accounts when spending money

Next, we need to credit the budget accounts each time we spend money. Ledger has another neat feature called automated transactions for this:

= /Expenses/
    [Assets:Budget:Unbudgeted]                    -1.0
    [Equity:Budget]                                1.0

= /Expenses:Food/
    [Assets:Budget:Food]                          -1.0
    [Assets:Budget:Unbudgeted]                     1.0
= /Expenses:Rent/
    [Assets:Budget:Rent]                          -1.0
    [Assets:Budget:Unbudgeted]                     1.0
= /Expenses:Utilities/
    [Assets:Budget:Utilities]                     -1.0
    [Assets:Budget:Unbudgeted]                     1.0

Every expense is taken out of the Assets:Budget:Unbudgeted account by default.

This forces me to budget properly, as Assets:Budget:Unbudgeted should always be 0 (if it is not the case I immediately know that there is something wrong going on).

All other automatic transactions take money out of the Assets:Budget:Unbudgeted account instead of Equity:Budget account.

A Budget report

This is the final piece of the puzzle. Here’s the budget report command:

ledger --empty -S -T -f ledger.dat bal ^assets:budget

If we have the following transactions:

2018/06/12 Groceries store
    Expenses:Food                                123.00 EUR

2018/06/12 Landlord
    Expenses:Rent                                600.00 EUR

2018/06/12 Internet provider
    Expenses:Utilities:Internet                   40.00 EUR

Here’s what the report looks like:

          837.00 EUR  Assets:Budget
          560.00 EUR    Utilities
          277.00 EUR    Food
                   0    Rent
                   0    Unbudgeted
          837.00 EUR


Ledger is amazingly powerful, and provides a great framework for YNAB-like budgeting. In a future post I’ll explain how I automatically import my bank transactions using a mix of ledger-autosync and weboob.

-1:-- Using Ledger for YNAB-like envelope budgeting (Post Nicolas Petton)--L0--C0--June 12, 2018 07:20 PM

Sanel Zukan: declutter - read online content without clutter

Last two days I've been hacking on a small Emacs mode called declutter and this will be the first version announcement.

What is declutter and why?

I often use Emacs to read long, online articles, which gives me plenty of options - I can save text for offline reading, I can read content with my favorite color and terminal setup, I have my shortcuts for fast navigation and so on.

However, modern sites are using more and more client-side rendering which doesn't play well with EWW. Also, there is a recent trend I'm not really fan of, and that is putting paywall on anything worth of reading.

So, someone smart I'm not affiliated with, created service, which is able to solve above problems. At least most of it, which is perfectly fine with me. And that service is free to use, of course.

declutter, in short, will use to get readable html content, including paywall protected sites straight from Emacs. Then it will render it in readable form in separate buffer.

So, I'm inviting you to try it, test it and let me know for your comments. And please report if something breaks.


-1:-- declutter - read online content without clutter (Post)--L0--C0--June 11, 2018 10:00 PM

Jonas Bernoulli: Magit 2.13 released

I am excited to announce the release of Magit version 2.13, consisting of 166 commits since the last feature release two months ago.
-1:-- Magit 2.13 released (Post)--L0--C0--June 02, 2018 05:00 AM

Alex Bennée: dired-rsync 0.4 released

I started hacking on this a while back but I’ve finally done the house-keeping tasks required to make it a proper grown up package.

dired-rsync is a simple command which you can use to trigger an rsync copy from within dired. This is especially useful when you want to copy across large files from a remote server without locking up Emacs/Tramp. The rsync just runs as an inferior process in the background.

Today was mainly a process of cleaning up the CI and fixing any issues with it. I’d still like to add some proper tests but the whole thing is interactive and that seems to be tricky for Emacs to test. Anyway I’ve now tagged 0.4 so it will be available from MELPA Stable once it rebuilds. You can of course grab the building edge from MELPA any time 😉

-1:-- dired-rsync 0.4 released (Post Alex)--L0--C0--June 01, 2018 05:12 PM

Alexander Gromnitsky: Emacs & gpg files: use the minibuffer for password prompts

In the past Emacs was communicating w/ gnupg directly & hence was responsible for reading/sending/catching passwords. In contrast, Emacs 26.1, by default, fully delegates the password handling to gpg2.

The code for the interoperation w/ gpg1 is still present in the Emacs core, but it's no longer advertised in favour of gpg2 + elpa pinentry.

If you don't want an additional overhead or a special gpg-agent setup, it's still possible to use gpg1 for (en|de)crypting ops.

Say we have a text file we want to encrypt & then transparently edit in Emacs afterwards. The editor should remember the correct pw for the file & not bother us w/ the pw during the file saving op.

$ rpm -qf `which gpg gpg2`

$ echo rain raine goe away, little Johnny wants to play | gpg -c > nr.gpg
$ file nr.gpg
nr.gpg: GPG symmetrically encrypted data (AES cipher)

If you have both gpg1 & gpg2 installed, Emacs ignores gpg1 completely. E.g., run 'emacs -Q' & open nr.gpg file–gpg2 promptly contacts gpg-agent, which, in turn, runs the pinentry app:

Although, it may look as if everything is alright, try to edit the decrypted file & then save it. The pinentry window will reappear & you'll be forced to enter the pw twice.

The Emacs mode that handles the gnupg dispatch is called EasyPG Assistant. To check its current state, use epg-find-configuration fn:

ELISP> (car (epg-find-configuration 'OpenPGP))
(program . "/usr/bin/gpg2")

We can force EasyPG to use gpg1, despite that it's not documented anywhere.

The actual config data is located in epg-config--program-alist var:

ELISP> epg-config--program-alist
((OpenPGP epg-gpg-program
("gpg2" . "2.1.6")
("gpg" . "1.4.3"))
(CMS epg-gpgsm-program
("gpgsm" . "2.0.4")))

Here, if we shadow the gpg2 entry in the alist, EasyPG would regenerate a new config for all the (en|de)crypting ops on the fly:

(require 'epg-config)
(add-to-list 'epg-config--program-alist `(OpenPGP epg-gpg-program ("gpg" . ,epg-gpg-minimum-version)))
(setq epa-file-cache-passphrase-for-symmetric-encryption t)
(setq epg--configurations nil)

Now, if you open nr.gpg afresh, Emacs neither should use the gpg-agent any more:

Nor should it ask for the pw when you'll do edit+save later on.

To clear the internal pw cache, type

ELISP> (setq epa-file-passphrase-alist nil)
-1:-- Emacs &amp; gpg files: use the minibuffer for password prompts (Post ag ( 01, 2018 07:28 AM

Chris Wellons: Emacs 26 Brings Generators and Threads

Emacs 26.1 was recently released. As you would expect from a major release, it comes with lots of new goodies. Being a bit of an Emacs Lisp enthusiast, the two most interesting new features are generators (iter) and native threads (thread).

Correction: Generators were actually introduced in Emacs 25.1 (Sept. 2016), not Emacs 26.1. Doh!


Generators are one of those cool language features that provide a lot of power at a small implementation cost. They’re like a constrained form of coroutines, but, unlike coroutines, they’re typically built entirely on top of first-class functions (e.g. closures). This means no additional run-time support is needed in order to add generators to a language. The only complication is the changes the compiler. Generators are not compiled the same way as normal functions despite looking so similar.

What’s perhaps coolest of all about lisp-family generators, including Emacs Lisp, is that the compiler component can be implemented entirely with macros. The compiler need not be modified at all, making generators no more than a library, and not actually part of the language. That’s exactly how they’ve been implemented in Emacs Lisp (emacs-lisp/generator.el).

So what’s a generator? It’s a function that returns an iterator object. When an iterator object is invoked (e.g. iter-next) it evaluates the body of the generator. Each iterator is independent. What makes them unusual (and useful) is that the evaluation is paused in the middle of the body to return a value, saving all the internal state in the iterator. Normally pausing in the middle of functions isn’t possible, which is what requires the special compiler support.

Emacs Lisp generators appear to be most closely modeled after Python generators, though it also shares some similarities to JavaScript generators. What makes it most like Python is the use of signals for flow control — something I’m not personally enthused about (though see also). When a Python generator completes, it throws a StopItertion exception. In Emacs Lisp, it’s an iter-end-of-sequence signal. A signal is out-of-band and avoids the issue relying on some special in-band value to communicate the end of iteration.

In contrast, JavaScript’s solution is to return a “rich” object wrapping the actual yield value. This object has a done field that communicates whether iteration has completed. This avoids the use of exceptions for flow control, but the caller has to unpack the rich object.

Fortunately the flow control issue isn’t normally exposed to Emacs Lisp code. Most of the time you’ll use the iter-do macro or (my preference) the new cl-loop keyword iter-by.

To illustrate how a generator works, here’s a really simple iterator that iterates over a list:

(iter-defun walk (list)
  (while list
    (iter-yield (pop list))))

Here’s how it might be used:

(setf i (walk '(:a :b :c)))

(iter-next i)  ; => :a
(iter-next i)  ; => :b
(iter-next i)  ; => :c
(iter-next i)  ; error: iter-end-of-sequence

The iterator object itself is opaque and you shouldn’t rely on any part of its structure. That being said, I’m a firm believer that we should understand how things work underneath the hood so that we can make the most effective use of at them. No program should rely on the particulars of the iterator object internals for correctness, but a well-written program should employ them in a way that best exploits their expected implementation.

Currently iterator objects are closures, and iter-next invokes the closure with its own internal protocol. It asks the closure to return the next value (:next operation), and iter-close asks it to clean itself up (:close operation).

Since they’re just closures, another really cool thing about Emacs Lisp generators is that iterator objects are generally readable. That is, you can serialize them out with print and bring them back to life with read, even in another instance of Emacs. They exist independently of the original generator function. This will not work if one of the values captured in the iterator object is not readable (e.g. buffers).

How does pausing work? Well, one of other exciting new features of Emacs 26 is the introduction of a jump table opcode, switch. I’d lamented in the past that large cond and cl-case expressions could be a lot more efficient if Emacs’ byte code supported jump tables. It turns an O(n) sequence of comparisons into an O(1) lookup and jump. It’s essentially the perfect foundation for a generator since it can be used to jump straight back to the position where evaluation was paused.

Buuut, generators do not currently use jump tables. The generator library predates the new switch opcode, and, being independent of it, its author, Daniel Colascione, went with the best option at the time. Chunks of code between yields are packaged as individual closures. These closures are linked together a bit like nodes in a graph, creating a sort of state machine. To get the next value, the iterator object invokes the closure representing the next state.

I’ve manually macro expanded the walk generator above into a form that roughly resembles the expansion of iter-defun:

(defun walk (list)
  (let (state)
    (cl-flet* ((state-2 ()
                 (signal 'iter-end-of-sequence nil))
               (state-1 ()
                 (prog1 (pop list)
                   (when (null list)
                     (setf state #'state-2))))
               (state-0 ()
                 (if (null list)
                   (setf state #'state-1)
      (setf state #'state-0)
      (lambda ()
        (funcall state)))))

This omits the protocol I mentioned, and it doesn’t have yield results (values passed to the iterator). The actual expansion is a whole lot messier and less optimal than this, but hopefully my hand-rolled generator is illustrative enough. Without the protocol, this iterator is stepped using funcall rather than iter-next.

The state variable keeps track of where in the body of the generator this iterator is currently “paused.” Continuing the iterator is therefore just a matter of invoking the closure that represents this state. Each state closure may update state to point to a new part of the generator body. The terminal state is obviously state-2. Notice how state transitions occur around branches.

I had said generators can be implemented as a library in Emacs Lisp. Unfortunately theres a hole in this: unwind-protect. It’s not valid to yield inside an unwind-protect form. Unlike, say, a throw-catch, there’s no mechanism to trap an unwinding stack so that it can be restarted later. The state closure needs to return and fall through the unwind-protect.

A jump table version of the generator might look like the following. I’ve used cl-labels since it allows for recursion.

(defun walk (list)
  (let ((state 0))
        ((closure ()
           (cl-case state
             (0 (if (null list)
                    (setf state 2)
                  (setf state 1))
             (1 (prog1 (pop list)
                  (when (null list)
                    (setf state 2))))
             (2 (signal 'iter-end-of-sequence nil)))))

When byte compiled on Emacs 26, that cl-case is turned into a jump table. This “switch” form is closer to how generators are implemented in other languages.

Iterator objects can share state between themselves if they close over a common environment (or, of course, use the same global variables).

(setf foo
      (let ((list '(:a :b :c)))
          (iter-lambda ()
            (while list
              (iter-yield (pop list)))))
          (iter-lambda ()
            (while list
              (iter-yield (pop list))))))))

(iter-next (nth 0 foo))  ; => :a
(iter-next (nth 1 foo))  ; => :b
(iter-next (nth 0 foo))  ; => :c

For years there has been a very crude way to “pause” a function and allow other functions to run: accept-process-output. It only works in the context of processes, but five years ago this was sufficient for me to build primitives on top of it. Unlike this old process function, generators do not block threads, including the user interface, which is really important.


Emacs 26 also bring us threads, which have been attached in a very bolted on fashion. It’s not much more than a subset of pthreads: shared memory threads, recursive mutexes, and condition variables. The interfaces look just like they do in pthreads, and there hasn’t been much done to integrate more naturally into the Emacs Lisp ecosystem.

This is also only the first step in bringing threading to Emacs Lisp. Right now there’s effectively a global interpreter lock (GIL), and threads only run one at a time cooperatively. Like with generators, the Python influence is obvious. In theory, sometime in the future this interpreter lock will be removed, making way for actual concurrency.

This is, again, where I think it’s useful to contrast with JavaScript, which was also initially designed to be single-threaded. Low-level threading primitives weren’t exposed — though mostly because JavaScript typically runs sandboxed and there’s no safe way to expose those primitives. Instead it got a web worker API that exposes concurrency at a much higher level, along with an efficient interface for thread coordination.

For Emacs Lisp, I’d prefer something safer, more like the JavaScript approach. Low-level pthreads are now a great way to wreck Emacs with deadlocks (with no C-g escape). Playing around with the new threading API for just a few days, I’ve already had to restart Emacs a bunch of times. Bugs in Emacs Lisp are normally a lot more forgiving.

One important detail that has been designed well is that dynamic bindings are thread-local. This is really essential for correct behavior. This is also an easy way to create thread-local storage (TLS): dynamically bind variables in the thread’s entrance function.

;;; -*- lexical-binding: t; -*-

(defvar foo-counter-tls)
(defvar foo-path-tls)

(defun foo-make-thread (path)
   (lambda ()
     (let ((foo-counter-tls 0)
           (foo-name-tls path))

However, cl-letf “bindings” are not thread-local, which makes this otherwise incredibly useful macro quite dangerous in the presence of threads. This is one way that the new threading API feels bolted on.

Building generators on threads

In my stack clashing article I showed a few different ways to add coroutine support to C. One method spawned per-coroutine threads, and coordinated using semaphores. With the new threads API in Emacs, it’s possible to do exactly the same thing.

Since generators are just a limited form of coroutines, this means threads offer another, very different way to implement them. The threads API doesn’t provide semaphores, but condition variables can fill in for them. To “pause” in the middle of the generator, just wait on a condition variable.

So, naturally, I just had to see if I could make it work. I call it a “thread iterator” or “thriter.” The API is very similar to iter:

This is merely a proof of concept so don’t actually use this library for anything. These thread-based generators are about 5x slower than iter generators, and they’re a lot more heavy-weight, needing an entire thread per iterator object. This makes thriter-close all the more important. On the other hand, these generators have no problem yielding inside unwind-protect.

Originally this article was going to dive into the details of how these thread-iterators worked, but thriter turned out to be quite a bit more complicated than I anticipated, especially as I worked towards feature matching iter.

The gist of it is that each side of a next/yield transaction gets its own condition variable, but share a common mutex. Values are passed between the threads using slots on the iterator object. The side that isn’t currently running waits on a condition variable until the other side frees it, after which the releaser waits on its own condition variable for the result. This is similar to asynchronous requests in Emacs dynamic modules.

Rather than use signals to indicate completion, I modeled it after JavaScript generators. Iterators return a cons cell. The car indicates continuation and the cdr holds the yield result. To terminate an iterator early (thriter-close or garbage collection), thread-signal is used to essentially “cancel” the thread and knock it off the condition variable.

Since threads aren’t (and shouldn’t be) garbage collected, failing to run a thread-iterator to completion would normally cause a memory leak, as the thread sits there forever waiting on a “next” that will never come. To deal with this, there’s a finalizer is attached to the iterator object in such a way that it’s not visible to the thread. A lost iterator is eventually cleaned up by the garbage collector, but, as usual with finalizers, this is only a last resort.

The future of threads

This thread-iterator project was my initial, little experiment with Emacs Lisp threads, similar to why I connected a joystick to Emacs using a dynamic module. While I don’t expect the current thread API to go away, it’s not really suitable for general use in its raw form. Bugs in Emacs Lisp programs should virtually never bring down Emacs and require a restart. Outside of threads, the few situations that break this rule are very easy to avoid (and very obvious that something dangerous is happening). Dynamic modules are dangerous by necessity, but concurrency doesn’t have to be.

There really needs to be a safe, high-level API with clean thread isolation. Perhaps this higher-level API will eventually build on top of the low-level threading API.

-1:-- Emacs 26 Brings Generators and Threads (Post)--L0--C0--May 31, 2018 05:45 PM

Timo Geusch: Emacs 26.1 has been released (and it’s already on Homebrew)

Saw the announcement on on the GNU Emacs mailing list this morning. Much to my surprise, it’s also already available on homebrew. So my Mac is now sporting a new fetching version of Emacs as well :). I’ve been running Read More

The post Emacs 26.1 has been released (and it’s already on Homebrew) appeared first on The Lone C++ Coder's Blog.

-1:-- Emacs 26.1 has been released (and it’s already on Homebrew) (Post Timo Geusch)--L0--C0--May 28, 2018 05:32 PM | Emacs: How do I write "Org mode"?

You write it just like that in the title — “Org” with capital “O”, and then lower-case “mode” separated by a space.

A super-quick intro to Org mode

Org mode is a fantastic major mode for Emacs, and people use it for all sorts of things like keeping notes, maintaining TODO lists, writing documentation, or even blogging—like I am doing here.


Every now and then, I would see “Org mode” and related phrases written in the “wild” (like blogs, Reddit posts, tweets) as Org-mode, org-manual, org file, etc., with a mix-and-match of cases and hyphens.

So here is an attempt to familiarize more people with the documentation standard for referring to “Org” stuff. Below I am quoting the text from the official Org Documentation Standards:

  • Prefer “Org mode” to “Org-mode” or “org-mode”. This is simply because it reflects an existing convention in The Emacs Manual which consistently documents mode names in this form - “Text mode”, “Outline mode”, “Mail mode”, etc.
  • Likewise refer, if at all possible, to “Org file or “Org buffer” meaning with, great generality, any file or buffer which requires use of some part of Org to edit it properly.
  • Org uses “org-…” to ring fence a name space for itself in the Emacs code base. This is obviously retained in code snippets.

The right way

Org mode, Org manual, Org file

Only in the Elisp code, is it called org-mode, because it is a major mode, and has to be named so in code by convention, and for its separate org-* name space.

But for blogging, documentation, etc. –

    Org foo it is.


-1:-- How do I write "Org mode"? (Post Kaushal Modi)--L0--C0--May 21, 2018 08:35 PM

Phil Hagelberg: in which interactive development saves the day

When I was writing EXO_encounter 667 in Fennel, I benefited immensely from the ability to do live reloads. Instead of having to restart the whole process, I could run a single key command from my editor and have the game see the new code immediately. This isn't particularly difficult to do in Fennel, but it's not immediately obvious at a glance either.

Before you understand how reloading works in Fennel, you need a little background regarding Lua's module system, since Fennel is just a compiler that emits Lua code. Older versions of Lua had a module function which would declare the whole rest of the file as being part of a specific module and register that with the module system, and all functions that would normally be declared as global within that file would be exported as part of the module instead. But in version 5.1, that system was recognized as redundant: nowadays a module is just a file that returns a table1 with closures and other values in it. This is reflects the relentless simplicity behind the design of Lua; why have modules as their own concept when tables and closures can do just as good a job?

So that's all well and good; you can just write code that uses functions written in other files by just calling dofile on the filename and putting that value in a local. And that works, but every time you use the module from another place it loads a fresh copy, which is wasteful. Enter the require function. It takes a module name which maps to a filename (by searching the entries of package.path) and gives you the value returned by that file, but it also caches subsequent calls. So every time you require a module, you're getting the exact same table2 in the exact same memory location.

Valley near Mt. Saint Helens

We can take a little detour here from Lua land and back into Fennel, because dofile only works on Lua code. Fennel provides its own fennel.dofile function which works just like the built-in one, but on .fnl files instead. But what about require? Well it turns out require is implemented in a pretty clever way that allows us to teach it new tricks. The way require works is that it looks at the package.searchers table, (it's package.loaders on Lua 5.1) which contains a list of searcher functions. It iterates over the list, calling each searcher with the module name. If that returns nil, it indicates that searcher can't find the module and it moves on, but a searcher which can load the module will return a function which allows require to get (and cache) the value for the module in question. So simply by adding fennel.searcher to package.searchers, we can make it so that require works seamlessly on modules whether they are written in Fennel or Lua:

(local fennel (require "fennel"))
(table.insert package.searchers fennel.searcher)

Now this seems somewhat academic; after all, you have a lot of memory; why do you care if modules are duplicated in memory? But using require for modules proved invaluable during the development of my game because it allowed me to do all my local hacking using .fnl files I was constantly editing, but when I prepared a release, I precompiled it all into .lua files and didn't have to change a line of my code to reflect that.

Well that's wonderful, but if require caches the value of each module, doesn't that interfere with live reloading? Indeed it does; simply re-requiring a module has no effect. You can call fennel.dofile to get a copy of the updated module. But that's no help to the existing code which has the old version of the module. What to do?

To understand the solution it's helpful to make a distinction between the identity of the table and the values it contains. The identity of a table is what makes it truly unique; it can be thought of in terms of that table's particular location in memory. When you pass a table to a function, that function has access to the exact same table, and changes made to it inside the function of course are visible to any other function that has access to the table3. The value of a table refers to what it contains; in the case of a module it's usually about what functions are present under what keys. Since the tables are mutable, the value can change over time but the identity cannot. When you call dofile on a module you get a table that might have the same values as last time you called dofile, (if the file on disk hasn't changed) but it will never have the same identity. When you call require you're guaranteed to get the exact same identical table every time.4

With that background maybe you can see now how this might work. All the existing code has access to the original module table. We can't swap out that table for a new one without reloading all the modules that use it, and that can be disruptive. But we can grab that original table, load a fresh copy of its module from disk, then go in and replace its contents with the values from the new one.

(defun fennel-reload-form (module-keyword)
  "Return a string of the code to reload the module-keyword module."
  (format "%s\n" (let [old (require ,module-keyword)
                            _ (tset package.loaded ,module-keyword nil)
                            new (require ,module-keyword)]
                    ;; if the module isnt a table then we can't make
                    ;; changes which affect already-loaded code, but if
                    ;; it is then we should splice new values into the
                    ;; existing table and remove values that are gone.
                    (when (= (type new) :table)
                      (each [k v (pairs new)]
                            (tset old k v))
                      (each [k (pairs old)]
                            ;; the elisp reader is picky about where . can be
                            (when (not (,"." new k))
                              (tset old k nil)))
                      (tset package.loaded ,module-keyword old)))))

The code above looks like Fennel, but it's actually Fennel embedded inside Emacs Lisp code; because they're both just made up of s-expressions, you can write Fennel code as Elisp code and quote it, then send it to the Fennel repl subprocess which is launched with M-x run-lisp. My recent changes to fennel-mode.el allow this to work out of the box, but they could easily be adapted to any other editor that supports communicating with an integrated repl subprocess.

Of course, all this background really isn't necessary; you can just hit reload now and have it work with no fuss. But sometimes it's interesting to understand why it works, and especially I think in this case the design decisions that went into the module system are noteworthy for allowing this kind of thing to be done in a graceful way, so that's worth appreciating and hopefully learning from.

[1] Technically a module can return any value, not just a table. But if you return a non-table, then the reloading features described don't work, because only tables can have their contents replaced while retaining their same object identity.

[2] Yep; this means you can abuse the module system to do terrible things like share application state across other modules. Please resist the temptation.

[3] Oddly enough in some languages this is not true and data structures default to being copied implicitly every time you pass them to a function, which can be very confusing. To muddle things even more, this behavior is referred to as "pass by value" instead of "we make copies of everything for you even when you don't ask". That doesn't happen here.

[4] For a fascinating discussion of the difference between value and identity and how it relates to equality I strongly recommend reading the very insightful Equal Rights for Functional Objects which goes into much more depth on this subject. Notably Lua's (and Fennel's) equality semantics are consistent with its recommendations despite Lua being an imperative language.

-1:-- in which interactive development saves the day (Post Phil Hagelberg)--L0--C0--May 10, 2018 02:11 AM

Phil Hagelberg: in which a game jam is recounted further

This is the second part continuing my previous post about creating the game EXO_encounter 667 using the Fennel programming language and the LÖVE game framework for the Lisp Game Jam 2018; you'll probably want to read the first installment if you haven't already. I wrote about the game design and art, but in this post I'd like to dive into the more technical aspects of the game.

exo encounter terminal

The voting for the game jam just closed, and EXO_encounter 667 came in ranked first! Three out of the top four winners are LÖVE games; one other in Fennel and one in Urn.


I pulled in a couple libraries on top of LÖVE to help out in a few areas. First and foremost I would dread to do any work on the Lua runtime without lume, which I like to think of as Lua's "missing standard library". It brings handy things like filter, find, reduce, etc. It's mostly sequence-related functions, but there are a few other handy functions as well like split, a bizarre omission from the standard library, or hotswap which I'll get to below.

The bump.lua library is used for collision detection, and as long as you only need to operate in terms of axis-aligned rectangles, it is very easy to use and gets the job done with no fuss.1 But one of the nicest things about bump is that it's integrated into Simple Tiled Implementation, which handles maps exported from Tiled. On its own the Tiled library just handles drawing them (including their animations and layering), but it can automatically integrate with bump if you set properties on a layer or object to flag it as collidable.

The documentation for the Tiled library unfortunately leaves quite a bit to be desired; it's one of those projects that just dumps a list of all functions with a line or two describing what each one does and considers that "the documentation". Fortunately the source is pretty readable, but figuring out how to handle opening and closing of doors was definitely the roughest spot when it came to 3rd-party libraries. The readme does describe how to implement a custom drawing routine for a layer, which allows us to draw a door differently based on whether it's closed or open. The problem is there's no easy way to do the same thing for the collision detection side of the story.

The Tiled library handles setting up the "world" table from bump by seeding it with all the collidable things from the map. The problem is it doesn't actually use the same tables from the map when adding them to the bump table; it wraps them in bump-specific tables stripping it down to just the fields relevant to collision detection. This is fine until have a door you need to open. Normally you'd do this by calling bump.remove with the door table to make the door no longer take part in collision detection, but bump doesn't know about the door table; it only knows about the wrapper table, which we no longer have access to.

I ended up hacking around this by making the Tiled library save off all the wrapper tables it created, and introducing a new bump_wrap function on the map which would intercept methods on the bump world, accept a regular table and look up the wrapped table and use it instead in the method call. It got the job done quickly, but I couldn't help but feel there should be a better way. I've opened an issue with the Tiled library to see if maybe I missed an undocumented built-in way of doing this. But as far as the coding went, this was really the only hiccup I encountered with any of the libraries I used.

Interactive Development

As a lisp, of course Fennel ships with a REPL (aka interactive console, often mistakenly called an "interpreter") which allows you to enter code and see the results immediately. This is absolutely invaluable for rapid game development. There's a bit of a hiccup though; the REPL reads from standard in, and LÖVE doesn't ship with a method for reading from standard in without blocking. Since Lua doesn't have concurrency, this means reading repl input would block the whole game loop until enter was pressed! LÖVE saves the day here by allowing you to construct "threads" which are really just completely independent Lua virtual machines that can communicate with each other over queues but can't share any data directly. This turns out to be just fine for the repl; one thread can sit and block on standard in, and when it gets input send it over a queue to the main thread which evaluates and sends the response back.

(defn start-repl []
  (let [code ( "stdio.fnl")
        lua (love.filesystem.newFileData (fennel.compileString code) "io")
        thread (love.thread.newThread lua)
        io-channel (love.thread.newChannel)]
    ;; this thread will send "eval" events for us to consume:
    (: thread :start "eval" io-channel)
    (set love.handlers.eval
         (fn [input]
           (let [(ok val) (pcall fennel.eval input)]
             (: io-channel :push (if ok (view val) val)))))))

As I use Emacs, I've configured fennel-mode to add a key combo for reloading the module for the current buffer. This only works if the current file is in the root directory of the project; it won't work with subdirectories as the module name will be wrong, but it's pretty helpful. It also requires lume be defined as a global variable. (Normally I avoid using globals, but I make two exceptions; one for lume and another for pp as a pretty-print function.) I haven't included this in fennel-mode yet because of these gotchas; maybe if I can find a way to remove them it can be included as part of the mode itself in the future.

Simply run C-u M-x run-lisp to start your game, and use love . as your command. Once that's started, the code below will make C-c C-k reload the current module.

(eval-after-load 'fennel-mode
  '(define-key fennel-mode-map (kbd "C-c C-k")
     (defun pnh-fennel-hotswap ()
        (format "(lume.hotswap \"%s\")\n"
                (substring (file-name-nondirectory (buffer-file-name)) 0 -4))))))

Update: I added first-class support for reloads to fennel-mode, though you will still need the stdin hack described above when using it inside LÖVE.

The other gotcha is that currently an error will crash your whole game. I really wanted to add an error handler which would allow you to resume play after reloading the module that crashed, but I didn't have time to add that. Hopefully I'll have that ready in time for the next jam!


From a usability perspective, one of the most helpful things was adding a tutorial to explain the basic controls and mechanics. The tutorial displays instructions onscreen until the point at which the player carries out those instructions, at which point it moves on to the next instructions. There are various ways you could go about doing this, but I chose to implement it using coroutines, which are Lua's way of offering cooperative multitasking.

(defn tutorial [state world map dt]
  (echo "Press 2 to select rover 2; bring it near the"
        "main probe and press enter to dock.")
  (while (not (. state.rovers 2 :docked?))

  (echo "With at least 3 rovers docked, the main" "probe has mobility."
        "" "Now do the same with rover 3.")
  (while (not (. state.rovers 3 :docked?))

  (echo "The probe's communications laser can be"
        "activated by holding space. Comma and"
        "period change the aim of the laser.")
  (while (not (or (and state.laser (~= state.selected.theta math.pi))
                  (> (: world :getRect state.selected) 730)
                  (sensor? map "first")))


The tutorial function runs inside a coroutine started with coroutine.wrap; it echoes the first message and then suspends itself with coroutine.yield which returns control to the caller. On every tick, the love.update function coroutine.resumes it which allows it to check whether the conditions have been fulfilled. If so it can move on to the next instruction; otherwise it just yields back immediately. Of course, it would be possible to do something like this using only closures, but coroutines allow it to be written in a very linear, straightforward way.

exo encounter laser screenshot


With LÖVE you get portability across many operating systems; however it does not actually handle creating the executables for each platform. I used an old version of love-release2 to create zip files which include everything you need to run on Windows and Mac OS. This was a huge help; I could run my entire build from my Debian laptop without even touching a Windows machine or a Mac.

For the jam I just published a .love file for other platforms, which requires you to manually install LÖVE yourself. This is a bit of a drag since most package managers don't include the correct version of LÖVE, and even if they did today, in the future they'd upgrade to a different one, so this is one place where relying on the package manager is definitely not going to cut it. Soon after the jam I discovered AppImages which are a way of bundling up all a program's dependencies into a single executable file which should work on any Linux distribution. While I think this is a really terrible idea for a lot of software, for a single-player game that doesn't load any data from untrusted sources, I believe it to be the best option. The love-release tool doesn't currently support creating AppImages, but I am hoping to add support for this. I also didn't get around to automating uploading of builds to using butler, but I'm hoping to have that working for next time.

Play my game!

Now that the jam is over, I've gotten some great feedback from players that resulted in a nice todo list of items that can be improved. I hope to release a "special edition" in the near future that includes all the things I wasn't able to get to during the jam. But in the mean time, I hope you enjoy EXO_encounter 667!

[1] LÖVE ships with a physics engine built-in, but the API it uses is much more complicated. It's capable of more sophisticated behavior, but unless you really can't work in terms of rectangles, I'd recommend sticking with the much simpler bump.lua.

[2] The love-release project has since been rewritten in Lua instead of being a shell script as it was at the time I downloaded the version I used. I haven't tried the new version but it looks promising.

-1:-- in which a game jam is recounted further (Post Phil Hagelberg)--L0--C0--May 05, 2018 05:05 PM