mgmarlow.com - List of blog posts

Revisiting My Reading List

2026-05-30T00:00:00+00:00

The best kind of weekend project takes just a few scattered hours while solving a supremely pedantic annoyance. That's the story of my hand-rolled book-tracking replacement.

The idea stemmed from a discussion with friends, where a conversation about books transitioned into how we keep track of our respective lists.

Unlike Letterboxd, which solves movie-tracking with a sublime grace, every reading platform kind of stinks. Goodreads is a vehicle for advertisement that has languished under Amazon's stewardship. Storygraph is the Next Best Thing, but is (unfortunately) supremely ugly. Margins looks neat but caters too heavily to the obsessive-impulsiveness of the BookTok crowd. Hardcover gives me whiplash every time it swaps between open source fantasy and legitimate product.

I don't mean to be too hard on these products, making a social book site is a surprisingly hard endeavor. The world of editions, publishers, and ISBNs is an absolute mess! But look, I just need a place to keep a list of books that I can share with my friends. I don't need recommendations, I don't need reviews. I don't use these sites to find my next read.

And so, taking a page out of Tom MacWright's book</a>, I absorbed my reading list into this very site</a>.

I keep my list as a YAML file that is easy enough to keep updated as I rotate through books:

-</span> title</span>:</span> "A Wild Sheep Chase"</span></span>
  author</span>:</span> "Haruki Murakami"</span></span>
  status</span>:</span> "read"</span></span>
  started</span>:</span> 2026-04-22</span></span>
  finished</span>:</span> 2026-05-05</span></span>
  isbn</span>:</span> 9780375718946</span></span></code></pre>
I compile this YAML file into two different file types. The first is the
HTML template that becomes /reading</a>. The second is an Atom
feed that I use to push updates to a Discord channel.</p>
That second point is inspired by
Filmlinkd</a>, which our Discord
server uses to post Letterboxd activity into a text channel. Since my
books are tracked in a YAML file, I need some mechanism for tracking
changes and triggering a message. That mechanism is an Atom feed and a
Cloudflare Worker.</p>
Atom is a great fit for this job. Each book entry has a natural
ID formed by it's ISBN, which I form into an OpenLibrary URL:
https://openlibrary.org/isbn/9780375718946</a>. An entry's updated-at
field is either the started</code> date or the finished</code> date. A book
transitioning from "reading" to "read" will naturally have a later
finished</code> timestamp, indicating an update.</p>
The update ends up in the Discord server via a Cloudflare Worker. The
worker reads the Atom feed on a periodic basis (every 30min) and looks
for updated items (by comparing the new read to the cache in Cloudflare
KV). If it finds an update, it forms a message and posts it to the
server via a webhook.</p>
Weekend accomplished.</p>
Check out the source: https://git.sr.ht/~mgmarlow/reading-list-poster</a>.</p>



PGP and Real-World Cryptography
2026-03-14T00:00:00+00:00
My previous post details setting up Sequoia PGP for email encryption, where I
gloss over technical details in favor of waxing poetic about the virtues of
privacy. That's all well and good, but I don't want to leave such details
completely behind because they form an interesting window into the world of
asymmetric cryptography.</p>
This whole PGP excursion has ignited within me a desire to learn more about
cryptography generally</em>, leading to the book
Real-World Cryptography</em></a>.
The author has the following to say about PGP:</p>

The most critical issue is that encryption is not authenticated, which means
that anyone intercepting an email that hasn't been signed might be able to
tamper with the encrypted content to some degree, depending on the exact
encryption algorithm used. For this reason alone, I would not recommend anyone
to use PGP today. (David Wong)</p>
</blockquote>
Not a very positive review, I'd say. Further points are well-argued, and the
case against PGP is strong. Well, maybe I should rephrase that as the case
against email encryption</em>.</p>
More fundamental than PGP is the fact that email is a plaintext protocol. It was
never designed with encryption in mind, and that effect has repercussions
towards any solution bolted on top. Cryptographic systems aside, using PGP to
encrypt email means that you're still exposing email metadata, even if the
message itself is encrypted.1</a></sup></p>
Despite this, I was still motivated to investigate some of the author's
criticisms. Has the world of PGP changed since the book was released in 2021? As
it turns out, yes! Although the details of those changes are themselves worthy
of an unexpectedly deep rabbit hole.</p>
The PGP that Real-World Cryptography</em> discusses is RFC 4880, the 2007 PGP
standard. Efforts to improve this standard have arisen over the last decade, but
have unfortunately split into two separate groups. On one side, GnuPG maintainer
Werner Koch advocates for a conservative approach, spawning LibrePGP. On the
other, Proton, Sequoia, and the IETF advocate for a thorough cryptography
refresh, RFC 9580. The inability for the two sides to agree on one proposal has
left PGP with two.</p>
I don't want to dive too deep into the semantics between the two different
proposals, since it's bad enough that the standard has become plagued with
in-fighting. Instead, I'll talk about some of the features that both proposals
bring to the table to address the points mentioned in Real-World
Cryptography</em>.2</a></sup></p>
Authenticated encryption</h2>
Let's start with authenticated encryption:</p>

PGP does not have authenticated encryption and is, thus, not secure if used
without signatures. (David Wong)</p>
</blockquote>
To clarify the author's point, RFC 4880 does include a device for authenticated
encryption known as MDC (Modification Detection Code). However, MDC doesn't
provide what the author of Real-World Cryptography</em> would consider
cryptographically strong authentication.</p>
Let me zoom out for a second to explain why any authenticated encryption method
is important for PGP. The attack looks something like this:</p>

Alice sends an encrypted mail to Bob. Alice chooses not to sign the message.</li>
Mallory intercepts the encrypted mail. Mallory cannot read the contents of
the message, but they can arbitrarily modify the ciphertext itself. They do
so.</li>
Bob receives the modified ciphertext and decrypts it. Bob has no idea that
the message contents were modified in transit by Mallory. The decrypted
plaintext no longer matches Alice's intended message.</li>
</ol>
Authenticated encryption allows Bob to verify in step 3 whether or not the
ciphertext received is consistent with the original message composed by Alice.
With MDC, Bob decrypts the message, discovers that it has been tampered with,
and knows that there's a Mallory sitting in the middle of the correspondence.</p>
Going back to David Wong's point, MDC is not considered a sufficient form of
authenticated encryption from a cryptographer's standpoint. The verification
code is included within the ciphertext, so when Bob verifies the message in step
3, Bob must first decrypt the entire message. This leaves an open space where a
PGP implementation may accidentally leak message contents and reveal information
due to bad error handling.3</a></sup></p>
In the original spec, the limitations of MDC are considered intentional risk.
Within the RFC, the authors note that they chose MDC because they wanted to
preserve the deniability of messages. MDC achieves this because unlike
alternative authentication mechanisms, there's no secret key associating the
authentication to the original message author (Alice).</p>

OpenPGP addresses this desire to have more security than raw encryption and
yet preserve deniability with the MDC system. An MDC is intentionally not a
MAC. Its name was not selected by accident. It is analogous to a checksum.
(RFC 4880)</p>
</blockquote>
Deniability is an important design goal for PGP simply because signing a message
is optional. If a user chooses not to sign a message, the system should not
implicitly sign said message with its authenticated encryption. Although the
contents of the message should be encrypted, they should not be
cryptographically linked to its author.</p>
Luckily in 2026 we have authenticated encryption mechanisms that both (a)
prevent decryption-oracle attacks and (b) don't sacrifice deniability. As Daniel
Huigens explains in his
crypto-refresh post for Proton Mail</a>:</p>

OpenPGP has had authenticated encryption for a long time, using a mechanism
called the “Modification Detection Code” (MDC). While this does the job,
modern authenticated encryption schemes achieve secrecy and authentication in
one integrated algorithm. Such encryption modes, dubbed AEAD algorithms, offer
improved performance at the same security level. (Daniel Huigens)</p>
</blockquote>
Both LibrePGP and RFC 9580, the two competing modern standards, include AEAD
algorithms that replace the MDC scheme from RFC 4880.</p>
Refreshed cryptography</h2>
It's probably clear from the previous section that the two new standards for PGP
address concerns related to obsolete cryptography. Once again citing Daniel
Huigens,</p>

[RFC 9580] deprecates old cryptographic primitives and algorithms, including
the hash algorithms MD5, SHA1, and RipeMD, the symmetric algorithms IDEA,
3DES, and CAST5, and the public-key algorithms ElGamal, DSA, and RSA keys of
less than 3072 bits (the security level comparable to Curve25519). These are
all considered less secure than their modern alternatives and, as a result,
are not fit for use in new data or even the consumption of existing data in
some cases. (Daniel Huigens)</p>
</blockquote>
That said, the current standards schism between LibrePGP and RFC 9580 is not
helping PGP users in adopting updated cryptographic algorithms. Both specs
introduce a new key format (v5 and v6 respectively) that are incompatible. As a
result, most users are still using v4 keys that use outdated cryptographic
algorithms. The whole thing is a bit of a mess, where v4 keys are an awkward
interoperability layer between the two incompatible modern formats.</p>
The tl;dr is that so long as you're using v4 keys, you're losing the
cryptographic improvements made in LibrePGP or RFC 9580. Because those v4 keys
are the only compatibility layer between the v5 and v6 proposals, most users are
using them. The vicious cycle ensues.</p>
Looking forward</h2>
Realistically I don't recommend anyone to go out of their way to set up PGP,
even if it has managed to nerd-snipe</a> me over the past
month. You should probably just use Signal.</p>
That said, I think PGP is a great way to start messing around with asymmetric
cryptography to help illustrate the concepts. I recommend
sq</a>, since it supports RFC 9580 and has excellent
documentation. And hey, if you want to set it up with Thunderbird,
I have a post for that</a>.</p>
Below are the handful of articles I used as reference when writing this post:</p>

RFC 4880</a></li>
RFC 9580</a></li>
A schism in the OpenPGP world</a></li>
Modernizing and improving PGP security</a></li>
</ul>
^1</sup>Here's an example of metadata usage in the real world:
Proton Mail Helped FBI Unmask Anonymous ‘Stop Cop City’ Protester</a>.</p>
</div>
^2</sup>For the record, I think RFC 9580 is the sensible option. Full support goes
to Proton and their
efforts to modernize PGP</a>.
If you're interested in comparing the two proposals,
this article</a> offers a
thorough look at both.</p>
</div>
^{3</sup>
In Real-World Cryptography</em>, David Wong emphasizes that vulnerabilities
caused by mis-implementations are a cryptography problem, because
cryptographic standards should ideally avoid situations where implementation
mistakes lead to vulnerabilities.</p>
</div>}


Email Encryption with Sequoia PGP and Thunderbird
2026-02-14T00:00:00+00:00
The
Discord Face ID debacle</a>
has reminded me that centralized platforms routinely abuse user privacy. I can
empathize with the desire to protect underage users, but requiring facial
identification is overreach. It's especially insulting when Discord
leaked some 70,000 government IDs in October 2025</a>
under similar pretenses.</p>
While my friends and I scour the web for an alternative place to call our
digital home, I finally gathered enough motivation to finish setting up
end-to-end encrypted email (via Thunderbird and Sequoia PGP). If you're curious
about encrypted email, this post is for you.</p>
Why encrypt email?</h2>
The first point to understand is that you don't need a good reason to want
encrypted email. Or encrypted anything, for that matter. FSF puts it nicely in
their Email Self-Defense</a> manual:</p>

Bulk surveillance violates our fundamental rights and makes free speech risky.
[...] Even if you have nothing to hide, using encryption helps protect the
privacy of people you communicate with, and makes life difficult for bulk
surveillance systems.</p>
</blockquote>
I don't have any particular need</em> to send encrypted email. I do, however,
believe that privacy is a fundamental right. Personal data should not be
collected or monitored, no matter how innocuous. I want others who feel the same
way to have an easy mechanism for communicating with me under those
circumstances. In the realm of email, that's PGP.</p>
Generating OpenPGP keys with Sequoia PGP</h2>
Thunderbird is my email client of choice and offers a few different ways to set
up end-to-end encryption (E2EE):</p>

Generate OpenPGP keys within Thunderbird directly</li>
Import OpenPGP keys generated from an external library (like Sequoia PGP or
GnuPG)</li>
S/MIME certificates, which are out of the scope of this article</li>
</ul>
This article is about Sequoia PGP</a>, so I obviously
opted to import my keys instead of using
Thunderbird OpenPGP</a>.</p>
Sequoia is not the only choice of PGP library. The most widely used library is
GnuPG</a>, venerable yet often criticized for its
complexity and support for outdated algorithms. I recommend Sequoia because it
promises to be safe by default and opinionated, two phrases that resonate with
me.</p>
Follow these steps to generate a PGP key with Sequoia and import it into
Thunderbird.</p>
Install Sequoia PGP:</p>
brew</span> install sequoia-sq</span></span></code></pre>
Generate your key:</p>
sq</span> key generate --profile rfc4880 --own-key</span> \</span></span>
  --name "Alice Example" --email alice@example.com</span></span></code></pre>

Note: although I included --profile rfc4880</code> in the command, it's technically
redundant since Sequoia uses RFC 4880 by default. I just wanted to reinforce
that Thunderbird follows OpenPGP RFC 4880, not RFC 9580 published in 2024.</p>
</blockquote>
You can use sq key list</code> to view the key you just generated. Take note of the
topmost entry, which provides the 40-character fingerprint that you'll use to
identify your key in future steps.</p>
If you're like me and use a custom domain with multiple email aliases, you need
to register each email alias to the PGP key you just generated. In PGP parlance,
these aliases are called user ids. User ids are included in your key export, so
it's important you complete this step before importing your key into
Thunderbird.</p>
# Only do this if you have extra email addresses to add to your key</span></span>
sq</span> key userid add --cert</span> $FINGERPRINT</span> \</span></span>
  --name Alice --email alice@work.example.com</span></span></code></pre>
Export your private key that you'll later import into Thunderbird:</p>
sq</span> key export --cert</span> $FINGERPRINT</span> ></span> secret.asc</span></span></code></pre>
Now open up Thunderbird, navigate to Account Settings > End-To-End Encryption,
and import secret.asc</code> via "Add key". If you have multiple email addresses
configured in Thunderbird, go to "Manage Identities" and configure E2EE for each
one.</p>
Key exchange</h2>
Now that you have E2EE enabled, it's important to understand how that encryption
actually works. Email encryption is only as good as the contacts you have that
are also using PGP. If you're exchanging email with someone not using PGP, your
emails are plaintext regardless of your Thunderbird E2EE setup. PGP
fundamentally requires an exchange of public keys between both participants in
the conversation.</p>
This necessity has lead to networks of public keys known as key servers, e.g.
https://keys.openpgp.org/</a>. These are effectively phone books mapping email
addresses to verified public keys. You likely want to upload your own public key
to one such server.</p>
Within Thunderbird, you can discover public keys while composing an email via
the OpenPGP Key Assistant. Alternatively, you can search with Sequoia:</p>
sq</span> network search alice@example.com</span></span></code></pre>
If Sequoia successfully locates a key, it follows up with a helpful message
prompting you to verify the integrity of the key. The intent of this step is to
verify with the participant that the certificate indeed belongs to them.
Typically this happens via an alternative method of communication.1</a></sup></p>
# I verify that this fingerprint belongs to Alice</span></span>
sq</span> pki link add --cert=</span>$FINGERPRINT</span> \</span></span>
  --userid="Alice <alice@example.com>"</span></span></code></pre>
I won't dive too far into the details, but the nature of key servers and key
verification is widely known as the Web of Trust. It's good practice to verify
the keys of your PGP contacts because the act is effectively vouching for the
authenticity of that key.</p>
Updates to this post</h2>
A prior version of this post used GnuPG instead of Sequoia PGP, following the
FSF guide Email Self-Defense</a>. Since
then, I've migrated to Sequoia PGP and use SSH instead of GPG to sign my git
commits.</p>
The reasons for this change have to do with my recent discovery of
A schism in the OpenPGP world</a> and its
implications for PGP as a cryptographic standard. I plan to detail my thoughts
on the subject in a future post, after I gather more research around the crazy
world of PGP RFCs and the divergence of LibrePGP and OpenPGP.</p>
I think it's unfortunate that the already vanishingly small number of PGP users
are further divided between the goal of backwards compatibility and modern
cryptographic techniques. I tend to side with the authors of Sequoia PGP and
their goal of a safe-by-default, opinionated implementation.</p>
^1</sup>The notion of fingerprint verification is core to asymmetric cryptography.
For example, Signal likewise has a verification process through
safety numbers</a></p>
</div>


Coding with Agents; Managers and Builders
2026-02-05T00:00:00+00:00
Like many software engineers I've been experimenting with coding agents as part
of my day job.1</a></sup> My approach is still in its infancy: a handful of tabs and
sessions organized by tmux, terminal split in half while coaching Claude through
planning and implementation, mostly focusing on just one task at a time. I
haven't seen the productivity boost lauded by tech executives, but I remain
impressed by the kinds of things Claude Code gets right.</p>
The more I work with agents, the more my job becomes centered around reviewing
code. And reviewing code is difficult! Properly reviewing a diff requires
acclimating within the headspace of the proposed change and understanding its
tradeoffs. Since I don't participate in the act of building, I lack the context
and theory behind the change. So when I review the code, simply reading the diff
isn't sufficient.</p>
The situation is a little different with AI agents because I drive the upfront
planning and problem description. In theory, I have the context of the change,
and even if I lack the process of typing it I have a general idea of how it came
to be. But in practice, coding with AI still feels a lot more like reviewing a
pull request than it does building a feature.</p>
All this to say, my day-to-day workflow is catered more towards reviewing code
than writing code. tmux</a> is absolutely
essential because it allows me to manipulate my terminal to prompt agents,
investigate implementation details, or run one-off tasks.
delta</a> is the newest addition to my kit,
improving the look of git diff</code> since I now scrutinize every line of code in my
working tree before wrapping it together into a commit.
ripgrep</a> and other CLI interfaces are
essential for crossing the gap between agent and manual work.</p>
As I work more with AI tools, my feelings towards programming have grown more
complicated. The shift from mostly writing code to mostly writing product
specifications is not one I'm particularly happy about. For many, coding is
nothing but an obstacle in the way of a successful product. For me, coding is
artistic expression. Building programs and structuring code in a maintainable
way is fun! Hell, editing text is fun.2</a></sup> Spending less time writing code and
more time writing specs or reviewing changesets has been a difficult transition.</p>
I've seen others mention this shift as a schism between builders and managers.
Folks who prefer composing instructions that delegate to agents, AI or human,
are managers. Folks who prefer typing text into an editor and watching programs
come alive are builders. Managers love the workflows AI tools enable. Builders
lament them. I won't go so far as to say I lament them, but more and more I find
myself avoiding AI tools on my personal projects.</p>
I'm also worried that AI causes skill to atrophy. Anthropic recently released a
paper studying the impact of AI on skill formation</a>3</a></sup>
in junior developers and the results do not look good. What this means for the
industry in coming years is an unnerving thought.</p>
^{1</sup>
For the record, I staunchly refuse to use AI for any of the writing on this
blog. Or really, any of my creative endeavors. I see AI merely as a
productivity tool, not a substitute for creativity.</p>
</div>
^{2</sup>
It helps when you practice fancy keybindings, adding an extra layer of
problem solving to the process of refining text in an editor.</p>
</div>
^{3</sup>
Anthropic's research into these kinds of topics is exactly why I'm happy to
support their AI tools.</p>
</div>}}}


Prototyping a Chess Puzzle Game
2026-01-10T00:00:00+00:00
Monster Chess</a> is my attempt at a chess
puzzle game that doesn't require any knowledge of chess except the movement of
the pieces.</p>
Rules of Monster Chess:</p>

You can only move white pieces.</li>
Capturing a piece turns your current piece into the kind that you captured.</li>
Pawns do not promote on the back rank.</li>
You can refresh the page to reset the level.</li>
</ul>
There are 12 puzzles in all.
Give them a try</a>!</p>
Read on to learn how the game was made.</p>
Creating Monster Chess</h2>
I love chess tactics puzzles, but I hate playing chess. It's a very
contradictory hobby.</p>
Unfortunately, to solve a chess puzzle one must have a deep understanding of the
game of chess. Not just the movement of the pieces, mind you, but various
tactics that make up fundamental strategy. Mating puzzles are the most obvious,
but deeper into the realms of chess puzzles are forks, pins, skewers,
sacrifices, discovered checks, zugzwang, and so on. Enjoying a chess puzzle is
entirely hinged on knowing why a particular sequence of moves is the single
correct answer. Not an easy feat!</p>
Despite this, chess puzzles are beautifully expressive. A board position just
begs to be solved, each piece artfully contributing constraints to the
possibility space. White to move, mate in 2.</p>
</p>
So, I got to thinking. What would a chess puzzle look like if it didn't assume
any prior knowledge of chess, except for the movement of the pieces?</p>
The first thing I removed was the opponent. If we're no longer playing the game
of chess, but simply using the pieces of chess to define a puzzle language, the
need for opponent interactions are gone. No more deducing opponent reactions in
response to a move.</p>
I recall Puzzmo's paper puzzle remix</a>
of Really Bad Chess. It tweaked the classic mating puzzle format by introducing
multiple kings into a single board position and asking for unique checkmate
combinations by different pieces. It was a unique spin on the format, but
retained too much chess tactic DNA for the result I wanted.</p>
Without an opponent, tactic puzzles fall apart. Mating puzzles are fun, but
lacking originality. This is when I stumbled into the central puzzle idea for
Monster Chess: the piece that captures morphs into the one taken captive.</p>
With the main idea out of the way, it didn't take long to pin down the rest of
the puzzle constraints. The win condition becomes very natural: clear the board
of enemy pieces. Building interesting puzzles means constraining that movement
set with pieces that are limited, like pawns. Each puzzle is focused on ensuring
the player executes the proper sequence of moves else they get stuck in an
irredeemable position.</p>
Lichess-inspired tech stack</h2>
Around the time I was thinking about Monster Chess I was investigating the
Lichess frontend architecture. Lichess doesn't use a popular frontend framework,
like React or Vue. Instead, it uses a tiny virtual DOM (VDOM) library called
snabbdom</a>. The architecture that stitches
the snabbdom views, game logic, and server-rendered data together is custom-made
by Lichess.</p>
I can speculate why Lichess chose snabbdom over alternatives:</p>

Lichess predates modern frameworks</li>
Performance is key, fewer framework layers are a positive</li>
Maintainability takes precedence over shiny tools</li>
Lichess has unique UI considerations</li>
</ul>
Then again, why bother with a VDOM library at all?</p>
I think the answer boils down to philosophical alignment with the Scala backend.
Vanilla JS (or jQuery, which would've been more relevant in the 2010s) is
fundamentally imperative. It's up to the developer to figure out how they want
to stitch together state and UI, and that process often involves wrapping state
updates with targeted DOM mutations.</p>
Here's a simple example comparing a vanilla JS counter to a snabbdom counter.</p>
Vanilla JS:</p>
<</span>button</span> id</span>=</span>"counter"</span>></span>Count: 0</span></</span>button</span>></span></span>
</span>
<!-- UI updates live a ways away from the DOM --></span></span>
<</span>script</span>></span></span>
  let</span> count</span> =</span> 0</span></span>
  const</span> button</span> =</span> document</span>.</span>getElementById</span>(</span>'counter'</span>)</span></span>
</span>
  button</span>.</span>addEventListener</span>(</span>'click'</span>, ()</span> =></span> {</span></span>
    count</span>++</span></span>
    // Targeted DOM mutation in response to a state update</span></span>
    button</span>.</span>textContent</span> =</span> `Count: </span>${</span>count</span>}</span>`</span></span>
  }</span>)</span></span>
<</span>/</span>script</span>></span></span></code></pre>
Snabbdom:</p>
let</span> count</span> =</span> 0</span></span>
let</span> container</span> =</span> document</span>.</span>getElementById</span>(</span>'app'</span>)</span></span>
</span>
// UI = f(state)</span></span>
function</span> view</span>(</span>count</span>) {</span></span>
  return</span> h</span>(</span></span>
    'button'</span>,</span></span>
    {</span></span>
      on</span>:</span> {</span></span>
        click</span>:</span> ()</span> =></span> {</span></span>
          count</span>++</span></span>
          render</span>()</span></span>
        },</span></span>
      },</span></span>
    },</span></span>
    `Count: </span>${</span>count</span>}</span>`</span>,</span></span>
  )</span></span>
}</span></span>
</span>
// The library handles figuring out which bits of state</span></span>
// correspond to which DOM updates</span></span>
function</span> render</span>() {</span></span>
  container</span> =</span> patch</span>(container</span>,</span> view</span>(count))</span></span>
}</span></span></code></pre>
Snabbdom allows the UI to be represented declaratively as a function of state.
Re-rendering concerns the entire application, not just a single unit of the DOM.
Developers don't need to worry about applying DOM updates as a result of state
changes; instead they write their UI, write their application logic, and let
re-renders handle the rest.</p>
As you might expect, re-rendering the entire DOM tree would be prohibitively
expensive and wasteful. Hence the virtual DOM. Snabbdom figures out which DOM
nodes need to be updated based on state changes, using the VDOM diff as a guide.
Then it updates only the necessary nodes.</p>
Flux architecture for snabbdom</h3>
Zooming out a bit, it's important to note that snabbdom is just a VDOM library.
It does not prescribe a technique for managing state in your application or a
philosophy around triggering re-renders. That's the realm of a framework.</p>
Lichess organizes state into
controllers</a>.
A simplified example looks something like this:</p>
class</span> EditorCtrl</span> {</span></span>
  castlingRights</span>:</span> CastlingRights</span></span>
</span>
  onChange</span>() {</span></span>
    // Update state</span></span>
    this</span>.</span>castlingRights</span> =</span> computeCastlingRights</span>()</span>;</span></span>
    // And trigger a re-render</span></span>
    this</span>.</span>rerender</span>()</span>;</span></span>
  }</span></span>
}</span></span>
</span>
// UI = f(ctrl)</span></span>
function</span> view</span>(</span>ctrl</span>:</span> EditorCtrl</span>) {</span></span>
  return</span> h</span>(</span>'div.board-editor'</span>,</span></span>
    {</span></span>
      on</span>:</span> {</span></span>
        click</span>:</span> ()</span> =></span> {</span></span>
          ctrl</span>.</span>onChange</span>()</span></span>
        }</span></span>
      }</span></span>
    },</span></span>
    [</span>...</span>])</span></span>
}</span></span>
</span>
// Initialize snabbdom onto the current page</span></span>
export function</span> initModule</span>() {</span></span>
  // Container for game state and logic</span></span>
  const</span> ctrl</span> =</span> new</span> EditorCtrl</span>(rerender)</span>;</span></span>
</span>
  // First render pass to generate initial DOM</span></span>
  const</span> el</span> =</span> document</span>.</span>getElementById</span>(</span>'board-editor'</span>)</span>!</span>;</span></span>
  let</span> vnode</span> =</span> patch</span>(el</span>,</span> view</span>(ctrl))</span>;</span></span>
</span>
  // Trigger re-renders to update the UI after a state change</span></span>
  function</span> rerender</span>() {</span></span>
    vnode</span> =</span> patch</span>(vnode</span>,</span> view</span>(ctrl))</span>;</span></span>
  }</span></span>
}</span></span></code></pre>
For the purposes of Monster Chess, I didn't want to worry about manually
triggering re-renders on state changes. Any meaningful action in Monster Chess
is going to result in a UI update, so I can simply re-render indiscriminately.
So, I took a few liberties with the Lichess style of things by adapting the data
flow to something that resembles
Flux</a> (so 2014,
dude).</p>
Here's a simplified counter example, demonstrating the structure:</p>
class</span> Store</span> {</span></span>
  state</span> =</span> {</span> count</span>:</span> 0</span> };</span></span>
</span>
  // If you don't like mutation, you could always go redux-style:</span></span>
  // this.state = reduce(action)</span></span>
  update</span>(</span>action</span>) {</span></span>
    switch</span> (action</span>.</span>type)</span> {</span></span>
      case</span> "inc"</span>:</span></span>
        this</span>.</span>state</span>.</span>count</span>++</span>;</span></span>
        break</span>;</span></span>
      case</span> "dec"</span>:</span></span>
        this</span>.</span>state</span>.</span>count</span>--</span>;</span></span>
        break</span>;</span></span>
    }</span></span>
  }</span></span>
}</span></span>
</span>
const</span> view</span> =</span> (</span>dispatch</span>)</span> =></span> (</span>state</span>)</span> =></span> {</span></span>
  return</span> h</span>(</span>"div"</span>,</span> [</span></span>
    h</span>(</span>"p"</span>,</span> `count: </span>${</span>state</span>.</span>count</span>}</span>`</span>)</span>,</span></span>
    h</span>(</span>"button"</span>, {</span></span>
      on</span>:</span> {</span> click</span>:</span> ()</span> =></span> dispatch</span>(</span>{</span> type</span>:</span> "inc"</span> }</span>)</span> }</span></span>
    },</span> "+"</span>)</span>,</span></span>
    h</span>(</span>"button"</span>, {</span></span>
      on</span>:</span> {</span> click</span>:</span> ()</span> =></span> dispatch</span>(</span>{</span> type</span>:</span> "dec"</span> }</span>)</span> }</span></span>
    },</span> "-"</span>)</span>,</span></span>
  ])</span>;</span></span>
};</span></span>
</span>
// Bootstrap boilerplate</span></span>
window</span>.</span>addEventListener</span>(</span>"DOMContentLoaded"</span>, ()</span> =></span> {</span></span>
  const</span> container</span> =</span> document</span>.</span>querySelector</span>(</span>"#app"</span>)</span>;</span></span>
</span>
  const</span> store</span> =</span> new</span> Store</span>()</span>;</span></span>
</span>
  // When actions are dispatched to the store, we always</span></span>
  // re-render afterwards.</span></span>
  function</span> dispatch</span>(</span>action</span>:</span> Action</span>) {</span></span>
    store</span>.</span>update</span>(action)</span>;</span></span>
    render</span>()</span>;</span></span>
  }</span></span>
</span>
  const</span> makeView</span> =</span> view</span>(dispatch)</span>;</span></span>
  let</span> vnode</span> =</span> patch</span>(container</span>,</span> makeView</span>(store</span>.</span>state))</span>;</span></span>
</span>
  function</span> render</span>() {</span></span>
    vnode</span> =</span> patch</span>(vnode</span>,</span> makeView</span>(store</span>.</span>state))</span>;</span></span>
  }</span></span>
}</span>)</span>;</span></span></code></pre>
The view is constructed with two parameters, dispatch</code> and state</code>. dispatch</code>
passes messages through the store and triggers a re-render. During the render
pass, snabbdom diffs the VDOM and applies changes to the UI based on the most
recent value of state</code>.</p>
I'm sure that Lichess benefits from more control over the render lifecycle of
its application, but I definitely appreciate the simplicity of Flux. The view
doesn't call directly into a stateful controller, it merely reads state for a
render pass and dispatches the occasional action back into the store.</p>
To put things into more concrete terms, here's a view into Monster Chess's
Action</code> type, demonstrating all of the events that are dispatched by the view:</p>
export type</span> Action</span> =</span></span>
  |</span> {</span> type</span>:</span> '</span>change_mode</span>'</span>;</span> payload</span>:</span> {</span> mode</span>:</span> '</span>select</span>'</span> } }</span></span>
  |</span> {</span> type</span>:</span> '</span>select_level</span>'</span>;</span> payload</span>:</span> {</span> level</span>:</span> number</span> } }</span></span>
  |</span> {</span> type</span>:</span> '</span>select_piece</span>'</span>;</span> payload</span>:</span> {</span> piece</span>:</span> Piece</span> } }</span></span>
  |</span> {</span> type</span>:</span> '</span>deselect</span>'</span> }</span></span>
  |</span> {</span></span>
      type</span>:</span> '</span>move</span>'</span></span>
      payload</span>:</span> {</span></span>
        to</span>:</span> Square</span></span>
        original</span>:</span> Piece</span></span>
        captured</span>:</span> Piece</span> |</span> undefined</span></span>
      }</span></span>
    }</span></span></code></pre>Why not just use React?</h3>
Simply put: novelty. I wanted to see how far I could take a VDOM library without
all of the extra framework primitives.</p>
That said, I would generally avoid React for projects like Monster Chess. React
is the kind of tool that is acceptable across the board, but doesn't excel in
any particular category. Its main draw is mindshare, reducing the number of
decisions made by large teams. Its API is complicated (useEffect</code> dependencies,
anyone?) and its VDOM algorithm is now a complicated concurrent scheduler. For
tiny web games it's overkill.</p>
If you're interested in making your own games with this snabbdom stack, check
out my game template</a>.</p>


Guide to Cryptic Crosswords
2025-11-03T00:00:00+00:00
The cryptic is a special kind of crossword that is unfortunately lacking
popularity in the US. Unlike it's American counterpart (e.g. the NYT daily),
every clue in a cryptic utilizes some kind of misleading wordplay. The result is
a crunchy (and hilarious) word puzzle that is a delight to solve.</p>
To the uninitiated, the cryptic crossword is downright indecipherable. To the
initiated, well, it's often just as confusing. But therein lies the fun of the
cryptic: every clue is its own little mini-puzzle.</p>
Here's an example cryptic clue, plucked from a recent
Minute Cryptic</a>:</p>

Golf lesson's beginning in month six for Tiger Woods? (6)</strong></p>
</blockquote>
The answer is JUNGLE. Confused? Good.</p>
On the surface, a cryptic clue is a humorous phrase with little to no relation
to its answer. Hiding within is a meta-textual puzzle composed of each word of
the clue, a recipe that points the solver to the solution. This recipe often
consists of the following ingredients:</p>


Definition</strong>, the straightforward meaning of the solution</p>
</li>

Fodder</strong>, the letters you will play around with to reach the solution</p>
</li>

Wordplay</strong> indicator(s), hinting at what to do with the Fodder to reach the
Definition</p>
</li>

Length indicator</strong>, a parenthetical showing how many letters and words are
in the solution</p>
</li>
</ul>
Not every cryptic clue will contain every one of these elements, but the
majority of clues incorporate at least a few. Let's look at another example:</p>

Tide turns to change (4)</strong></p>
Answer: EDIT</p>
</blockquote>
A surface reading of the clue suggests a shoreline changing tides. It should
come as no surprise that water has nothing to do with the actual 4-lettered
solution.</p>
Breaking the clue into its components provides:</p>


Definition</strong>: change</p>
</li>

Fodder</strong>: tide</p>
</li>

Wordplay indicator</strong>: turns</p>
</li>

Length</strong>: a single, 4-letter word</p>
</li>
</ul>
Recognizing a clue's recipe takes time and practice. In fact, the vast majority
of time spent solving a cryptic is trying to figure out the correct recipe!
Often a tough clue will hint at several possible devices, of which only one is
the proper answer.</p>
The definition part of a clue often appears at the beginning or the end, as is
the case with the above. This means "tide" or "change" are the most likely
suspects.</p>
From there, look through the remaining elements for some sign of wordplay. "To"
isn't a good guess, there's not much room for anything interesting. "Turn", on
the other hand, can be taken a few different ways. It can mean "change", as is
consistent with the surface-reading of the clue (indicating changing tides). Or,
taken literally, "turn" can mean "swap direction" or "reverse". Wordplay
indicator located.</p>
Next up: which word is reversed? With the two suspects "tide" and "change", only
one word is exactly 4 letters. Therefore, reverse "tide" to find "edit", a
word that means "change"</strong>.</p>
Turns is just one of hundreds of wordplay indicators that you’ll find out in the
wild. It belongs to a category of "reversals", indicators that require reversing
the Fodder to reach the solution. A few other indicators belonging to the same
category are "reversed", "goes back", or "in retrospect".</p>
Categories of wordplay</h2>
The different kinds of wordplay that you might see in a cryptic crossword can
often be grouped into broader categories. You've already seen Reversals</strong>,
wordplay that reverses the letters of a word. Here are some other examples of
cryptic wordplay techniques.</p>
Anagrams</h3>
Rearrange letters to form a new word.</p>
Indicators: destroyed, messed up, rearranged.</p>
Example:</p>

Wine with no tip? Crazy (5)</strong></p>
Answer: PINOT. Parsed as NO TIP annagrammed (made crazy).</p>
</blockquote>
Deletions</h3>
Remove one or more letters from a word.</p>
Indicators: removed, defaced, dropped off.</p>
Example:</p>

Trim tabs for six pack (3)</strong></p>
Answer: ABS. Parsed as TABS minus the first letter (trim).</p>
</blockquote>
Hidden words</h3>
Find a word hidden within one or several other words.</p>
Indicators: hides, contains.</p>
Example:</p>

World's tallest mountain home hidden in fine palace (5)</strong></p>
Answer: NEPAL. Parsed as hidden in FINE PALACE.</p>
</blockquote>
Soundalikes</h3>
Swap one word for another that sounds similar (e.g. homophone).</p>
Indicators: broadcasted, said, announced.</p>
Example:</p>

Disregard mumbled greeting (5)</strong></p>
Answer: WAIVE. Parsed as homophone (mumbled) of WAVE (greeting).</p>
</blockquote>
Charades</h3>
Substitute one word for another.</p>
Indicators: none required (this one is tricky!)</p>
Example:</p>

Pass standard edition, no longer active (5)</strong></p>
Answer: LAPSE. Parsed as LAP (pass) SE (standard edition).</p>
</blockquote>
Containments</h3>
Place one word inside of another.</p>
Indicators: accepts, infiltrates, sandwiches (example from Minute Cryptic).</p>
Example:</p>

Golf lesson's beginning in month six for Tiger Woods? (6)</strong></p>
Answer: JUNGLE. Parsed as first letters of GOLF LESSON (beginning) placed
within (in) JUNE (month six).</p>
</blockquote>
Double definitions</h3>
Two definitions for the same word.</p>
Indicators: none required.</p>
Example:</p>

Medicine sheds fluff (5)</strong></p>
Answer: PILLS. Parsed as sheds fluff as in a sweater.</p>
</blockquote>
All of the above</h3>
Nothing limits a cryptic crossword clue to a single wordplay device. Most clues
will combine several wordplay techniques to make more interesting words and
combinations.</p>
Example:</p>

Seasons every other shallot with top spice (5)</strong></p>
Answer: SALTS. Parsed as every other letter in SHALLOT + first letter (top) of
SPICE.</p>
</blockquote>
And another:</p>

Prepare ambush: half partners, half betrayal, full reversal (3,1,4)</strong></p>
Answer: LAY A TRAP. Parsed as PARTners (half) + betrAYAL (half) reversed.</p>
</blockquote>
&lit</h3>
Pronounced "and lit", a curious construction. &lit clues do not have a separate
definition. Instead, the entire clue is considered the definition. It's best to
demonstrate with an example (this one comes from Minute Cryptic):</p>

Cop in male form! (9)</strong></p>
Answer: POLICEMAN.</p>
</blockquote>
The answer "POLICEMAN" fits the entire clue, a "cop in male form". It's also
achieved via the anagram indicator "form" that suggests rearranging "cop in
male". Sneaky!</p>
Indicators: none needed, although many outlets like Minute Cryptic will end the
clue with "?!" to help indicate that an &lit is in play.</p>
Learning to learn</h2>
It can be difficult to recognize wordplay techniques when you're first getting
started with cryptics. Here are a few tips and resources to help ease the path:</p>


Minute Cryptic</a> is an accessible cryptic
crossword outlet that releases a new clue every day. Start here!</p>
</li>

When solving, don't be afraid to reveal an answer to reverse-engineer the
wordplay. That's a great way to learn your way around the different wordplay
devices!</p>
</li>

The Guardian</a> offers a free,
introductory puzzle called the Quick Cryptic (not to be confused with the
"Quiptic", which is harder). Be forewarned that there may be one or two
British idioms in any given puzzle.</p>
</li>

Fifteensquared</a> collects detailed answers
(AKA parses) for popular British cryptic crosswords. If you're solving the
Guardian (among others), this site is a great reference.</p>
</li>
</ul>
You can find the cryptic crosswords I've constructed over here</a>.</p>


Why React Matters
2025-10-26T00:00:00+00:00
A recent popular article compares
React to Backbone</a>, arguing that React
is not much of an improvement. I think this article profoundly misses the point.
And I don't even like React!</p>
Before discussing what the article gets wrong, I want to quickly mention what it
gets right. These bullet points captured from the article are a great list of
React-isms that are worthy of criticism:</p>

key</code> as a mandatory prop for lists is fraught</li>
form inputs cannot initialize with undefined</code>, drawing a strange division
between controlled and uncontrolled controls</li>
useEffect</code> dependency arrays are difficult to understand</li>
batched updates lead to awkward APIs, like the callback form of setState</code></li>
</ul>
React has many rough edges that are difficult for beginners to wrap their heads
around, particularly useEffect</code> and all of the intricacies of dependency
management. I can't tell you how many React developers have made the mistake of
syncing state via effects when they could simply derive it with a variable
assignment.</p>
That said, the article hand-waves over the main reason this complexity exists:
the ability to represent UI as a function of state. Or, put another way,
unidirectional data flow.</p>
The Backbone example provided by the article clearly demonstrates the lack of
this ability. Below is the Backbone render function, tasked with assembling the
initial UI of the view:</p>
  render</span>()</span> {</span></span>
    this</span>.</span>$el</span>.</span>html</span>(</span>`</span></span>
      <div></span></span>
        <input type="password" placeholder="Enter password"></span></span>
        <div class="space-y-2"></span></span>
          ${</span>[</span>reqs</span>]</span>.</span>map</span>(</span>label</span> =></span> `</span></span>
            <div></span></span>
              <div></div></span></span>
              <span></span>${</span>label</span>}</span></span></span></span>
            </div></span></span>
          `)</span>}</span>.join('')</span></span>
        </div></span></span>
      </div></span></span>
    `</span>)</span>;</span></span>
    return</span> this</span>;</span></span>
  }</span></span></code></pre>
And the event handler that triggers on changes made to the input:</p>
  updatePassword</span>(e)</span> {</span></span>
    const</span> pwd</span> =</span> e</span>.</span>target</span>.</span>value</span>;</span></span>
    const</span> reqs</span> =</span> [</span></span>
      // ...</span></span>
    ]</span>;</span></span>
</span>
    this</span>.</span>$</span>(</span>'.space-y-2'</span>)</span>.</span>html</span>(reqs</span>.</span>map</span>(</span>([</span>label</span>,</span> met</span>])</span> =></span> `</span></span>
      <div class="flex items-center gap-2"></span></span>
        <div></span></span>
          ${</span>met</span> ?</span> '✓'</span> :</span> ''</span>}</span></span>
        </div></span></span>
        <span></span></span>
          ${</span>label</span>}</span></span>
        </span></span></span>
      </div></span></span>
    `</span>)</span>.</span>join</span>(</span>''</span>))</span>;</span></span>
  }</span></span></code></pre>
Notice that the event handler is tasked with a localized DOM manipulation. When
the input change event fires, the handler queries the DOM and replaces the HTML
in-place. The details of the UI are now contained in two different places: the
updatePassword</code> event handler and the render</code> function.</p>
This kind of separation is exactly what the pre-React world struggled to
maintain. When state is kept separate from the UI, yet requires that the UI is
manually updated when that state is changed, complications ensue.</p>
Contrast this with the React solution, where the developer is tasked with
constructing state variables (via useState</code>) that update the UI automatically:</p>
const</span> PasswordStrength</span> =</span> ()</span> =></span> {</span></span>
  const</span> [</span>password</span>,</span> setPassword</span>]</span> =</span> useState</span>(</span>''</span>)</span></span>
</span>
  const</span> requirements</span> =</span> [</span></span>
    // ...</span></span>
  ]</span></span>
</span>
  return</span> (</span></span>
    <</span>div</span>></span></span>
      <</span>input</span></span>
        type</span>=</span>"password"</span></span>
        value</span>=</span>{</span>password</span>}</span></span>
        onChange</span>=</span>{(</span>e</span>)</span> =></span> setPassword</span>(e</span>.</span>target</span>.</span>value)</span>}</span></span>
        placeholder</span>=</span>"Enter password"</span></span>
      /></span></span>
</span>
      <</span>div</span> className</span>=</span>"space-y-2"</span>></span></span>
        {</span>requirements</span>.</span>map</span>(</span>(</span>req</span>,</span> idx</span>)</span> =></span> {</span></span>
          const</span> isMet</span> =</span> req</span>.</span>check</span>(password)</span></span>
          return</span> (</span></span>
            <</span>div</span> key</span>=</span>{</span>idx</span>}</span>></span></span>
              <</span>div</span>></span>{</span>isMet</span> ?</span> '✓'</span> :</span> ''</span>}</span></</span>div</span>></span></span>
              <</span>span</span>></span>{</span>req</span>.</span>label</span>}</span></</span>span</span>></span></span>
            </</span>div</span>></span></span>
          )</span></span>
        }</span>)</span>}</span></span>
      </</span>div</span>></span></span>
    </</span>div</span>></span></span>
  )</span></span>
}</span></span></code></pre>
The most notable difference between the two approaches takes place in the event
handler. In React, the handler only updates the underlying component state. The
UI is automatically updated by the framework. I think it's hard to argue that
this kind of unidirectional data flow isn't a large improvement over Backbone.</p>
tl;dr</strong>: LOC comparisons are meaningless.</p>
I think a more interesting comparison is to consider the paradigm of
unidirectional data flow outside of React. If I want to render HTML as a
function of state, but avoid the complexities of React, what are my options?</p>
Web components are a natural place to look, since they're the HTML standard for
UI components. Luckily for us
Plain Vanilla Web</a> already provides a
comparison against React:
The unreasonable effectiveness of vanilla JS</a>.</p>
Notably on the topic of unidirectional data flow, the author of Plain Vanilla
Web has this to say:</p>

Because there is no framework patching the DOM with only the parts that
changed, we have to tread lightly and only update the DOM when and where that
is needed. Recreating too much of the DOM after a state change risks losing
state or causing performance issues.</p>
</blockquote>
And here we encounter the first rub of implementing unidirectional data flows:
re-rendering the entire application as a function of state is expensive! This
problem is exactly why React uses a
virtual DOM</a>.</p>
If you're willing to adopt a library, there are a ton of compelling options.
Lichess</a> famously uses
snabbdom</a>, which is effectively a virtual
DOM without a framework. If you like the look of HTML template strings,
lit-html</a> might be your jam.
Or, how about ditching the virtual DOM in favor of a
compiler</a> that writes localized DOM manipulations for you?</p>
All this to say, React is a solution built for web applications that are wholly
controlled by JavaScript. Server-rendered apps can and should opt for the
simpler solution of progressive enhancement because the scope of localized DOM
manipulations is much smaller when the server is tasked with re-rendering the
HTML. But please, don't use Backbone.</p>


A Thorough Look into RBS for Rails
2025-10-18T00:00:00+00:00
Back in 2020, Ruby 3.0 introduced a system for writing type definitions for Ruby
programs called RBS. Five years later, I rarely hear about it being used in
production Rails apps.</p>
The situation is somewhat similar to Ractors, another feature released with Ruby
3.0. The idea of Ractors brought a ton of buzz to the Ruby community because it
directly answered one of the major pain points of the language: sidestepping the
GVL for real parallelism. However, the reality of Ractors and the semantics of
shareable objects made them nearly impossible to adopt.</p>
I don't think RBS is in the same boat. At first blush, the toolset feels usable
and sophisticated, if lacking a bit in maturity. My experimentation with it has
already yielded benefit in a real-world Rails application. Adoption in an
existing codebase isn't trivial, but the semantics of RBS make it possible to do
incrementally.</p>
One of the main problems I see with RBS coverage on the web is that it's heavily
catered towards RubyGems or vanilla Ruby. There are not many articles that
explain RBS in Rails beyond a few cursory comparisons with Sorbet. This post
aims to fill that gap.</p>
Overall, I think RBS is in a fairly good spot. It still has rough edges, but
many of those edges are intrinsic to the nature of Ruby metaprogramming. Just
like with TypeScript and JavaScript, static types will change the way that you
write Ruby code to guarantee states and branches that are analyzable by static
tools. Whether that's good or bad depends on taste.</p>
Let's dive in.</p>
RBS tools</h2>
When working with RBS in a Rails codebase, you will make ample use of the
following tools:</p>

rbs</a>, used for signature prototyping (AKA code
generation) and managing signatures for RubyGems. I will refer to the gem from
now on as rbs</code> and the general signature format as RBS.</li>
Steep</a>, the gem that actually performs
type-checking.</li>
rbs_rails</a>, a handy set of Rake tasks to
help generate ActiveRecord signatures.</li>
</ul>
It's important to note that rbs</code> does not actually perform type-checking. It
only defines the syntax that you will use for writing signature files and
provides an API for accessing those signatures programmatically. Steep is the
program that actually checks if the types are valid.</p>
rbs</code> does, however, provide some handy CLI tools that you will use often. The
first is signature generation via rbs prototype</code>. The second is
RBS Collection</a>, effectively
Bundler for signatures. The RBS Collection community repository holds signatures
for many popular RubyGems, notably Rails and Sidekiq. Your application interacts
with RBS Collection via the rbs collection</code> command.</p>
As mentioned earlier, type-checking is performed by Steep. You will make
frequent use of the Steep CLI to check your app for warnings and errors, but you
can also integrate Steep directly into your text editor thanks to LSP. Here's an
example for Helix:</p>
# ~/.config/helix/languages.toml</span></span>
[</span>language-server.steep</span>]</span></span>
command</span> =</span> "steep"</span></span>
args</span> =</span> [</span>"langserver"</span>]</span></span>
</span>
[[</span>language</span>]]</span></span>
name</span> =</span> "ruby"</span></span>
language-servers</span> =</span> [</span>"steep"</span>]</span></span></code></pre>
I'll walk through using each of these tools in a Rails app in the next section.</p>
Adding RBS to a new Rails app</h2>
From a clean slate:</p>
rails</span> new myapp</span></span></code></pre>
Add Steep and run init</code> to generate its configuration file (Steepfile</code>):</p>
bundle</span> add steep</span></span>
bundle</span> exec steep init</span></span></code></pre>
Open up Steepfile</code> and you'll see a bunch of configuration options commented
out. Feel free to keep these around for future reference, but the configuration
that we'll use for this post is the following:</p>
# Steepfile</span></span>
target </span>:</span>app</span> do</span></span>
  signature </span>"sig"</span></span>
</span>
  check </span>"app"</span></span>
end</span></span></code></pre>
In short,</p>

A project may contain many targets, although we only make use of the :app</code>
target. You will likely want a separate target for tests.</li>
Our signature files go in the sig/</code> directory.</li>
When type-checking, we check the entirety of app/</code>. You can use separate
check</code> lines to incrementally adopt RBS, globbing particular files or
directories. More on this later.</li>
</ul>
Run the type-checker and you'll observe some 13 errors:</p>
bundle</span> exec steep check</span></span>
# Output of 13-ish errors and warnings...</span></span></code></pre>
Most of these errors and warnings are from missing definitions, as we haven't
yet added any signature files. However, quite a few of the errors point to
missing definitions in baseline Rails classes (e.g. ActiveRecord</code>). Steep
doesn't yet know how to locate signatures for Rails.</p>
Rails doesn't maintain its own signatures, but luckily there are
community-maintained signatures in RBS Collection. Let's set them up:</p>
rbs</span> collection init</span></span>
rbs</span> collection install</span></span></code></pre>
During installation, RBS Collection walks your Gemfile.lock</code> and pulls
signatures for gems that (a) are registered in the
repository</a> or (b) ship with their
own signatures via RubyGems. After running the initialization commands, you'll
have three new files/folders on your machine:</p>

rbs_collection.yaml</code> (a configuration file that we won't mess with)</li>
rbs_collection.lock.yaml</code> (equivalent to a Gemfile.lock</code>)</li>
.gem_rbs_collection/</code> (the actual signatures pulled during install)</li>
</ul>
You will likely want to add .gem_rbs_collection/</code> to your .gitignore</code>. You
will also want to add rbs collection install</code> to your bin/setup</code> to ensure
future users of your Rails app won't run into trouble with missing signatures.</p>
# bin/setup</span></span>
puts</span> "== Installing dependencies =="</span></span>
system</span>(</span>"bundle check"</span>)</span> ||</span> system!</span>(</span>"bundle install"</span>)</span></span>
</span>
puts</span> "== Installing signatures =="</span></span>
system!</span>(</span>"rbs collection install"</span>)</span></span>
# ...</span></span></code></pre>
Run check</code> again and observe that we've fixed all of the errors, though we
still have 5 warnings:</p>
bundle</span> exec steep check</span></span>
# 0 errors, 5 warnings</span></span></code></pre>
These warnings are from missing signatures in our actual application code. Since
the codebase is virtually empty, the prototype signatures generated by rbs</code> are
more than adequate:</p>
rbs</span> prototype rb --out-dir=sig/app/ app/</span></span>
</span>
# Output:</span></span>
Processing</span> `</span>app/</span>`</span>...</span></span>
  Generating</span> RBS for</span> `</span>app/controllers/application_controller.rb</span>`</span>...</span></span>
    -</span> Writing RBS to</span> `</span>sig/app/controllers/application_controller.rbs</span>`</span>...</span></span>
  Generating</span> RBS for</span> `</span>app/helpers/application_helper.rb</span>`</span>...</span></span>
    -</span> Writing RBS to</span> `</span>sig/app/helpers/application_helper.rbs</span>`</span>...</span></span>
  Generating</span> RBS for</span> `</span>app/jobs/application_job.rb</span>`</span>...</span></span>
    -</span> Writing RBS to</span> `</span>sig/app/jobs/application_job.rbs</span>`</span>...</span></span>
  Generating</span> RBS for</span> `</span>app/mailers/application_mailer.rb</span>`</span>...</span></span>
    -</span> Writing RBS to</span> `</span>sig/app/mailers/application_mailer.rbs</span>`</span>...</span></span>
  Generating</span> RBS for</span> `</span>app/models/application_record.rb</span>`</span>...</span></span>
    -</span> Writing RBS to</span> `</span>sig/app/models/application_record.rbs</span>`</span>...</span></span></code></pre>

Note: Steep doesn't actually care where your RBS files are located. Matching
the directory structure of app/</code> is merely convention. We'll cover a more
complicated directory structure that makes use of rbs subtract</code> later on.</p>
</blockquote>
Run check</code> again and observe no errors:</p>
bundle exec steep check</span></span>
# Type checking files:</span></span>
</span>
......</span></span>
</span>
No type error detected. 🫖</span></span></code></pre>
That's most of the setup done.</p>
Things get more complicated with the addition of rbs_rails</code>, which adds another
layer of code generation to our signature folder. I will talk through that setup
later on, after discussing incremental adoption.</p>
Incremental adoption for existing Rails apps</h2>
The nature of RBS signatures living separately from the Ruby code they represent
is convenient for incremental adoption. Same goes for the check</code> attribute in
our Steepfile</code>, which enables us to slowly migrate directories over to
type-checking.</p>
Incremental adoption isn't perfect because you'll inevitably have warnings for
untyped code, but that can be mitigated by only checking for errors in CI and
keeping an ignore file for known violations.</p>
The general strategy begins with a Steepfile</code> that works against one directory
at a time:</p>
# Steepfile</span></span>
target </span>:</span>app</span> do</span></span>
  signature </span>"sig"</span></span>
</span>
  check </span>"app/models"</span></span>
  check </span>"app/services/**/some-dir/*.rb"</span></span>
  # Add more as you develop more signatures...</span></span>
end</span></span></code></pre>
The workflow looks something like this:</p>

Add a new directory to Steepfile</code></li>
Prototype the directory</li>
Run steep check</code> and fix violations</li>
Ignore warnings or errors due to untyped references</li>
Check-in your work</li>
Repeat</li>
</ol>
I mention ignoring warnings or errors due to untyped references because you'll
often come across untyped code when working incrementally. For example, adding
types for a worker that references a model and a service, where the model or
service hasn't itself been typed.</p>
To help mitigate this issue, I recommend starting with app/models/</code>, as it's
arguably the directory with the widest surface area in your Rails app.</p>
Another helpful technique is to configure Steep to (a) ignore warnings and (b)
ignore certain known violations. You can automate this configuration with a Rake
task:</p>
# Rakefile</span></span>
require</span> 'steep/rake_task'</span></span>
</span>
Steep</span>::</span>RakeTask</span>.</span>new do</span> |</span>t</span>|</span></span>
  t</span>.</span>check</span>.</span>severity_level</span> =</span> :</span>error</span></span>
  t</span>.</span>check</span>.</span>with_expectations</span> =</span> true</span></span>
end</span></span></code></pre>
When we run Steep, we'll ask it to save known violations into a YAML file so
they can be ignored by future runs if the with_expectations</code> flag is true.
Generate the file of known violations by invoking Steep with a couple of extra
flags:</p>
bundle</span> exec steep --severity-level=error --save-expectations</span></span></code></pre>
After generating known violations, check in the file:</p>
git</span> add steep_expectations.yml</span></span></code></pre>
From here on out, the Rake task will ignore any violation present in that file.
Use this sparingly!</p>
Generating signatures for Rails models</h3>
As you'll quickly find out, the signatures generated via rbs prototype</code> are
very primitive. This is especially true for Rails models, which make heavy use
of metaprogramming.</p>
Instead of generating model signatures by hand, use
rbs_rails</a>. This gem provides a few Rake
tasks that generate ActiveRecord models based on their runtime behavior, filling
in a ton of detail that would otherwise be missing from rbs prototype</code>.</p>
bundle</span> add rbs_rails --require=false</span></span>
bin/rails</span> g rbs_rails:install</span></span></code></pre>
Installation provides the following tasks in rbs.rake</code> (under the rbs_rails</code>
namespace):</p>

generate_rbs_for_models</code></li>
generate_rbs_for_path_helpers</code></li>
all</code> (models and path helpers)</li>
</ul>
When migrating an existing app, your app/models</code> directory should probably be
your first priority and rbs_rails:all</code> is a huge help.</p>
Keep generated signatures separate</h4>
Up to this point in the post we've been prototyping signatures directly into our
app's sig/app/</code> folder. However, you do not want to do this with rbs_rails</code>.
In fact, rbs_rails</code> will place all of its generated signatures in
sig/rbs_rails/</code> by default, and for good reason.</p>
You don't want to be in a situation where your hand-written edits are
overwritten by generated code. This is especially relevant with rbs_rails</code>,
because you'll be re-running the rbs_rails</code> rake tasks anytime a model changes,
particularly if that change involves database migrations. Unlike the signatures
created by rbs prototype</code>, which serve merely as a starting point, the
signatures generated by rbs_rails</code> can and should be kept separate.</p>
To enable hand-written edits to rbs_rails</code>, we'll set up a wrapper task that
merges hand-written signatures with those generated programmatically. This
allows us to reliably re-run the rbs_rails</code> rake tasks without needing to worry
that the new signatures will overwrite custom modifications.</p>
# Rakefile</span></span>
namespace </span>:</span>rbs</span> do</span></span>
  task </span>:</span>generate</span> do</span></span>
    # Use rbs_rails to generate signatures</span></span>
    Rake</span>::</span>Task</span>[</span>'rbs_rails:all'</span>].</span>invoke</span></span>
</span>
    # Remove hand-written touch-ups from rbs_rails generated code.</span></span>
    # This assumes you have hand-written signatures in sig/app/models.</span></span>
    `bin/rbs subtract --write sig/rbs_rails sig/app/models`</span></span>
  end</span></span>
end</span></span></code></pre>
The necessary folder structure looks like this:</p>
sig/</span></span>
  rbs_rails/</span></span>
    app/</span></span>
      models/</span></span>
        user.rbs  # auto-generated</span></span>
  app/</span></span>
    models/</span></span>
      user.rbs    # hand-written</span></span></code></pre>
After running rbs:generate</code>, the auto-generated code will have definitions
removed if those definitions conflict with hand-written code. In effect,
hand-written code is always preferred to auto-generated. Both directories are
checked in to source control.</p>
The author of rbs subtract</code> and rbs_rails</code> wrote a design doc where you can
learn more about this workflow:
Design Doc of rbs subtract</a>.</p>
Signatures for third-party code</h3>
Using RBS Collection to manage third-party gems can be a little confusing, so
here are some guidelines.</p>
If a gem is part of RBS Collection (and present in your Gemfile.lock</code>) you're
good to go. Run rbs collection init/install</code> and reap the benefits of
community-maintained signatures.</p>
If a gem isn't in the collection and does not publish its own signatures, you
will need to provide them yourself.</p>
For stdlib gems, things get a little confusing. If that gem is truly part of the
Ruby stdlib, but not present in your Gemfile.lock</code>, you need to tell Steep that
it's active in your project. This is the case for gems like yaml</code> or net/http</code>
that need to be required despite existing in Ruby Core:</p>
target </span>:</span>app</span> do</span></span>
  # ... snip</span></span>
  library </span>"yaml"</span></span>
  library </span>"net-http"</span></span>
end</span></span></code></pre>
It's easy to forget what should and should not be added as a "library" in your
Steepfile, so here's my guidance. Never add third-party gems to your Steepfile.
Only add stdlib gems, if that gem is not present in your Gemfile.lock</code>.
Everything else is either already installed via RBS Collection or the signatures
do not exist and you will need to write them yourself.</p>
Code comments</h3>
By default rbs prototype</code> copies code comments from your Ruby files into your
RBS files. This brings up an interesting question: where should your comments
live, in the code or in the signatures?</p>
The answer is both!</p>
In RBS files, add comments that explain high-level details about the API. These
comments should describe the intended purpose of the class and help developers
understand how to use it.</p>
In Ruby files, add comments that explain the intricacies of the code. These
comments are made for those modifying the code to suit new purposes (or fix
existing bugs).</p>
For example,</p>
# feed_parser.rbs</span></span>
# Fetch and RSS/Atom feed and return a list of Articles.</span></span>
class</span> FeedParser</span></span>
  # @param url [String] The URL of the RSS or Atom feed.</span></span>
  def</span> initialize</span>: (</span>String</span> url</span>)</span> -></span> void</span></span>
</span>
  # Fetches and parses the feed, returning a list of articles.</span></span>
  # @return [Array[Article]]</span></span>
  def</span> articles</span>: ()</span> -></span> Array</span>[</span>Article</span>]</span></span>
end</span></span>
</span>
# feed_parser.rb</span></span>
class</span> FeedParser</span></span>
  def</span> articles</span></span>
    # Note that RSS and Atom differ in the following respects: ...</span></span>
  end</span></span>
end</span></span></code></pre>RBS will change the way you write Ruby code</h3>
I have found that, like TypeScript, RBS changes the way you write Ruby code. I
generally think this is good news for the clarity of your code.</p>
The most common case that I've run into is the issue of "flow specificity", or,
the inability of Steep to narrow a type based on context. Do not take this as a
bad mark against Steep, TypeScript suffers from the same issue. The problem is
that Ruby code carries certain patterns that are more prone to flow specificity
issues because of how Ruby developers like to write code.</p>
Here's an example:</p>
class</span> FooService</span></span>
  def</span> execute</span></span>
    return unless</span> some_variable</span></span>
</span>
    do_something_with</span>(</span>some_variable</span>)</span></span>
  end</span></span>
</span>
  private</span></span>
</span>
  def</span> do_something_with</span>(</span>value</span>)</span></span>
    # ...</span></span>
  end</span></span>
</span>
  def</span> some_variable</span></span>
    # ...</span></span>
  end</span></span>
end</span></span></code></pre>
Say that some_variable</code> is something that could be nil</code>. Here's the signature:</p>
class</span> FooService</span></span>
  @some_variable</span>:</span> Integer</span>?</span></span>
</span>
  def</span> execute</span>: ()</span> -></span> void</span></span>
</span>
  private</span></span>
</span>
  def</span> do_something_with</span>: (</span>Integer</span> x</span>)</span> -></span> void</span></span>
</span>
  def</span> some_variable</span>: ()</span> -></span> Integer</span>?</span></span>
end</span></span></code></pre>
Run Steep and you'll see the following error:</p>
app/services/foo_service.rb:5:22:</span> [error] Cannot pass a value of type </span>`</span>(</span>:</span>:Integer</span> |</span> nil</span>)</span>`</span> as</span> an argument of type</span> `</span>:</span>:Integer</span>`</span></span>
│</span>   (::Integer </span>|</span> nil</span>) </span><</span>: ::Integer</span></span>
│</span>     nil</span> <</span>: ::Integer</span></span>
│</span></span>
│</span> Diagnostic ID: Ruby::ArgumentTypeMismatch</span></span>
│</span></span>
└</span>     do_something_with</span>(</span>some_variable</span>)</span></span>
                        ~~~~~~~~~~~~~</span></span>
</span>
Detected</span> 1</span> problem from</span> 1</span> file</span></span></code></pre>
The problem is that although we check for the existence of some_variable</code> at
the beginning of execute</code>, some_variable</code> is a method. Steep cannot know that
the second call of some_variable</code> takes place after the first call was
validated, nor that the second call is guaranteed to be non-nil due to flow
control patterns.</p>
Here's the workaround:</p>
class</span> FooService</span></span>
  def</span> execute</span></span>
    value</span> =</span> some_variable</span></span>
    return unless</span> value</span></span>
</span>
    do_something_with</span>(</span>value</span>)</span></span>
  end</span></span>
  # ...</span></span>
end</span></span></code></pre>
Assigning the method to a variable, checking that variable, and continuing to
use that checked variable will lead Steep to the correct conclusion.</p>
Now although I mentioned that this exact issue also exists in TypeScript, I've
never seen it in practice. I don't think JS developers are incentivized to write
flow control in the Ruby way because JS doesn't have the same optional
parentheses that mask whether or not an identifier is a method or a variable
(playground link</a>):</p>
const</span> someVariable</span> =</span> ()</span>:</span> number</span> |</span> null</span> =></span> 42</span></span>
const</span> doSomething</span> =</span> (</span>n</span>:</span> number</span>)</span> =></span> {}</span></span>
</span>
// Looks weird and TypeScript complains!</span></span>
if</span> (</span>someVariable</span>())</span> {</span></span>
  doSomething</span>(</span>someVariable</span>())</span> // ArgumentError</span></span>
}</span></span></code></pre>
This is a contrived example, but it's a problem that I've seen numerous times in
a recently-converted Rails codebase. Especially when dealing with associations
that allow null</code>.</p>
The solution, I think, is to avoid writing Ruby code that proliferates nil</code>
values. That means restructuring code with fewer methods and more local
variables, that also means longer methods that pack more content, which finally
means fewer one-line methods.</p>
Clean Code aesthetics are on their way out, this is one more nail in the coffin.</p>
Conclusion</h2>
Adding types to an existing Rails app is not trivial, but RBS allows for
incremental adoption.</p>
After working with RBS in a production application for two weeks, my team has
already discovered a number of bugs that we've identified as real issues
matching our Airbrake exception logs. RBS clearly revealed the bug, often a
NoMethodError</code> pointing to an object that might be nil</code>, and identified other
potential failure points that did not happen to align with our primary execution
path.</p>
Resolving the bug in these circumstances wasn't always trivial due to the
tendency for Rubyists to wrap optional states behind methods that sidestep
Steep's type-checking. Rewriting classes to suit the signatures and eliminate
nil</code> values, however, has been a net positive.</p>
Overall, RBS has been well-worth the investment.</p>


Deno's stdlib is Available Outside Deno
2025-09-17T00:00:00+00:00
Out of the craziness that has been the last couple weeks of
NPM supply-chain drama</a> we're
reminded that Deno at least had a
few things right</a> when it pushed for a
secure-by-default</a> stance
towards third-party code. In the same general space we've seen
Pnpm</a>
disable postinstall scripts by default</a>
and more recently release some
minor mitigating configuration settings</a>.
It is certainly an interesting time to be a JavaScript developer, not that this
kind of issue is unique to NPM.</p>
There are, however, many reasons why NPM is the perfect target for this kind of
attack. JavaScript is a language with a small standard library, an enormous user
base, and a general social acceptance of insane node_modules</code> folders. We all
remember the
left-pad incident</a>, a mere
17 lines of code that sent the JavaScript ecosystem into a spiral.</p>
Anyway, this TIL isn't about all of that. It's about one of the nice things I
stumbled upon while reading the aforementioned Hacker News thread: Deno's
standard library is widely available even for non-Deno users. You can find it on
Deno's independent module registry, JSR</a>.</p>
When I work in JavaScript or Rust I'm always envious of Go. I may hate the
syntax and find the code lacking expressivity, but it undeniably has a rich and
simple standard library. I've often seen an ethos in Go to stick to "pure Go"
and avoid pulling in third-party implementations for items already covered by
the stdlib. It's a stacked comparison because JavaScript was never meant to be a
language running on the server (that's really a Node problem, after all), but
times have changed and JavaScript is no longer just a browser runtime.</p>
The ability to use Deno's standard library for non-Deno projects offers a nice
default for JavaScript developers. We might just be trading one dependency for
another, but I have a high degree of trust in the Deno folks to make good on
their architectural goals and offer a widely useful, yet dependency-free set of
functions.</p>
On a quick scan of Deno's @std</code> modules, there are quite a few goodies:</p>

@std/collections</code> which covers utility functions a la lodash</li>
@std/uuid</code> for UUID generation/validation</li>
@std/async</code> for quite a few commonly-implemented async handlers (debounce,
retry, exponential back-off)</li>
@std/csv</code> and @std/yaml</code> for common file formats</li>
</ul>
The retry</code> function from @std/async</code> looks especially appealing:</p>
import</span> {</span> retry</span> }</span> from</span> '@std/async/retry'</span></span>
const</span> req</span> =</span> async</span> ()</span> =></span> {</span></span>
  // some function that throws sometimes</span></span>
}</span></span>
</span>
// Below resolves to the first non-error result of `req`</span></span>
const</span> retryPromise</span> =</span> await</span> retry</span>(req</span>, {</span></span>
  multiplier</span>:</span> 2</span>,</span></span>
  maxTimeout</span>:</span> 60000</span>,</span></span>
  maxAttempts</span>:</span> 5</span>,</span></span>
  minTimeout</span>:</span> 100</span>,</span></span>
  jitter</span>:</span> 1</span>,</span></span>
}</span>)</span></span></code></pre>
Something that's definitely worth exploring for new projects. The source code
for the entirety of Deno's standard library is available here:
denoland/std</a>.</p>


August Was a Great Month for Puzzles
2025-09-04T00:00:00+00:00
I can't stop thinking about two puzzle games that came out last month. They're
both the kind of game that makes me jealous for not having designed it myself,
then jealous again for knowing that even with the idea in my hands I couldn't
execute it as well. Those two games are
Strange Jigsaws</a>
and Öoo</a>.</p>
</p>
Strange Jigsaws is a meta-puzzle exploration built on the humble jigsaw puzzle.
If you're not into jigsaws (I don't blame you, they're not particularly
puzzling</em>) don't be dissuaded. The puzzles in Strange Jigsaws encompass a wide
variety of different logic and themed puzzles, jigsaws only in the narrowest
sense.</p>
Thanks to those jigsaws, the game is incredibly tactile. FLEB clearly knows what
he's doing when he designs puzzles that emphasize juicy interactions. Moving,
rotating, and slotting puzzle pieces is dopamine delivered straight to the
brain.</p>
The real triumph of Strange Jigsaws is the breadth of ideas and overall quality
of their execution. There are a ton</em> of different puzzle ideas in the game,
almost none of which are a plain ol' jigsaw. Each puzzle is a fresh challenge
with a consistent difficulty, a bit on the easy side but only so much as to
avoid any sense of frustration.</p>
I played through Strange Jigsaws in three, one-hour sessions. It's a game that's
very amenable to short sessions since each puzzle is neatly self-contained.</p>
Öoo is likewise a short game. I finished in just under two hours, but that two
hours was a single, non-stop playthrough. Öoo is not an easy game to put down.</p>
</p>
Design-wise, Öoo is kind of the antithesis of Strange Jigsaws. Where Strange
Jigsaws delights by introducing new mechanics with every puzzle, Öoo is a study
into the possibility space of a single idea. That single idea grows deeper as
the player accumulates the knowledge of how to apply it to the surrounding
world.</p>
That means mechanics in Öoo aren't so much introduced as revealed. Every puzzle
advances the player's intuition of the mechanical language underlying Öoo,
unveiling how that language interacts with the surrounding world and how the
player can use that language to solve puzzles. The player character doesn't gain
new abilities. Instead, the player learns the world and the world reveals itself
as one great puzzle.</p>
It's hard to overstate how much design excellence Öoo squeezes out of its
mechanics. Several times a solution left me blurting out in laughter, amazed by
how Öoo bent the rules of the world and re-contextualized my expectations. It's
a uniquely joyful experience.</p>
It's hard to believe that two of the best puzzle games that I've played in the
last two years came out in the same month. Do yourself a favor and check them
out.</p>


New Emacs Package: Helix Mode
2025-05-17T00:00:00+00:00
Short version:</p>
I'm building a new Emacs package:
Helix Mode</a>. Helix Mode implements the
Helix modal keybindings</a> in Emacs.
It's been my daily driver for about a month, and while it still has some bugs,
I'm reasonably confident it's in a usable state.</p>
Install Helix Mode in Emacs 30.1:</p>
(</span>use-package</span> helix</span></span>
  :vc (:url</span> "https://github.com/mgmarlow/helix-mode"</span>)</span></span>
  :config</span></span>
  (helix-mode))</span></span></code></pre>
Long version:</p>
About six months ago I attempted to set up Emacs on a Windows machine and found
it to be an immensely frustrating experience. The default Windows Emacs build
works well enough if you don't use any third-party packages, but who is using
Emacs who isn't also using packages? Diving into the complexity of setting up my
entire Emacs config exposed a reliance on Linux CLI tools that I hadn't
installed, and attempting to configure my Windows environment to properly export
paths with cygwin/w64devkit/whatever was not going well.</p>
Eventually I gave up and swapped over to WSL, the Linux emulation layer for
Windows. For the most part WSL is great, provided you use the terminal.
Attempting to use GUI Emacs from WSL results in a Frankenstein-like windowing
experience. It kinda works but is far from ideal.</p>
With these frustrations top of mind, I decided to drop Emacs altogether and
experiment with a terminal-first workflow. I had already been itching for an
excuse to try out Helix</a> and this felt like the
perfect opportunity.</p>
As it turns out, Helix is an incredibly capable text editor, if a bit light on
the tooling. The vim-ish keybinding scheme is magical once you understand the
basics, and the automatic configuration settings for tree-sitter and LSP work
amazingly well. That said, Helix is not very featureful and expects a lot of
supplemental work done in the terminal. It really needs to be paired with a
terminal multiplexer like Zellij</a> or
tmux</a> to work effectively.</p>
I settled on tmux and set up a light config that emulates Emacs:</p>
# remap prefix from C-b to C-x</span></span>
unbind C-b</span></span>
set-option -g prefix C-x</span></span>
bind-key C-x send-prefix</span></span>
</span>
# split panes</span></span>
bind 0 kill-pane</span></span>
bind 1 kill-pane -a</span></span>
bind 2 split-window -v</span></span>
bind 3 split-window -h</span></span>
unbind '"'</span></span>
unbind %</span></span>
</span>
# zellij-style pane swapping</span></span>
bind h select-pane -L</span></span>
bind j select-pane -D</span></span>
bind k select-pane -U</span></span>
bind l select-pane -R</span></span></code></pre>
If you're willing to settle for a minimal text editor that's supplemented with
tmux and small scripting languages, I think Helix is incredibly compelling. It
remixes the Vim keybindings1</a></sup> in a way that makes them far more intuitive.</p>
The principle change is flipping around Vim's verb-object model. In Vim, if you
want to delete the next word, you first press d</code> (delete) and followup with w</code>
(word). The idea is that you declare your action before your intended target,
queuing up what you intend to perform before telling Vim what to perform it on.</p>
Helix is the opposite. First you select your intended target: w</code> (word). Helix
automatically selects the word as the cursor navigates to it, clarifying the
selection visually. Then you perform your action: d</code> (delete).</p>
It's kind of like Helix is operating in a permanent, automatic visual mode. In
Vim, I often found myself resorting to visual mode because I didn't inherently
trust my muscle memory to select the appropriate selection before performing a
deletion. This is problematic because Vim's visual mode makes everything less
efficient. Here's how you'd delete with visual mode:</p>

Press v</code> to enter visual mode.</li>
Press w</code> to navigate word.</li>
Press d</code> to delete.</li>
</ol>
The funny thing is that visual mode makes Vim function like Helix, but requires
an extra keypress for every action. In Helix, the selection is automatic so you
don't
lose any street cred</a>.</p>
Back to Emacs</h2>
Despite enjoying the Helix + tmux workflow, in the last couple months I've come
to miss some of the niceties of Emacs:</p>

Built-in diffing tools like vc-diff</code> are really nice, even if I prefer the
git CLI for most everything else.</li>
project.el</code> is unbeatable. Helix doesn't have a concept of workspaces, nor
does it allow global search & replace like project-query-replace-regexp</code>.</li>
Helix only recently got a proper file navigator but it hasn't yet been
released. I doubt that it will be as useful as dired.</li>
Emacs remains the king of Lisp editing (shoutout to the
2025 Spring Lisp Game Jam</a>
where I'm using Fennel & Love2d).</li>
</ul>
And so the idea for Helix Mode</a>
developed. It's easily my most ambitious Emacs package, both in lines of code
and functionality. But it brings all of my favorite pieces of Helix into the
Emacs editing experience.</p>
Helix Mode isn't designed to re-implement all of Helix, nor provide the
extensibility of the venerable Evil Mode. Instead it's aimed at the subset of
Helix keybindings responsible for editing and navigation, leaving everything
else to the responsibility of Emacs. That means you'll still be using stuff like
M-x replace-string</code> or consult</a>.</p>
What it does offer is the same object-verb navigation as Helix, complete with
automatic selections. It also includes some of the Helix sub-modes, like the
Goto mode that provides go-to definition (g d</code>) or the Space mode that allows
navigation across a project (SPC f</code>). Both of which integrate with project.el</code>
and xref</code>.</p>
If I haven't bored you with the details of my text-editor dabblings over the
past six months, I encourage you to check out
Helix Mode</a>. I have a long list of
features and improvements that I'd like to make before the 1.0.0 release, but I
think it's currently in a very usable state.</p>
^1</sup>Noteworthy that the object-verb idea isn't Helix's innovation, but
Kakoune's</a>.</p>
</div>


Action Cable + React
2025-05-02T00:00:00+00:00
Using Action Cable in React is surprisingly difficult. Every third-party package
that I've come across that offers a custom hook makes some fundamental
assumptions that only hold for simple applications. The vast majority of
tutorials gloss over anything beyond the "log when event is received"
boilerplate.</p>
The principle of integrating Action Cable is easy, since it follows a well-known
subscribe/unsubscribe pattern with a useEffect</code>. It looks something like
this1</a></sup>:</p>
import</span> {</span> createConsume</span> }</span> from</span> '@rails/actioncable'</span></span>
</span>
const</span> MyComponent</span> =</span> ()</span> =></span> {</span></span>
  const</span> consumer</span> =</span> useMemo</span>(</span></span>
    ()</span> =></span> createConsumer</span>(</span>'ws://localhost:3000/cable'</span>)</span>,</span></span>
    []</span>,</span></span>
  )</span></span>
</span>
  useEffect</span>(</span>()</span> =></span> {</span></span>
    const</span> sub</span> =</span> consumer</span>.</span>subscriptions</span>.</span>create</span>(</span>'AlertChannel'</span>, {</span></span>
      received</span>(</span>data</span>) {</span></span>
        console</span>.</span>log</span>(data)</span></span>
      },</span></span>
    }</span>)</span></span>
</span>
    return</span> ()</span> =></span> {</span></span>
      sub</span>.</span>unsubscribe</span>()</span></span>
    }</span></span>
  },</span> [consumer])</span></span>
</span>
  return</span> <</span>div</span> /></span></span>
}</span></span></code></pre>
When all the React application is doing is logging some data, sure, easy-peasy.
But when that component needs to access component state? Now we have a problem.</p>
Let me demonstrate by introducing a stateful counter. It's a contrived example,
but it gets the point across that accessing component state is probably useful
for Websocket subscribers.</p>
const</span> MyComponent</span> =</span> ()</span> =></span> {</span></span>
  const</span> [</span>count</span>,</span> setCount</span>]</span> =</span> useState</span>(</span>0</span>)</span></span>
</span>
  const</span> consumer</span> =</span> useMemo</span>(</span></span>
    ()</span> =></span> createConsumer</span>(</span>'ws://localhost:3000/cable'</span>)</span>,</span></span>
    []</span>,</span></span>
  )</span></span>
</span>
  useEffect</span>(</span>()</span> =></span> {</span></span>
    const</span> sub</span> =</span> consumer</span>.</span>subscriptions</span>.</span>create</span>(</span>'AlertChannel'</span>, {</span></span>
      received</span>() {</span></span>
        console</span>.</span>log</span>(count)</span></span>
      },</span></span>
    }</span>)</span></span>
</span>
    return</span> ()</span> =></span> {</span></span>
      sub</span>.</span>unsubscribe</span>()</span></span>
    }</span></span>
  },</span> [consumer])</span></span>
</span>
  return</span> (</span></span>
    <</span>div</span>></span></span>
      <</span>button</span> onClick</span>=</span>{()</span> =></span> setCount</span>(</span>(</span>c</span>)</span> =></span> c</span> +</span> 1</span>)</span>}</span>></span>increment</span></</span>button</span>></span></span>
    </</span>div</span>></span></span>
  )</span></span>
}</span></span></code></pre>
This example demonstrates the most obvious flaw: count</code> is missing in the
useEffect</code> dependencies, so no matter how many times the increment button is
clicked, the value logged will always be 0. We have to make the subscription
event handler aware that the count has changed by adding it as a dependency to
the effect.</p>
useEffect</span>(</span>()</span> =></span> {</span></span>
  const</span> sub</span> =</span> consumer</span>.</span>subscriptions</span>.</span>create</span>(</span>'AlertChannel'</span>, {</span></span>
    received</span>() {</span></span>
      console</span>.</span>log</span>(count)</span></span>
    },</span></span>
  }</span>)</span></span>
</span>
  return</span> ()</span> =></span> {</span></span>
    sub</span>.</span>unsubscribe</span>()</span></span>
  }</span></span>
},</span> [consumer</span>,</span> count])</span></span></code></pre>
Now, theoretically this resolves our counter issue. And, for the most part, it
does. When we receive an Action Cable event from our server, the received</code>
handler logs with the correct value of count</code>. However, in practice this code
has another bug: subscriptions are not properly cleaned up, so the client
responds to the Action Cable message many more times than expected. In my
testing, if I clicked the button 12 times quickly, I would see 6 console logs
when the Action Cable event is broadcast.</p>
It seems that Action Cable is not particularly good about cleaning up
subscriptions that have the same channel key. That is, when the increment button
is clicked multiple times in succession (representing many state updates in our
component), Action Cable does not do a good job ensuring that every connection
is appropriately unsubscribed between renders. You will actually observe errors
in the Rails console, indicating that it’s struggling to keep up:</p>
Could not execute command from ({"command" => "unsubscribe", "identifier" =></span></span>
"{\"channel\":\"AlertChannel\"}"}) [RuntimeError - Unable to find subscription</span></span>
with identifier: {"channel":"AlertChannel"}]</span></span></code></pre>
Digging into the Action Cable source code, it's made apparent that the Action
Cable library uses a JSON-stringified representation of the channel name as an
identifier when storing the subscriber. Here's the
relevant code</a>:</p>
export default class</span> Subscription</span> {</span></span>
  constructor</span>(</span>consumer</span>,</span> params</span> =</span> {},</span> mixin</span>) {</span></span>
    this</span>.</span>consumer</span> =</span> consumer</span></span>
    this</span>.</span>identifier</span> =</span> JSON</span>.</span>stringify</span>(params)</span></span>
    extend</span>(</span>this</span>,</span> mixin)</span></span>
  }</span></span>
  // ...</span></span></code></pre>
I can only guess that there's a race condition somewhere in Action Cable
involving identical subscription identifiers. I managed to locate a GitHub issue
that tracks a similar problem</a> and
lends a little extra support to the theory.</p>
One way to resolve this race condition is to simply include the count in the
channel identifier, even if it's unused by the channel on the server. That way a
unique identifier is created for every re-render caused by count:</p>
useEffect</span>(</span>()</span> =></span> {</span></span>
  const</span> sub</span> =</span> consumer</span>.</span>subscriptions</span>.</span>create</span>(</span></span>
    {</span> channel</span>:</span> 'AlertChannel'</span>,</span> count</span> },</span></span>
    {</span></span>
      received</span>() {</span></span>
        console</span>.</span>log</span>(count)</span></span>
      },</span></span>
    },</span></span>
  )</span></span>
</span>
  return</span> ()</span> =></span> {</span></span>
    sub</span>.</span>unsubscribe</span>()</span></span>
  }</span></span>
},</span> [consumer</span>,</span> count])</span></span></code></pre>
This seems to get the job done. Each Websocket subscriber is given a unique key
that can be easily located by the Action Cable library for removal. Note that
this only works for serializable data.</p>

I'll note that I also tried passing a reference (via useRef</code>) for the Action
Cable callbacks, hoping that a stable object reference might avoid the need
for the extra useEffect</code> dependency. However, when the Action Cable JS
library creates new subscriptions, it creates an entirely new object,
rendering the stable reference moot.</p>
</blockquote>
Anyway, all this to say: be careful when creating Action Cable subscriptions
that rely on external state. Subscriptions created with the same key will likely
not be cleaned up correctly.</p>
Most of the time in React applications this doesn't matter that much, since we
can get by with a stable, memoized reference. useQueryClient</code> from
tanstack-query is a great example, since it allows us to invalidate our client
requests when an event is broadcast from the server:</p>
// e.g. from react-query or tanstack-query</span></span>
const</span> queryClient</span> =</span> useQueryClient</span>()</span></span>
</span>
const</span> consumer</span> =</span> useMemo</span>(</span>()</span> =></span> createConsumer</span>(</span>'ws://localhost:3000/cable'</span>)</span>,</span> [])</span></span>
</span>
useEffect</span>(</span>()</span> =></span> {</span></span>
  if</span> (</span>!</span>consumer</span> || !</span>queryClient)</span> {</span></span>
    return</span></span>
  }</span></span>
</span>
  const</span> sub</span> =</span> consumer</span>.</span>subscriptions</span>.</span>create</span>(</span>'AlertChannel'</span>, {</span></span>
    received</span>() {</span></span>
      queryClient</span>.</span>invalidateQueries</span>(</span>{</span></span>
        queryKey</span>:</span> [</span>'alerts'</span>]</span>,</span></span>
      }</span>)</span></span>
    },</span></span>
  }</span>)</span></span>
</span>
  return</span> ()</span> =></span> {</span></span>
    sub</span>.</span>unsubscribe</span>()</span></span>
  }</span></span>
},</span> [consumer</span>,</span> queryClient])</span></span></code></pre>
For other purposes, it's likely a good idea to pass serializable data to the
Websocket channel parameters.</p>
^{1</sup>
Note that I'm being careful to only create one consumer for a given
component to avoid re-establishing a connection to the Websocket on every
re-render. It's also likely that your consumer will need to live in a
separate hook for authorization purposes.</p>
</div>}


Kafka on the Shore is My Favorite Murakami Novel
2025-04-22T00:00:00+00:00
The following is an email I sent a friend regarding Kafka on the Shore.</em></p>
I've had a week or two now to digest Kafka on the Shore</em> and put some thoughts
together. It's definitely my favorite Murakami novel thus far. By a long shot.
The symbolism feels attainable, yet abstract enough that there's still room for
reader interpretation. The plot is interesting enough to give weight to the
characters, aided by the dual narrative between Kafka and Nakata/Hoshino. It's
great.</p>
A couple of ideas stand out to me:</p>
The Oedipus prophecy set upon Kafka isn't necessarily that he literally needs to
fulfill the Oedipus contract, but that he needs to carry on the spirit of his
father's art. The subtext that I'm picking up is that his father (the
cat-murdering, flute-blowing madman sculptor) sacrificed everything for his art,
including his relationship with his son. The prophecy that he laid upon Kafka is
his own desire for immortality, extending his name and art with Kafka as the
vehicle. Thus Kafka feels overwhelming pressure and the impossibility of his own
individuality, thus he runs away.</p>
In Miss Saeki, Kafka finds a companion in grief. The two struggle with existing
in the real world, caught instead between the threshold of life and death where
her 15 year old spirit inhabits memories of the past. To her the past and
present are inseparable, the youth that once drove her to compose Kafka on the
Shore</em> has long since vanished.</p>
When Kafka ventures into the forest behind the cabin, he grapples with the idea
of suicide. He's literally on the precipice of death, peering into the world
beyond and the purgatory in-between. Here there's comfort in routine, at the
cost of the literal music of life. Back home there's grief and sadness, but also
the ability to form new memories shaped from the past.</p>
I'll leave you with one of my favorite quotes near the end of the book,</p>

“Every one of us is losing something precious to us,” he says after the phone
stops ringing. “Lost opportunities, lost possibilities, feelings we can never
get back again. That’s part of what it means to be alive. But inside our
heads—at least that’s where I imagine it—there’s a little room where we store
those memories. A room like the stacks in this library. And to understand the
workings of our own heart we have to keep on making new reference cards. We
have to dust things off every once in a while, let in fresh air, change the
water in the flower vases. In other words, you’ll live forever in your own
private library.”</p>
</blockquote>


How I Organize Email with HEY
2025-04-18T00:00:00+00:00
Six months after
swapping back over to HEY</a> for
email feels like the appropriate time to check in on how it’s going. Here are
the ways I use HEY to organize my email; what works and what doesn't.</p>
My workflow</h2>
I read every email that finds its way into my inbox. I hate unread emails, and I
especially hate the # unread counter that most other email platforms surface
within their tab titles. It unnerves me to an unhealthy degree.</p>
That doesn't mean that I categorize every email into a special folder or label
to get it out of my inbox. HEY doesn't even support this workflow, it lacks the
notion of folders. Instead, read emails that I don't immediately delete simply
pile up in the inbox and are
covered with an image</a>.</p>
HEY claims that their email client is "countless"1</a></sup>, in that there are no
numbers telling you how many emails are in your inbox or how far you're behind
in your organizational duties. And for the most part, that's true, except for
one glaring counter that tells you how many unscreened emails are awaiting your
approval:</p>
</p>
Not exactly "countless" but at least the screener is only relevant for emails
from unrecognized senders.</p>
Back on the topic of emails flowing into my inbox, most transactional emails
find their way into the Paper Trail automatically. Receipts of this kind are
bundled up</a> and kept out of sight, out
of mind.</p>
Other emails that I want to draw temporary importance to reside in one of the
two inbox drawers, Set Aside or Reply Later. I use Set Aside for shipping
notifications, reservations, and other emails that are only relevant for a short
period of time. Reply Later is self-evident. The system is very simple and works
the way HEY intends.</p>
My favorite HEY feature is easily
The Feed</a>, which aggregates newsletters
into a single page. In a world where Substack has convinced every blogger that
newsletters are the correct way to distribute their thoughts, The Feed is a
great platform for aggregation. Shout-out to
JavaScript Weekly</a> and
Ruby Weekly</a>.</p>
The Feed, Paper Trail, Set Aside, and Reply Later make up the bulk of my daily
workflow in HEY. I'm very happy with these tools and while they are largely
achievable via application of filters, labels, and rules in other inbox systems,
I find the experience in HEY to be an improvement thanks to its email client and
UI.</p>
A few other HEY tools fit into more niche use-cases.</p>
Collections are essentially threads of threads. They're similar to labels, but
have the added benefit of aggregating attachments to the top of the page. I tend
to use them for travel plans because they provide easy access to boarding passes
or receipts.</p>
</p>
On the topic of travel, Clips</a>
are amazing for Airbnb door codes, addresses, or other key information that
often finds itself buried in email marketing fluff. Instead of keeping the email
in the Set Aside drawer and digging into it every time you need to retrieve a
bit of information, simply highlight the relevant text and save it to a Clip.</p>
HEY for domains, while severely limited in its lack of support for multiple
custom domains, at least allows for email extensions. I use
reimburse@mydomain.com</code> to automatically tag incoming email with the
"reimburse" label so I can later retrieve it for my company's reimbursement
systems.</p>
Important missing features</h2>
HEY is missing a couple of crucial features that I replace with free
alternatives.</p>
The first is allowing multiple custom domains, a feature of Fastmail that I
dearly miss. I have a few side projects that live on separate domains and I
would prefer those projects to have email contacts matching said domain. If I
wanted to achieve this with HEY, I'd have to pay an additional $12/mo per domain
which is prohibitively expensive2</a></sup>.</p>
Instead of creating multiple HEY accounts for multiple domains, I use email
forwarding to point my other custom domains towards my single HEY account.
Forward Email</a> is one such service, which offers
free email forwarding at the cost of denoting the DNS records in plain text (you
pay extra for encryption). Another option I haven't investigated is
Cloudflare Email Routing</a>,
which may be more convenient if Cloudflare doubles as your domain registrar.</p>
It's a bummer that I can't configure email forwarding for custom domains within
HEY itself, as I can with Fastmail.</p>
The other big missing feature of HEY is
masked email</a>.</p>
Fastmail partners with 1Password to offer randomly-generated email addresses
that point to a generic @fastmail domain instead of your personal domain. This
is such a useful (and critical) feature for keeping a clean inbox, since many
newsletter sign-ups or point-of-sale devices (looking at you, Toast) that
collect your email have a tendency to spam without consent. With masked email,
you have the guarantee that if your masked email address gets out in the wild it
can be trivially destroyed with no link back to your other email addresses.</p>
Luckily, DuckDuckGo has their own masked email service and it’s totally free:
DuckDuckGo Email Protection</a>. The trade-off is a
one-time download of the DuckDuckGo browser extension that you can remove
afterwards.</p>
Both of these features make me wish that HEY was more invested in privacy and
security. They have a couple of great features that already veer in that
direction, like tracking-pixel elimination</a>
and the entire concept of the Screener, but they haven't added any new privacy
features since the platform launched.</p>
Problem areas</h2>
Generally speaking, the Screener</a>
is one of the killer features of HEY. Preventing unknown senders from dropping
email directly into your inbox is really nice. It does come with a couple of
trade-offs, however.</p>
For one, joining a mailing list means constant triage of Screener requests.
Every personal email of every participant on that mailing list must be manually
screened. HEY created the
Speakeasy code</a> as a pseudo
workaround, but it doesn't solve the mailing list issue because it requires a
special code in the subject line of an email.</p>
The second problem with the Screener is pollution of your contact list. When you
screen an email into your inbox, you add that email address to your contacts.
That means your contact list export (which you may create if you migrate email
platforms) is cluttered with truckloads of no-reply email addresses, since many
services use no-reply senders for OTP or transactional emails.</p>
When I originally migrated off of HEY to Fastmail a few years ago (before coming
back) I wrote a script that ran through my contacts archive and removed no-reply
domains with regular expressions. Instead, I wish that allowed senders were
simply stored in a location separate from my email contacts.</p>
The other pain point is around the HEY pricing structure. HEY is divided into
two products: HEY for You, which provides an @hey.com</code> email address, and HEY
for Domains, which allows a single custom domain and some extra features. The
problem is that these two products are mutually exclusive.</p>
By using HEY for Domains, I do not have access to an @hey.com</code> email address, a
HEY World blog</a>, or the ability to take personal
notes on email threads. If I wanted these features in addition to a custom
domain, I'd need to pay for both HEY products and manage two separate accounts
in my email inbox (of which I want to do neither).</p>
The split in pricing is made even worse because the extra features offered by
Hey for Domains all revolve around team accounts, e.g. multi-user companies. For
a single HEY user, the HEY for You features are more appealing.</p>
This creates an awkward pricing dynamic for a single-user HEY experience. The
product that I actually want is HEY for You with a single custom domain that
maps both emails to a single account. The @hey.com</code> email address should be a
freebie for HEY for Domain users, as it is with alternative email providers.</p>
I still like it though</h2>
Since the last two sections have been dwelling a bit on the negatives, I'll end
by saying that I still think HEY is a good product. Not every feature is going
to resonate with every individual (there's a good amount of fluff), but the
features that do resonate makes HEY feel like personally-crafted software.</p>
^1</sup>HEY talks about their general philosophy
here</a>.</p>
</div>
^{2</sup>
It's worth noting that the HEY for Domains pricing scheme is intended for
multiple users. HEY for Domains used to be branded as "HEY for Work", if
that's any indication of where the pricing awkwardness comes from.</p>
</div>}


Visualizing Bracket City Puzzles
2025-04-11T00:00:00+00:00
Lately I've been addicted to a new daily word puzzle game called
Bracket City</a>. It's unique
among competitors because the game isn't about rearranging letters baked in
hidden information, but rather solving hand-written, crossword-style clues.</p>
I recommend giving the daily puzzle a shot before reading the rest of this
article since it will help with visualizing the puzzle format. But as a quick
rules summary:</p>

A Bracket City solution is a short phrase</li>
Certain words are substituted with clues, indicated via a pair of square
brackets</li>
Clues can nest other clues</li>
You must solve the inner-most clues before you can solve the outer-most</li>
</ul>
Since Bracket City is basically a recursive crossword, the structure of a puzzle
is easily mapped to a tree. And so, in classic programmer-brain fashion, I built
a little app that turns a Bracket City puzzle into an interactive tree.</p>
How it works</h2>
I had a couple of realizations while working on this little project.</p>
The first was recognizing how brilliant the Bracket City puzzle structure is.
Not only does it spin the age-old crossword in a compelling way that feels
fresh, but the actual mechanics for constructing a Bracket City puzzle are super
simple. It's a win in all categories, excellence in design.1</a></sup></p>
The second realization was how easy it is to parse Bracket City puzzles into
trees and render them via Svelte components. I haven't done much work with
Svelte, but the ability to recursively render a component by simply
self-referencing that component is incredibly expressive.</p>
If you're unfamiliar with Svelte, don't worry! There's really not that much
special Svelte stuff going on in my solution. Most of it is plain old
JavaScript.</p>
First thing's first: a class for nodes in our tree:</p>
class</span> Node</span> {</span></span>
  constructor</span>(</span>text</span> =</span> ''</span>,</span> children</span> =</span> []</span>) {</span></span>
    this</span>.</span>text</span> =</span> text</span></span>
    this</span>.</span>children</span> =</span> children</span></span>
  }</span></span>
}</span></span></code></pre>
Next, the parsing algorithm.</p>
The basic strategy has a function read through the input string one character at
a time. When a "[" is encountered, a new node is created. A couple variables
track our position in the resulting tree:</p>

currentNode</code> points to the most recent node</li>
stack</code> holds a list of nodes in order</li>
</ul>
With currentNode</code>, we can easily append new child nodes to our position in the
tree. With stack</code>, we can exit the currentNode</code> and navigate upwards in the
tree to the node's parent.</p>
Here's the algorithm in full:</p>
const</span> parsePuzzle</span> =</span> (</span>raw</span>)</span> =></span> {</span></span>
  // Initial output takes the form of a single node.</span></span>
  const</span> root</span> =</span> new</span> Node</span>()</span></span>
  let</span> currentNode</span> =</span> root</span></span>
  let</span> stack</span> =</span> [root]</span></span>
</span>
  for</span> (</span>let</span> i</span> =</span> 0</span>;</span> i</span> <</span> raw</span>.</span>length</span>;</span> i</span>++</span>)</span> {</span></span>
    const</span> char</span> =</span> raw[i]</span></span>
</span>
    if</span> (char</span> ===</span> '['</span>)</span> {</span></span>
      // Substitutions are marked with ??.</span></span>
      currentNode</span>.</span>text</span> +=</span> '??'</span></span>
      const</span> node</span> =</span> new</span> Node</span>()</span></span>
      currentNode</span>.</span>children</span>.</span>push</span>(node)</span></span>
      stack</span>.</span>push</span>(node)</span></span>
      // Update our currentNode context so that future nodes</span></span>
      // are appended to the most recent one.</span></span>
      currentNode</span> =</span> node</span></span>
    }</span> else if</span> (char</span> ===</span> ']'</span>)</span> {</span></span>
      if</span> (stack</span>.</span>length</span> ></span> 1</span>)</span> {</span></span>
        // Closing brace encountered, so we can bump the</span></span>
        // currentNode context up the tree by a single node.</span></span>
        stack</span>.</span>pop</span>()</span></span>
        currentNode</span> =</span> stack[stack</span>.</span>length</span> -</span> 1</span>]</span></span>
      }</span></span>
    }</span> else</span> {</span></span>
      currentNode</span>.</span>text</span> +=</span> char</span></span>
    }</span></span>
  }</span></span>
</span>
  // If we have any elements left over, there's a missing closing</span></span>
  // brace in the input.</span></span>
  if</span> (stack</span>.</span>length</span> ></span> 1</span>)</span> {</span></span>
    return</span> [</span>false</span>,</span> root]</span></span>
  }</span></span>
</span>
  return</span> [</span>true</span>,</span> root]</span></span>
}</span></span></code></pre>
The return result of the function denotes whether or not it was successful
followed by the resulting tree, a simple form of error handling.</p>
In Svelte, we can tie this algorithm together with an HTML textarea in a
component like so:</p>
<</span>script</span>></span></span>
  import</span> parsePuzzle</span> from</span> '$lib/parsePuzzle.js'</span></span>
</span>
  let</span> puzzle</span> =</span> $state</span>(</span>''</span>)</span></span>
  let</span> [</span>_</span>,</span> tree</span>]</span> =</span> $derived</span>(</span>parsePuzzle</span>(puzzle))</span></span>
  $inspect</span>(tree)</span></span>
<</span>/</span>script</span>></span></span>
</span>
<</span>textarea</span> bind:value</span>=</span>"{puzzle}"</span>></</span>textarea</span>></span></span></code></pre>
And using the tutorial puzzle as an example,</p>
# raw input:</span></span>
[where [opposite of clean] dishes pile up] or [exercise in a [game played with a cue ball]]</span></span>
</span>
# tree:</span></span>
Node(</span></span>
  "?? or ??",</span></span>
  [</span></span>
    Node(</span></span>
      "where ?? dishes pile up",</span></span>
      [</span></span>
        Node("opposite of clean", [])</span></span>
      ]</span></span>
    ),</span></span>
    Node(</span></span>
      "exercise in a ??",</span></span>
      [</span></span>
        Node("game played with a cue ball", [])</span></span>
      ]</span></span>
    )</span></span>
  ]</span></span>
)</span></span></code></pre>
As the textarea is updated, $inspect</code> logs the resulting tree. We haven't yet
rendered the tree in the actual UI. Let's change that.</p>
First, update the original component to include a new component named Tree</code>:</p>
<</span>script</span>></span></span>
  import</span> parsePuzzle</span> from</span> '$lib/parsePuzzle.js'</span></span>
  import</span> Tree</span> from</span> '$lib/components/Tree.svelte'</span></span>
</span>
  let</span> puzzle</span> =</span> $state</span>(</span>''</span>)</span></span>
  let</span> [</span>success</span>,</span> tree</span>]</span> =</span> $derived</span>(</span>parsePuzzle</span>(puzzle))</span></span>
<</span>/</span>script</span>></span></span>
</span>
<</span>textarea</span> bind:value</span>=</span>"{puzzle}"</span>></</span>textarea</span>></span></span>
</span>
{#if success}</span></span>
<</span>Tree</span> nodes</span>=</span>"{[tree]}"</span> /></span></span>
{:else}</span></span>
<</span>p</span>></span>Error: brackets are unbalanced</span></</span>p</span>></span></span>
{/if}</span></span></code></pre>
Creating a new component to handle rendering the puzzle tree is not just to tidy
up the code, it's to enable a bit of fancy self-referential Svelte behavior.
Intro CS courses have taught us that tree structures map nicely to recursive
algorithms and it's no different when we think about UI components in Svelte.
Svelte allows components to import themselves as a form of recursive rendering.</p>
Here's the Tree</code> component in full:</p>
<</span>script</span>></span></span>
  import</span> Self</span> from</span> './Tree.svelte'</span></span>
</span>
  const</span> {</span> nodes</span> }</span> =</span> $props</span>()</span></span>
<</span>/</span>script</span>></span></span>
</span>
{#each nodes as node}</span></span>
<</span>div</span>></span></span>
  <</span>div</span>></span>{node.text}</span></</span>div</span>></span></span>
</span>
  <</span>div</span> class</span>=</span>"ml-4"</span>></span></span>
    {#if node.children.length > 0}</span></span>
    <</span>Self</span> nodes</span>=</span>"{node.children}"</span> /></span></span>
    {/if}</span></span>
  </</span>div</span>></span></span>
</</span>div</span>></span></span>
{/each}</span></span></code></pre>
How about that? A Svelte component can render itself by simply importing itself
as a regular old Svelte file. In the template content of the component, we
simply map over our list of nodes and render their text content. If a given node
has children, we use a Self</code> reference to repeat the same process from the
viewpoint of the children.</p>
ml-4</code> applies left-margin to each of the children nodes, enabling stair-like
nesting throughout the tree. We never need to increment the margin in subsequent
child nodes because the document box model handles the hard work for us. Each
margin is relative to its container, which itself uses the same margin
indentation.</p>
That about wraps it up! I added a couple extra features to the final version,
namely the ability to show/hide individual nodes in the tree. I'll leave that as
an exercise for the reader.</p>
^{1</sup>
Well, there is one</em> thing that is maybe questionable about the design of
Bracket City. The layout of the puzzle makes you really want to solve the
outer-most clue before the inner-most, if you know the answer. However the
puzzle forces you to solve the inner-most clues first. This is a
surprisingly controversial design choice!</p>
</div>}


Onboarding a new Mac
2025-04-05T00:00:00+00:00
My process for onboarding a new Mac:</p>

Remove all of the apps from the default dock. Move the dock to the righthand
side and set to minimize automatically.</li>
Rebind Caps Lock as Control via Settings->Keyboard->Modifier Keys.</li>
Install the usual software:

Firefox Developer Edition</a></li>
Alacritty</a> (terminal emulator)</li>
Rectangle</a> (windowing solution)</li>
Hack</a> (monospace font of choice)</li>
1Password</a></li>
Homebrew</a></li>
</ul>
</li>
Install git by opening Alacritty, attempting to call git</code>, and accepting the
xcode-select</code> tool installation.</li>
Install must-have brew formulae:

brew install helix tmux ripgrep npm rbenv</code></li>
</ul>
</li>
Configure a Github SSH key</a></li>
Bring over dotfiles</a> for Alacritty,
Helix, tmux, git, etc. I don't have a good workflow for this yet but I'm
investigating GNU Stow</a>.</li>
</ol>
I probably forgot a thing or two, but this list accounts for some 90% of the
tools I use in the day-to-day.</p>


Ruby and RSS feeds
2025-03-30T00:00:00+00:00
I've been digging into Ruby's stdlib RSS parser for a side project and am very
impressed by the overall experience. Here's how easy it is to get started:</p>
require</span> "open-uri"</span></span>
require</span> "rss"</span></span>
</span>
feed</span> =</span> URI</span>.</span>open</span>(</span>"https://jvns.ca/atom.xml"</span>)</span> do</span> |</span>raw</span>|</span></span>
  RSS</span>::</span>Parser</span>.</span>parse</span>(</span>raw</span>)</span></span>
end</span></span></code></pre>
That said, doing something interesting with the resulting feed is not quite so
simple.</p>
For one, you can't just support RSS. Atom is a more recent standard used by many
blogs (although I think irrelevant in the world of podcasts). There's about a
50% split in the use of RSS and Atom in the tiny list of feeds that I follow, so
a feed reader must handle both formats.</p>
Adding Atom support introduces an extra branch to our snippet:</p>
URI</span>.</span>open</span>(</span>"https://jvns.ca/atom.xml"</span>)</span> do</span> |</span>raw</span>|</span></span>
  feed</span> =</span> RSS</span>::</span>Parser</span>.</span>parse</span>(</span>raw</span>)</span></span>
</span>
  title</span> =</span> case</span> feed</span></span>
  when</span> RSS</span>::</span>Rss</span></span>
    feed</span>.</span>channel</span>.</span>title</span></span>
  when</span> RSS</span>::</span>Atom</span>::</span>Feed</span></span>
    feed</span>.</span>title</span>.</span>content</span></span>
  end</span></span>
end</span></span></code></pre>
The need to handle both standards independently is kind of frustrating.</p>
That said, it does make sense from a library perspective. The RSS gem is
principally concerned with parsing XML per the RSS and Atom standards, returning
objects that correspond one-to-one. Any conveniences for general feed reading
are left to the application.</p>
Wrapping the RSS gem in another class helps encapsulate differences in
standards:</p>
class</span> FeedReader</span></span>
  attr_reader</span> :</span>title</span></span>
</span>
  def</span> initialize</span>(</span>url</span>)</span></span>
    @url</span> =</span> url</span></span>
  end</span></span>
</span>
  def</span> fetch</span></span>
    feed</span> =</span> URI</span>.</span>open</span>(</span>@url</span>) { |</span>r</span>|</span> RSS</span>::</span>Parser</span>.</span>parse</span>(</span>r</span>) }</span></span>
</span>
    case</span> feed</span></span>
    when</span> RSS</span>::</span>Rss</span></span>
      @title</span> =</span> feed</span>.</span>channel</span>.</span>title</span></span>
    when</span> RSS</span>::</span>Atom</span>::</span>Feed</span></span>
      @title</span> =</span> feed</span>.</span>title</span>.</span>content</span></span>
    end</span></span>
  end</span></span>
end</span></span></code></pre>
Worse than dealing with competing standards is the fact that not everyone
publishes the content of an article as part of their feed. Many bloggers only
use RSS as a link aggregator that points subscribers to their webpage, omitting
the content entirely:</p>
<</span>rss</span> version</span>=</span>"2.0"</span>></span></span>
  <</span>channel</span>></span></span>
    <</span>title</span>></span>Redacted Blog</span></</span>title</span>></span></span>
    <</span>link</span>></span>https://www.redacted.io</span></</span>link</span>></span></span>
    <</span>description</span>></span>This is my blog</span></</span>description</span>></span></span>
    <</span>item</span>></span></span>
      <</span>title</span>></span>Article title goes here</span></</span>title</span>></span></span>
      <</span>link</span>></span>https://www.redacted.io/this-is-my-blog</span></</span>link</span>></span></span>
      <</span>pubDate</span>></span>Thu, 25 Jul 2024 00:00:00 GMT</span></</span>pubDate</span>></span></span>
      <!-- No content! --></span></span>
    </</span>item</span>></span></span>
  </</span>channel</span>></span></span>
</</span>rss</span>></span></span></code></pre>
How do RSS readers handle this situation? The solution varies based on the app.</p>
The two I've tested, NetNewsWire and Readwise Reader, manage to include the
entire article content in the app, despite the RSS feed omitting it (assuming no
paywalls). My guess is these services make an HTTP request to the source,
scraping the resulting HTML for the article content and ignoring everything
else.</p>
Firefox users are likely familiar with a feature called
Reader View</a>
that transforms a webpage into its bare-minimum content. All of the layout
elements are removed in favor of highlighting the text of the page. The JS
library that Firefox uses is open source on their Github:
mozilla/readability</a>.</p>
On the Ruby side of things there's a handy port called
ruby-readability</a> that we can use
to extract omitted article content directly from the associated website:</p>
require</span> "ruby-readability"</span></span>
</span>
URI</span>.</span>open</span>(</span>"https://jvns.ca/atom.xml"</span>)</span> do</span> |</span>raw</span>|</span></span>
  feed</span> =</span> RSS</span>::</span>Parser</span>.</span>parse</span>(</span>raw</span>)</span></span>
</span>
  url</span> =</span> case</span> feed</span></span>
  when</span> RSS</span>::</span>Rss</span></span>
    feed</span>.</span>items</span>.</span>first</span>.</span>link</span></span>
  when</span> RSS</span>::</span>Atom</span>::</span>Feed</span></span>
    feed</span>.</span>entries</span>.</span>first</span>.</span>link</span>.</span>href</span></span>
  end</span></span>
</span>
  # Raw HTML content</span></span>
  source</span> =</span> URI</span>.</span>parse</span>(</span>url</span>).</span>read</span></span>
  # Just the article HTML content</span></span>
  article_content</span> =</span> Readability</span>::</span>Document</span>.</span>new</span>(</span>source</span>).</span>content</span></span>
end</span></span></code></pre>
So far the results are good, but I haven't tested it on many blogs.</p>


Reminiscing on Flow
2025-03-01T00:00:00+00:00
(The type-checker</a>, not the state of deep work)</em></p>
React's recent
sunsetting of Create React App</a>
has me feeling nostalgic.</p>
My first experience with a production web application was a React ecommerce site
built with Create React App. I came into the team with zero React experience,
hot off of some Angular 2 work and eager to dive into a less-opinionated
framework. The year was 2018 and the team (on the frontend, just two of us) was
handed the keys to a brand new project that we could scaffold using whatever
tools we thought best fit the job.</p>
We knew we wanted to build something with React, but debated two alternative
starting templates:</p>


Create React App (then, newly released) with Flow</p>
</li>

One of the many community-maintained templates with TypeScript</p>
</li>
</ol>
You might be surprised that Create React App didn't originally come bundled with
TypeScript1</a></sup>, but the ecosystem was at a very different place back in 2018.
Instead, the default type-checker for React applications was Flow, Facebook's
own type-checking framework.</p>
After a couple prototypes, we chose Flow. It felt like a safer bet, since it was
built by the same company as the JavaScript framework that powered our app. Flow
also handled some React-isms more gracefully than TypeScript, particularly
higher-order components where integrations with third-party libraries (e.g.
React Router, Redux) led to very complicated scenarios with generics.</p>
Of all of our stack choices at the start of this project in 2018, choosing Flow
is the one that aged the worst. Today, TypeScript is so ubiquitous that removing
it from your open source project
incites a community outrage</a>2</a></sup>.
Why is TypeScript widely accepted as the de facto way to write JavaScript apps,
whereas Flow never took off?</p>
</p>
I chalk it up to a few different reasons:</p>


TypeScript being a superset of JavaScript allowed early adopters to take
advantage of JavaScript class features (and advanced proposals, like
decorators). In a pre-hooks era, both Angular and React required class syntax
for components and the community seemed to widely support using TypeScript as
a language superset as opposed to just a type-checker.</p>
</li>

Full adoption by Angular 2 led to lots of community-driven support for
TypeScript types accompanying major libraries via DefinitelyTyped. Meanwhile
nobody really used Flow outside of React.</p>
</li>

Flow alienated users by shipping broad, wide-sweeping breaking changes on a
regular cadence. Maintaining a Flow application felt like being subject to
Facebook's whims. Whatever large refactor project was going on at Facebook at
the time felt like it directly impacted your app.</p>
</li>

VSCode has become the standard text editor for new developers and it ships
with built-in support for TypeScript.</p>
</li>
</ul>
TypeScript as a language superset</h2>
Philosophically, in 2018 the goals of Flow and TypeScript were quite different.
TypeScript wasn't afraid to impose a runtime cost on your application to achieve
certain features, like enums and decorators. These features required that your
build pipeline either used the TypeScript compiler (which was, and is,
incredibly slow) or clobbered together a heaping handful of Babel plugins.</p>
On the other hand, Flow promised to be just JavaScript with types</em>, never
making its way into your actual production JavaScript bundle. Since Flow wasn't
a superset of JavaScript, it was simple to set up with existing build pipelines.
Just strip the types from the code and you're good to go.</p>
Back when JavaScript frameworks were class-based (riding on the hype from
ES2015), I think developers were more receptive towards bundling in additional
language features as part of the normal build pipeline. It was not uncommon to
have a handful of polyfills and experimental language features in every large
JavaScript project. TypeScript embraced this methodology, simplifying the
bundling process by offering support in the TypeScript compiler proper.</p>
Nowadays the stance between the two tools has reversed. The adoption of
alternative bundlers that cannot use the TypeScript compiler (esbuild, SWC, and
so on) has meant that JavaScript developers are much less likely to make use of
TypeScript-specific features. People generally seem less receptive towards
TypeScript-specific features (e.g. enums) if they're easily replaced by a
zero-cost alternative (union types). Meanwhile, recent Flow releases added
support for enums</a> and
React-specific component syntax</a>3</a></sup>.
What a reversal!</p>
Community library support</h2>
As TypeScript gathered mindshare among JavaScript developers,
DefinitelyTyped</a> crushed
FlowTyped</a> in terms of open source
contribution. By the tail end of 2021, our small team had to maintain quite a
few of our own forks of FlowTyped files for many common React libraries
(including React Router and Redux)4</a></sup>. Flow definitely felt like an
afterthought for open source library developers.</p>
As TypeScript standardized with npm under the @types</code> namespace, FlowTyped
still required a separate CLI. It's not easy to compete when the alternative
makes installing types as easy as npm install @types/my-package</code>.</p>
Breaking things</h2>
I remember distinctly that upgrading Flow to new releases was such a drag. Not
only that, but it was a regular occurrence. New Flow releases brought
wide-sweeping changes, often with new syntax and many deprecations. This problem
was so well-known in the community that Flow actually released a blog post on
the subject in 2019:
Upgrading Flow Codebases</a>.</p>
For the most part, I don't mind if improvements to Flow means new violations in
my existing codebase pointing to legitimate issues. What I do mind is that many
of these problematic Flow releases felt more like Flow rearchitecting itself
around fundamental issues that propagated down to users as new syntax
requirements. It did not often feel like the cost to upgrade matched the benefit
to my codebase.</p>
A couple examples that I still remember nearly 6 years later:</p>

Asking for required annotations</a></li>
Types-First: A Scalable New Architecture for Flow</a></li>
</ul>
LSP, tooling, and the rise of VSCode</h2>
In the early days, the Flow language server was on par with TypeScript's. Both
tools were newly emerging and often ran into issues that required restarting the
language server to re-index your codebase.</p>
VSCode was not as ubiquitous in those days as it is today, though it was
definitely an emerging star. Facebook was actually working on its own IDE at the
time, built on top of Atom. Nuclide</a> promised deep
integration with Flow and React, and gathered a ton of excitement from our team.
Too bad it was
retired in December of 2018</a>.</p>
As time went on and adoption of VSCode skyrocketed, Flow support lagged behind.
The TypeScript language server made huge improvements in consistency and
stability and was pre-installed in every VSCode installation. Meanwhile Flow
crashed with any dependency change, and
installing the Flow extension</a>
involves digging into your built-in VSCode settings and disabling
JavaScript/TypeScript language support.</p>
Towards TypeScript</h2>
As our Flow application grew from 3-month unicorn to 3-year grizzled veteran,
Flow really started to wear developers on our team down. It was a constant
onboarding pain as developers struggled to set up VSCode and cope with some of
the Flow language server idiosyncrasies. Refactoring to TypeScript was an
inevitable conversation repeated with every new hire.</p>
The point of this blog post is not to bag on Flow. I still have a ton of respect
for the project and its original goal of simplicity: "JavaScript with types".
Although that goals lives on via JSDoc</a>, Flow
is an important milestone to remember as type annotations are
formally discussed by TC39</a>.</p>
Before leaving the company, I remember tasking out a large project detailing the
entire process of converting our Flow codebase to TypeScript. I wonder if it was
ever finished.</p>
^{1</sup>
TypeScript support was added in 2019 with the v2 release.</p>
</div>}^2</sup>For another example, see Svelte's move from
TypeScript to JSDoc</a>.</p>
</div>
^3</sup>The move away from "JavaScript with types" is documented in this blog post:
Clarity on Flow’s Direction and Open Source Engagement</a>.</p>
</div>
^4</sup>If you've never looked at one of the type files for some of your favorite
libraries, they can be
rather cryptic</a>.</p>
</div>


Zod refinements are complicated
2025-02-26T00:00:00+00:00
Today I found myself at the bottom of a rabbit hole, exploring how
Zod's</a> refine method interacts with form validations. As with
most things in programming, reality is never as clear-cut as the types make it
out to be.</p>
Today's issue concerns
zod/issues/479</a>, where refine
validations aren't executed until all fields in the associated object are
present. Here's a reframing of the problem:</p>
The setup:</p>

I have a form with fields A and B. Both are required fields, say required_a</code>
and required_b</code>.</li>
I have a validation that depends on the values of both A and B, say
complex_a_b</code>.</li>
</ul>
The problem:</p>
If one of A or B is not filled out, the form parses with errors: [required_a]</code>,
not [required_a, complex_a_b]</code>. In other words, complex_a_b</code> only pops up as
an error when both A and B are filled out.</p>
Here's an example schema that demonstrates the problem:</p>
const</span> schema</span> =</span> z</span></span>
  .</span>object</span>(</span>{</span></span>
    a</span>:</span> z</span>.</span>string</span>()</span>,</span></span>
    b</span>:</span> z</span>.</span>string</span>()</span>,</span></span>
  }</span>)</span></span>
  .</span>refine</span>(</span>(</span>values</span>)</span> => !</span>complexValidation</span>(values</span>.</span>a</span>,</span> values</span>.</span>b)</span>, {</span></span>
    message</span>:</span> 'complex_a_b error'</span>,</span></span>
  }</span>)</span></span></code></pre>
This creates an experience where a user fills in A, submits, sees a validation
error pointing at B, fills in B, and sees another validation error pointing at
complex_a_b</code>. The user has to play whack-a-mole with the form inputs to make
sure all of the fields pass validation.</p>
As a programmer, we're well-acquainted with error messages that work like this.
And we hate them! Imagine a compiler that suppresses certain errors before
prerequisite ones are fixed.</p>
If you dig deep into the aforementioned issue thread, you'll come across the
following solution (credit to
jedwards1211</a>):</p>
const</span> base</span> =</span> z</span>.</span>object</span>(</span>{</span></span>
  a</span>:</span> z</span>.</span>string</span>()</span>,</span></span>
  b</span>:</span> z</span>.</span>string</span>()</span>,</span></span>
}</span>)</span></span>
</span>
const</span> schema</span> =</span> z</span>.</span>preprocess</span>(</span>(</span>input</span>,</span> ctx</span>)</span> =></span> {</span></span>
  const</span> parsed</span> =</span> base</span>.</span>pick</span>(</span>{</span> a</span>:</span> true</span>,</span> b</span>:</span> true</span> }</span>)</span>.</span>safeParse</span>(input)</span></span>
  if</span> (parsed</span>.</span>success)</span> {</span></span>
    const</span> {</span> a</span>,</span> b</span> }</span> =</span> parsed</span>.</span>data</span></span>
    if</span> (</span>complexValidation</span>(a</span>,</span> b))</span> {</span></span>
      ctx</span>.</span>addIssue</span>(</span>{</span></span>
        code</span>:</span> z</span>.</span>ZodIssueCode</span>.</span>custom</span>,</span></span>
        path</span>:</span> [</span>'a'</span>]</span>,</span></span>
        message</span>:</span> 'complex_a_b error'</span>,</span></span>
      }</span>)</span></span>
    }</span></span>
  }</span></span>
  return</span> input</span></span>
},</span> base)</span></span></code></pre>
Look at all of that extra logic! Tragic.</p>
From a type perspective, I understand why Zod doesn't endeavor to fix this
particular issue. How can we assert the types of A or B when running the
complex_a_b</code> validation, if types A or B are implicitly optional? To evaluate
them optionally in complex_a_b</code> would defeat the type, z.string()</code>, that
asserts that the field is required.</p>
How did I fix it for my app? I didn't. I instead turned to the form library,
applying my special validation via the form API instead of the Zod API. I
concede defeat.</p>


Modularizing Start Emacs
2025-02-24T00:00:00+00:00
Some folks don't want their entire Emacs configuration to live in a single,
thousand-line file. Instead, they break their config into separate modules that
each describe a small slice of functionality. Here's how you can achieve this
with Start Emacs</a>.</p>
Step one: load your custom lisp directory</h2>
Emacs searches for Emacs Lisp code in the
Emacs load path</a>.
By default, Emacs only looks in two places:</p>

/path/to/emacs/<version>/lisp/</code>, which contains the standard modules that
ship with Emacs</li>
~/.emacs.d/elpa/</code>, which contains packages installed via package-install</code></li>
</ul>
Neither of these places are suitable for your custom lisp code.</p>
I prefer to have my custom lisp code live within ~/.emacs.d/</code>, since I version
control my entire Emacs configuration as a single repository. Start Emacs adds
~/.emacs.d/lisp/</code> to the load path with this line in init.el</code> (the
Init File</a>):</p>
(</span>add-to-list</span> '</span>load-path</span> (</span>expand-file-name</span> "lisp"</span> user-emacs-directory</span>))</span></span></code></pre>
Where user-emacs-directory</code> points to ~/.emacs.d/</code>, or wherever it may live on
your machine.</p>
The rest of this guide assumes your load path accepts ~/.emacs.d/lisp/</code>, but
feel free to swap out this path for your preferred location.</p>
Step two: write your module</h2>
Next we'll create a module file that adds
evil-mode</a> with a few configurations and
extensions.</p>
Create the file evil-module.el</code> in your ~/.emacs.d/lisp/</code> directory. Open it
up in Emacs and use M-x auto-insert</code> to fill a bunch of boilerplate Emacs Lisp
content. You can either quickly RET</code> through the prompts or fill them out.
Note: to end the "Keywords" prompt you need to use M-RET</code> instead to signal the
end of a multiple-selection.</p>
Your evil-module.el</code> file should now look something like this:</p>
;;; evil-module.el ---      </span>-*-</span> lexical-binding</span>:</span> t</span>; -*-</span></span>
</span>
;; Copyright (C) 2025</span></span>
</span>
;; Author:</span></span>
;; Keywords:</span></span>
</span>
;; This program is free software; you can redistribute it and/or modify</span></span>
;; it under the terms of the GNU General Public License as published by</span></span>
;; the Free Software Foundation, either version 3 of the License, or</span></span>
;; (at your option) any later version.</span></span>
</span>
;; This program is distributed in the hope that it will be useful,</span></span>
;; but WITHOUT ANY WARRANTY; without even the implied warranty of</span></span>
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the</span></span>
;; GNU General Public License for more details.</span></span>
</span>
;; You should have received a copy of the GNU General Public License</span></span>
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.</span></span>
</span>
;;; Commentary:</span></span>
</span>
;;</span></span>
</span>
;;; Code:</span></span>
</span>
(</span>provide</span> '</span>evil-module</span>)</span></span>
;;; evil-module.el ends here</span></span></code></pre>
Most of these comments aren't relevant for your custom lisp module but they're
good to have in case you ever want to share your code as an Emacs Lisp package.
The single line of Emacs Lisp code, (provide 'evil-module)</code>, is the most
important part of the template. It denotes 'evil-module</code> as a
named feature</a>,
allowing us to import it into our Init File.</p>
Since we're building an evil-mode module, I'll add my preferred Evil defaults to
the file:</p>
;;; Commentary:</span></span>
</span>
;; Extensions for evil-mode</span></span>
</span>
;;; Code:</span></span>
</span>
(</span>use-package</span> evil</span></span>
  :</span>ensure t</span></span>
  :</span>init</span></span>
  (</span>setq evil-want-integration t</span>)</span></span>
  (</span>setq evil-want-keybinding </span>nil</span>)</span></span>
  :</span>config</span></span>
  (</span>evil-mode</span>))</span></span>
</span>
(</span>use-package</span> evil-collection</span></span>
  :</span>ensure t</span></span>
  :</span>after evil</span></span>
  :</span>config</span></span>
  (</span>evil-collection-init</span>))</span></span>
</span>
(</span>use-package</span> evil-escape</span></span>
  :</span>ensure t</span></span>
  :</span>after evil</span></span>
  :</span>config</span></span>
  (</span>setq evil-escape-key-sequence </span>"jj"</span>)</span></span>
  (</span>setq evil-escape-delay </span>0.2</span>)</span></span>
  ;; Prevent "jj" from escaping any mode other than insert-mode.</span></span>
  (</span>setq evil-escape-inhibit-functions</span></span>
        (</span>list</span> (</span>lambda</span> () (</span>not</span> (</span>evil-insert-state-p</span>)))))</span></span>
  (</span>evil-escape-mode</span>))</span></span>
</span>
(</span>provide</span> '</span>evil-module</span>)</span></span>
;;; evil-module.el ends here</span></span></code></pre>Step three: require your module</h2>
Back in our Init File, we need to signal for Emacs to load our new module
automatically. After the spot where we amended the Emacs load path, go ahead and
require 'evil-module</code>:</p>
;; init.el</span></span>
;; ...</span></span>
(</span>add-to-list</span> '</span>load-path</span> (</span>expand-file-name</span> "lisp"</span> user-emacs-directory</span>))</span></span>
</span>
(</span>require</span> '</span>evil-module</span>)</span></span></code></pre>
Reboot Emacs and your module is ready to go!</p>


Async IO in Emacs
2025-02-16T00:00:00+00:00
Stumbled on the emacs-aio</a> library today
and it's introduction post</a>. What a
great exploration into how async/await works under the hood! I'm not sure I
totally grok the details, but I'm excited to dive more into Emacs generators and
different concurrent programming techniques.</p>
The article brings to mind Wiegley's
async</a> library, which is probably the
more canonical library for handling async in Emacs. From a brief look at the
README, async</code> looks like it actually spawns independent processes, whereas
emacs-aio</code> is really just a construct for handling non-blocking I/O more
conveniently.</p>
Karthink on reddit</a>
comments on the usability of generators in Emacs:</p>

I've written small-medium sized packages -- 400 to 2400 lines of elisp -- that
use generators and emacs-aio (async/await library built on generator.el) for
their async capabilities. I've regretted it each time: generators in their
current form in elisp are obfuscated, opaque and not introspectable -- you
can't debug/edebug generator calls. Backtraces are impossible to read because
of the continuation-passing macro code. Their memory overhead is large
compared to using simple callbacks. I'm not sure about the CPU overhead.</p>
</blockquote>
That said, the simplicity of emacs-aio</code> promises is very appealing:</p>
(</span>defun</span> aio-promise</span> ()</span></span>
  "Create a new promise object."</span></span>
  (</span>record</span> '</span>aio-promise</span> nil</span> ()))</span></span>
</span>
(</span>defsubst</span> aio-promise-p</span> (</span>object</span>)</span></span>
  (</span>and</span> (</span>eq</span> '</span>aio-promise</span> (</span>type-of</span> object</span>))</span></span>
       (</span>=</span> 3</span> (</span>length</span> object</span>))))</span></span>
</span>
(</span>defsubst</span> aio-result</span> (</span>promise</span>)</span></span>
  (</span>aref</span> promise </span>1</span>))</span></span></code></pre>


Pulling Puzzles from Lichess
2025-02-03T00:00:00+00:00
Lichess</a> is an awesome website, made even more awesome by
the fact that it is free and open source. Perhaps lesser known is that the
entire Lichess puzzle database is available for free download under the Creative
Commons CC0 license. Every puzzle that you normally find under
lichess.org/training</a> is available for your
perusal.</p>
This is a quick guide for pulling that CSV and seeding a SQLite database so you
can do something cool with it. You will need
zstd</a>.</p>
First, wget</code> the file from
Lichess.org open database</a> and save it
into a temporary directory. Run zstd</code> to uncompress it into a CSV that we can
read via Ruby.</p>
wget</span> https://database.lichess.org/lichess_db_puzzle.csv.zst -P tmp/</span></span>
zstd</span> -d tmp/lichess_db_puzzle.csv.zst</span></span></code></pre>
CSV pulled down and uncompressed, it's time to read it into the application. I'm
using Ruby on Rails, so I generate a database model like so:</p>
bin/rails g model Puzzle \</span></span>
  puzzle_id:string fen:string moves:string rating:integer \</span></span>
  rating_deviation:integer popularity:integer nb_plays:integer \</span></span>
  themes:string game_url:string opening_tags:string</span></span></code></pre>
Which creates the following migration:</p>
class</span> CreatePuzzles</span> <</span> ActiveRecord</span>::</span>Migration</span></span>
  def</span> change</span></span>
    create_table </span>:</span>puzzles</span> do</span> |</span>t</span>|</span></span>
      t</span>.</span>string</span> :</span>puzzle_id</span></span>
      t</span>.</span>string</span> :</span>fen</span></span>
      t</span>.</span>string</span> :</span>moves</span></span>
      t</span>.</span>integer</span> :</span>rating</span></span>
      t</span>.</span>integer</span> :</span>rating_deviation</span></span>
      t</span>.</span>integer</span> :</span>popularity</span></span>
      t</span>.</span>integer</span> :</span>nb_plays</span></span>
      t</span>.</span>string</span> :</span>themes</span></span>
      t</span>.</span>string</span> :</span>game_url</span></span>
      t</span>.</span>string</span> :</span>opening_tags</span></span>
</span>
      t</span>.</span>timestamps</span></span>
    end</span></span>
  end</span></span>
end</span></span></code></pre>
A separate seed script pulls items from the CSV and bulk-inserts them into
SQLite. I have the following in my db/seeds.rb</code>, with a few omitted additions
that check whether or not the puzzles have already been migrated.</p>
csv_path</span> =</span> Rails</span>.</span>root</span>.</span>join</span>(</span>"tmp"</span>,</span> "lichess_db_puzzle.csv"</span>)</span></span>
raise</span> "CSV not found"</span> unless</span> File</span>.</span>exist?</span>(</span>csv_path</span>)</span></span>
</span>
buffer</span> =</span> []</span></span>
buffer_size</span> =</span> 500</span></span>
flush</span> =</span> -></span>()</span> do</span></span>
  Puzzle</span>.</span>insert_all</span>(</span>buffer</span>)</span></span>
  buffer</span>.</span>clear</span></span>
end</span></span>
</span>
CSV</span>.</span>foreach</span>(</span>csv_path</span>,</span> headers</span>:</span> true</span>)</span> do</span> |</span>row</span>|</span></span>
  buffer </span><<</span> {</span></span>
    puzzle_id</span>:</span> row</span>[</span>"PuzzleId"</span>],</span></span>
    fen</span>:</span> row</span>[</span>"FEN"</span>],</span></span>
    moves</span>:</span> row</span>[</span>"Moves"</span>],</span></span>
    rating</span>:</span> row</span>[</span>"Rating"</span>],</span></span>
    rating_deviation</span>:</span> row</span>[</span>"RatingDeviation"</span>],</span></span>
    popularity</span>:</span> row</span>[</span>"Popularity"</span>],</span></span>
    nb_plays</span>:</span> row</span>[</span>"NbPlays"</span>],</span></span>
    themes</span>:</span> row</span>[</span>"Themes"</span>],</span></span>
    game_url</span>:</span> row</span>[</span>"GameUrl"</span>],</span></span>
    opening_tags</span>:</span> row</span>[</span>"OpeningTags"</span>]</span></span>
  }</span></span>
</span>
  if</span> buffer</span>.</span>count</span> >=</span> buffer_size</span></span>
    flush</span>.()</span></span>
  end</span></span>
end</span></span>
</span>
flush</span>.()</span></span></code></pre>
And with that you have the entire Lichess puzzle database available at your
fingertips. The whole process takes less than a minute.</p>
Puzzle</span>.</span>where</span>(</span>"rating < 1700"</span>).</span>count</span></span>
# => 3035233</span></span></code></pre>


Logseq Has Perfected Note Organization
2025-02-01T00:00:00+00:00
A little while ago Apple Notes left me with quite the scare. I booted up the app
to jot down an idea and found my entire collection of notes erased. I re-synced
iCloud, nothing. Just the blank welcome screen.</p>
Luckily my notes were still backed up to iCloud, even though they weren't
displaying in the app (I checked via the web interface). After 40 minutes of
debugging and toggling a series of obtuse settings, my notes were back on my
phone. Yet the burn remained.</p>
Since then I've been looking at alternatives for my long-term document/note
storage. Apple Notes was never meant to be a formal archive of my written work,
it just came out that way due to laziness in moving my notes somewhere
permanent. I investigated the usual suspects: Notion, Obsidian, Bear, Org mode,
good ol' git and markdown. Nothing stuck. Then I found
Logseq</a> and was immediately smitten.</p>
The truth is, I don't actually use Logseq. I use Obsidian. You see, Logseq is a
outliner</em>. Every piece of text is attached to some kind of bulleted list,
whether you're writing a code sample or attaching an image. Bulleted lists are
great for notes, but not so great for blog posts or longform writing. I need a
tool that can easily handle standard markdown for this blog, for example.</p>
But despite not actually using Logseq, I've structured my Obsidian identically
to Logseq. The Logseq method of organization is just so good. Everything boils
down to three folders:</p>

journal/</code>: the place for daily notes.</li>
pages/</code>: high-level concepts that link between other pages or entries from
the journal.</li>
assets/</code>: storage for images pasted from clipboard.</li>
</ul>
That's it! Just three folders, each containing a ton of flat files. All of my
actual writing happens in journal pages, titled with the current day in
YYYY-MM-DD</code> format. I never need to think about file organization, nor do I
struggle to find information.</p>
Looking at a long list of YYYY-MM-DD</code> files sounds difficult to navigate, but
the key is that they're tagged with links to relevant pages (like
[[disco-elysium]]</code>) that attach the journal entry to a concept. When I want to
view my notes on a concept, I navigate to the concept page (disco-elysium</code>) and
read through the linked mentions. I don't need to worry about placing a
particular thought in a particular place because the link doesn't care.</p>
I got hooked on this workflow because Logseq is incredible at linked mentions.
Just take a look at this example page:</p>
</p>
All of the linked mentions (journal entries containing the tag
[[disco-elysium]]</code>) are directly embedded into the concept page. Logseq will
even embed images, code samples, to-do items, you name it. It works incredibly
well.</p>
The Obsidian equivalent isn't quite as nice, but it gets the job done. Obsidian
mentions are briefer, lack context, and stripped of formatting:</p>
</p>
The flip-side is that I don't need to write notes in an outline form and can
more easily handle moving my Obsidian notes into plain markdown files for my
blog.</p>
If you're like me and you want to use Logseq-style features in Obsidian there
are a few configuration settings that are worth knowing about:</p>

In your Core plugins/Daily notes settings, set the New file location to
journal/</code> and turn on "Open daily note on startup".</li>
In Core plugins/Backlinks, toggle "Show backlinks at the bottom of notes".</li>
In Files and links, set the "Default location for new attachments" path to
assets/</code>.</li>
</ul>
These three settings changes will get you most of the way there. That said,
before messing with those settings I encourage you to give
Logseq</a> a try. It's free and open source, it's built in
Clojure, and it has an excellent community forum</a>.
Although I don't use it for my longform/personal writing, I use it at work where
outlining fits my workflow better.</p>


Paper Puzzle Remixes
2025-01-11T00:00:00+00:00
The holidays are always a great time for puzzles. My parents still receive print
newspapers, offering an ideal opportunity to catch up on crosswords. This year I
also picked up NYT's Puzzle Mania</a>,
a treasure-trove of paper puzzle goodness. Just a few days ago my partner and I
finished the whopping 50x50 crossword puzzle. That's over 1000 clues!</p>
What struck me as especially interesting with Puzzle Mania were the paper
remixes of the popular "-dles":1</a></sup> Wordle, Spelling Bee, and Connections. Each
remix tweaks the digital puzzle form so that it suits a printed medium, changing
a few mechanics but keeping the puzzle evocative of its original design.
Puzzmo</a> did something similar with their
Crossword Vol. 1</a>,
offering print versions of
Really Bad Chess</a> and
Flipart</a>.</p>
In fact, when Puzzmo soft-launched they sent out beta invites via physical
postcards to your address. Solve the puzzle on the postcard to unlock your way
into the app.</p>
</p>
The first and third pictured are remixes of Zach Gage games:
Typeshift</a> and Really Bad Chess.
Typeshift is the more interesting of the two, since the digital version relies
on a clever sliding interface to differentiate the game from a simple
wordsearch. Adapting the game to print means the player can no longer find words
by randomly moving the slider up and down.2</a></sup> It also means lowering the number
of possible words to simplify the search.</p>
I think the popularity of "-dle" puzzle games, the kind of daily games that one
finds on NYT and Puzzmo, have to do with their resemblance to newspaper puzzles.
They're short and snackable, perfect while waiting for coffee to brew. They're
also crunchy enough that the player makes observable improvements over a long
period of time, often in the form of a solving streak.</p>
However, despite that resemblance there's a design tension that arises when
adapting a digital puzzle into a print puzzle. What kinds of mechanics are
translatable and why? How do the designers behind games like Flipart approach
print adaptation of their digital games?</p>
Zach Gage (creator of Flipart) gives some insight into the process in the
Crossword Vol. 1 collection:</p>

When we first started thinking about what kinds of puzzles we could make in
print, we felt like Flipart was one Puzzmo game that truly could not work on
paper. It was friend and fellow game designer JW Nijman who suggested a grid
with embedded shapes that players would have to draw corresponding shapes on
top of. [...] I didn't want players to have to do shape rotation in their
heads (this is tough for many people!), so I brought JW's idea to Jack...</p>
</blockquote>
I recommend playing through a game of
Flipart</a> to get a sense of the
difficulties Zach alludes to in this quote. A game of Flipart only takes tens of
seconds. It's borderline instinctual; the ocular faculties take control as
shapes rotate to avoid overlapping.</p>
In contrast, the print version of the game is slow and methodical. Rotation is
removed in favor of drawing the shape as-is. The fundamental constraint is
drawing the shape in the grid such that the drawn shape contains the square that
originally depicted it. Shapes cannot rotate and drawings cannot overlap. Print
Flipart is much more of a logic puzzle.3</a></sup></p>
</p>
Both the digital and print forms of Flipart play to the strengths of their
medium. The digital form takes advantage of the fact that the computer can
trivially render shapes in different rotations, something that's incredibly
difficult for the human mind (and tedious to draw). The print form remains
evocative of the digital, but ditches rotation in favor of something easier to
both conceptualize and draw.</p>
Converting a digital puzzle to a print puzzle is an interesting exercise. What
can we learn from the process? A few rules come to mind:</p>


Keep state simple</strong>. Unlike their digital counterparts, print puzzles cannot
represent game state that often changes or changes in unintuitive ways (like
rotations in Flipart). The best print puzzles have the player fill in the game
state as they progress, e.g. letters in crosswords, numbers in sudoku, and
shapes in print Flipart.</p>
</li>

Complicated rule evaluations are a better fit for digital puzzles</strong>. Chess
puzzles often feel more like an academic exercise than a casual puzzle, as the
player must not only think about their own optimal move, but also the optimal
response from their opponent. A puzzle that requires multiple back-and-forth
turns quickly balloons into an overwhelming number of possibilities.</p>
</li>

Rethink UI affordances</strong>. On the web, Typeshift uses a vertical slider to
add extra flavor to the puzzle-solving experience. On paper, implementing a
vertical slider is impossible. To compensate, the overall complexity of the
puzzle is reduced.</p>
</li>

Grids make for great playgrounds</strong>. I don't think it's a coincidence that
crosswords and sudokus are confined to a grid. The grid is satisfying to fill
and clearly denotes progress. It also provides a natural place to store game
state.</p>
</li>
</ul>
I also want to shout-out a fantastic game that released last year:
LOK Digital</a>. It's relevant to this whole
conversation because it actually goes in the reverse direction, adapting a print
puzzle into a digital form. Because the rules of LOK are heavily reliant on
rules evaluation, I personally think the digital adaptation is the way to go. It
makes the overall experience quite a bit more enjoyable.</p>
^{1</sup>
Not my favorite term, but an apt description of the genre after the
popularity of Wordle.</p>
</div>}^{2</sup>
Not like I've done that before, obviously.</p>
</div>}^3</sup>The print Flipart puzzles are surprisingly similar to the
tetris puzzles</a> from The
Witness.</p>
</div>


Best of 2024
2024-12-29T00:00:00+00:00
I'm always surprised when distilling a year into a single post just how many
things take place over those 365 days. When I'm in the thick of it I'm rarely
thinking about the details. Events and projects come and go, rarely do I take a
step back and properly register their impact or my feelings. So forgive me a
moment of catharsis.</p>
Game development</h2>
I made a game! It's a little game, but I'm proud of it. It received second place
in a game jam and I think it's pretty good (only 25-ish entries in the jam so
reign in the enthusiasm). At the very least, it contains my current best attempt
at level design. Play it for free:
Kat's Ghost</a>.</p>
Unsurprisingly the game is a block-pushing puzzle game similar to Sokoban. I say
unsurprisingly because the Sokoban-like has been one of my favorite subgenres of
puzzle games ever since
Stephen's Sausage Roll</a>
(which I haven't even finished because it's devilishly hard). The Sokoban-like
is the platonic ideal of a puzzle game: all logic, simple controls, simple
constraints.</p>
I also got into crossword construction this year, releasing two midi-sized
American-style crosswords. Both of which are Dungeons and Dragons themed:</p>

Dragons in Dungeons</a></li>
Adventure Awaits</a></li>
</ul>
I tried (and failed) to get the first of those puzzles accepted into
Puzzmo</a> during their open submission period.
Here's hoping my next submission does better.</p>
2024 was a big year for puzzles. The availability of free online puzzle games
like Minute Cryptic</a>,
Blockables</a>, and the mainstays of Puzzmo or NYT
have made puzzle-solving a daily exercise. We're living in the golden ages of
snackable puzzle games. My morning routine has suffered.</p>
This year also marks the release of
Braid Anniversary Edition</a>,
released 16 years after the original. It includes the most in-depth commentary
I've ever seen for a video game, talking game design, programming, art, and
music. It offers a ton of wisdom and has inspired me to create. It's also just a
phenomenal game.</p>
Start (and end) Emacs</h2>
Late 2023 and early 2024 I spent quite a bit of time on
Crafted Emacs</a> with the goal
of helping folks get started with Emacs. I've always felt that most of the
starter kits pack too much extra stuff into the base Emacs installation, making
for a very complicated or cumbersome first experience. Ditto for distributions
like DOOM or Spacemacs that effectively hijack the built-in Emacs configuration
tools in favor of custom ones (e.g. layers). Crafted Emacs felt like a nice,
intermediate step.</p>
That said, there was still something about Crafted Emacs that prevented me from
recommending it to folks that were interested in switching to Emacs. For one,
the README is that particular breed of verbosity that old-school Emacs hackers
are so fond of. Heavy on the philosophy, light on the examples. For two, the
module system is just inherently complicated. I really wanted to push new Emacs
users towards a single-file configuration, just like how I started.</p>
And so I created Start Emacs</a>. It's
basically just a "better defaults" setup for Emacs with some packages that align
the Emacs and VSCode experience. I'm particularly happy with the
extension guide</a>
guide, which moves a lot of the optional configuration into a handful of
recipes.</p>
During the making of Start Emacs I moved back to Windows as my primary dev
machine and was absolutely hating the experience. Emacs mostly worked, but
mainstays like Magit were horribly slow and many packages assumed access to
standard Linux utilities like diff</code> or grep</code>. I spent so many hours messing
around with different Windows development kits (MSYS2</a>,
w64devkit</a>, etc.) but couldn't find
something I was happy with. Finally I gave up and
swapped over to WSL</a>.</p>
This period of Windows hacking had me switching back and forth a few different
text editors while I troubleshooted Emacs, finally motivating me to try out
Helix</a>. The
vim-ish keybindings</a>
definitely threw me for a loop, sitting in that awkward area of close enough to
vim that it feels familiar, yet far enough away that I'm constantly invoking the
wrong commands. But after I garnered enough experience with it I grew to like it
so much that I started questioning my motivations. Why am I spending so much
time setting up Emacs when I have a capable editor already working?</p>
I switched and haven't looked back.</p>
I've tried writing a blog post about my new setup but I can't motivate myself
because it's so banal. I use Helix for editing text, tmux to manage terminal
windows (which works excellent in the Windows Terminal, surprisingly), and have
replaced all of my usual Emacs power features with CLI tools like ripgrep or
Awk. I'm probably not as productive since I still lack familiarity with my
tools, but I've really been enjoying leveraging a console workflow instead of
relying on a GUI editor.</p>
Am I done with Emacs? Probably. Do I still think Emacs is a great tool?
Absolutely! Don't let my experience dissuade you from trying it out.</p>
Ruby on Rails</h2>
This year felt like a great one for
Ruby on Rails</a>.
The release of Rails 8 brings a bunch of awesome improvements, including
built-in authentication, full-stack SQLite, and zero-build frontend development.
Folks are talking about Rails again and they're doing so with a ton of
enthusiasm.</p>
Coincidentally all of this Rails enthusiasm lines up with a job change for
myself, taking on a new role that does a lot more traditional Rails development.
I'm thankful that I have the opportunity to work with Ruby everyday.</p>
That said, I've never worked at a Rails shop that actually used Rails for the
frontend. Every single app that I've worked on professionally with Rails has
been an Rails JSON API paired with a SPA frontend, usually React. With SSR
making a big comeback this year (thanks to Hotwire, HTMX, among others) I'm
eager to dive into the new suite of Rails tools.</p>
Books</h2>
This year continues a reading trend from the past few years: an exploration into
Japanese literature through Haruki Murakami. Since then I've expanded to another
Japanese-borne author, Kazuo Ishiguro, and am dabbling in the works of Yukio
Mishima. But Murakami still reigns as my most-read author for the third year in
a row.</p>
He's especially notable this year thanks to the release of The City and Its
Uncertain Walls</em> in November. Let's just say the Murakami excitement was high.</p>
Here are some of my reading highlights for this year:</p>


The City and Its Uncertain Walls</em></a>
by Haruki Murakami. I just finished this one last week so it's fresh in my
memory. I was surprised at how much of this book rehashes content from
Hard-boiled Wonderland</em>, with the exploration of consciousness as a town
surrounded by a wall. Despite that, I enjoyed the deeper exploration into the
shadow-self. "My real self isn't here. It's somewhere else. The me that's here
looks like me, but is nothing more than a shadow projected onto the ground and
walls..." Quite a few aspects of this novel parallel 1Q84</em>, particularly the
protagonist who searches for a long-lost love that rules his heart. The City
and Its Uncertain Walls</em> is an exploration of the self and how it relates to
the world around us.</p>
</li>

Anathem</em></a> by
Neal Stephenson. I've seen the name Neal Stephenson on many a massive tome at
my local bookstore but haven't read any until this year. Now I'm hooked.
Anathem</em> is a slow novel in every category, but its exploration of
philosophical topics is thorough and endlessly interesting for a layperson
like me. Underpinning the novel is an exploration of realism and nominalism,
depicted through manufactured names created for the world of Anathem</em>. Just
don't come to Anathem</em> looking for plot.</p>
</li>

1Q84</em></a> by Haruki
Murakami. It's long, ponderous, and contains one too many Proust references,
but aspects of the work feel cohesive in a way that Murakami's other novels
don't. I'm also a sucker for a story about a writer. I am not prepared for a
literary analysis of 1Q84</em> though, I was mostly sailing on vibes.</p>
</li>

Never Let Me Go</em></a>
by Kazuo Ishiguro. I was introduced to Ishiguro from his most latest novel,
Klara and the Sun</em>, which I found to be an enjoyable exploration of empathy,
if a bit superficial on the Sci-Fi implications of an Android protagonist.
Never Let Me Go</em> has similar themes but delivers on them more successfully.
But man, is this book a bummer. Where Klara and the Sun</em> is light and
forgiving, Never Let Me Go</em> is oppressive and unyielding.</p>
</li>
</ul>
I also wanted to shout-out
The Awk Programming Language</em></a>
which had a second edition release late last year that I finished in February.
It's unexpectedly one of the best programming books that I've read recently for
a language that I had no prior experience with. I bought the book expecting
perl-ish one-liners for simple problems, but stayed for its profound analysis of
DSLs and Awk as a toolkit for building them. Incredible stuff. These days I have
too much enjoyment searching for problems that I can solve using little Awk
scripts.</p>
Movies</h2>
Over the last couple years I've met with a group of friends every weekend to
discuss a movie that one of us picked. A kind of movie-book-club.</p>
The result has been great. I'm thinking more critically about the media I
consume and my relationship to it. I'm exposed to other perspectives that
reflect experience I would've never gathered myself. I'm thankful to have the
opportunity to meet and talk with others about this kind of stuff.</p>
Notable films that I watched this year:</p>


Perfect Days</em></a>. I would
describe this film as a personification of Taoism. It follows the daily ritual
of a janitor for
The Tokyo Toilet</a>, an artsy
urban development project distilled into fancy toilets. The movie is slow and
contemplative and well worth the watch.</p>
</li>

Vertigo</em></a>. Lately I've been on a
little Hitchcock kick, Vertigo</em> being the first of the bunch that I haven't
already seen. Unsurprisingly, it's great. It's a bit slow, but the twists are
worth it.</p>
</li>

Evil Does Not Exist</em></a>.
2021's Drive My Car</em> is one of my favorite films, period. So I went into
Evil Does Not Exist</em> with high expectations. Unfortunately this one did not
do much for me. There's some allegorical storytelling underpinning this movie,
filling in the lines between some light plot elements and nature
cinematography. And while that cinematography is gorgeous, I couldn't shake a
sense of boredom at the many extended pauses between beats. Normally
contemplative movies are a hit for me, but this movie didn't spark any
thoughts with its storytelling that were worthy of the thoughtful moments.</p>
</li>

Autumn Sonata</em></a>. Speaking of
thoughtful moments. Look, Ingmar Bergman makes excellent movies. Autumn
Sonata</em> is no exception. There's a scene in this movie that is a slow pan onto
the face of Liv Ullmann, broadcasting an entire life's worth of emotions into
a mere thirty seconds.</p>
</li>
</ul>
Games</h2>
I was so starved for puzzles after beating Braid that I followed it up by
playing through all of The Talos Principle and about a forth of the sequel. But
neither of those games came out this year, so here's a short list of a few
others that sparked my interest.</p>


Braid: Anniversary Edition</a></em>.
Already mentioned above. Do yourself a favor and pick it up, both for the game
and the commentary.</p>
</li>

The Rookery</em></a>. You
have to be some kind of Chess sicko to get a kick out of this game, but if you
are, it will suck up a ton of your time. It's effectively Chess: the
roguelike, but executed incredibly well. It lacks the presentational details
of something like Balatro</em> (another great game this year) but still offers a
tight gameplay loop.</p>
</li>

UFO 50</em></a>. An incredible
achievement that is an easy recommendation for anyone remotely interested in
game design. There are so many ideas in this game (well, at least 50) that
twist well-known game mechanics in compelling ways. When I first heard about
this game years ago I thought it was going to be a Warioware-like collection
of minigames. Imagine my surprise when almost every one of the 50 games is
about the length of an original NES title. The fact that this game was ever
finished is an achievement. That it includes so many great games is nothing
short of amazing.</p>
</li>

Animal Well</em></a>. I
have played many metroidvanias over the years but have finished almost none of
them. Animal Well is an exception. It wasn't my favorite game to play in 2024
but it was certainly my favorite one to talk about. There was a general sense
of excitement around this title that was infectious, helped along by some
devilish secrets.</p>
</li>
</ul>
Looking ahead</h2>
Not mentioned in this post are a couple months that I spent working on a Chess
engine, or other numerous side projects that have been tabled, resumed, and
tabled again. I'm thinking a lot about my
reading stack</a>,
for lack of a better term. I've been noodling on a few ideas for building my own
Goodreads alternative that doesn't have any of the AI cruft from Storygraph,
focused purely on reading and notetaking. We'll see where it goes.</p>
I'm also attempting to break into the world of longform writing, in the way of
nonfiction. In other words, I'm writing a book. Well, several. Most of my
attempts have suffered the same fate as the average side project, with myself
working furiously until interest wanes, then promptly abandoning the idea.</p>
Eventually one of my many book ideas will make its way into a finished product,
and when that happens I hope those of you still reading this post will enjoy the
result.</p>


Automating Quick Notes with iOS Shortcuts
2024-12-24T00:00:00+00:00
I've blogged before about why I really dislike apps like Notion for
taking quick notes</a> since they're so slow to
open. The very act of opening the app to take said note often takes 10 or more
seconds, typically with a whole bunch of JavaScript-inflicted loading states and
blank screens. By the time I get to the note, I've already lost my train of
thought.</p>
As it turns out, this painpoint is a perfect candidate for the iOS Shortcuts
app. I can create an automated workflow that captures my text input instantly
but pushes to Notion in the background, allowing me to benefit from Notion's
database-like organization but without dealing with the pitiful app performance.</p>
Here's my Shortcut:</p>
</p>
Super simple but it gets the job done.</p>


Solving Puzzles by Making Puzzles
2024-12-19T00:00:00+00:00
This year I've substantially buffed up my crosswording skills. Mon-Wed on the
NYT pose no threat, and I can even occasionally solve the Thu/Fri without
checking an answer. Saturday remains befuddling.</p>
One reason for my skill improvement is repetition. The more puzzles I solve, the
more I recognize clue patterns and common words. Drill those puzzles frequently
enough and skill inevitably trickles in.</p>
In reality, repetition only explains a small sliver of my improvement. The bulk
of my newfound skill doesn't come from training crossword puzzles out in the
wild, but from
making my own</a>.</p>
Building a crossword puzzle requires activating a whole bunch of underused brain
wrinkles that remain latent when solving. Thinking of a theme and filling a
bunch of words into a grid is just one small part of the equation. How do I
measure difficulty so solvers don't get stuck? How do I compromise in a tradeoff
between word quality and theme? Why does the software keep suggesting I use
Australian birds?</p>
The construction of quality reveals the heart of the puzzle. The very same
questions I ask myself when endeavoring to make a good puzzle help reveal the
construction of puzzles created by other people. For example, I now come
equipped with a backlog of words that appear frequently thanks to their helpful
vowels (OPAL</code>, EMU</code>, ERODE</code>, ...). Difficult corners are made easier when I
consider that the uncommon words are probably grouped with more common words.
Themes are easier to spot now that I have thought of a few of my own.</p>
This same skill applies to other puzzle genres, like the humble
block-pushing puzzle game</a>. Building
interesting levels is a tough job that requires the constructor to think deeply
about the constraints of their game. I don't know about other gamedevs, but I
start by fiddling around with a random level layout, paring things back again
and again until a single core concept is revealed to be interesting. I take that
concept and build three or four levels around it, tutorializing it, expanding
it, and remixing it.</p>
This thought process has me thinking about other block-pushing puzzle games in a
completely different way. Now when I get stuck on
Patrick's Parabox</a>
I take a step back and attempt to reverse engineer the mechanic at play. Why did
the constructor choose this</em> level layout? What mechanic are they trying to
showcase? What am I supposed to take away?</p>
I suppose this same skill applies to programming, in the way of framework
design. As a user of React, I may get frustrated at the hook APIs and the design
of useEffect</code>. But if I pare back the layers and think about what the framework
is fundamentally accomplishing (that is, virtual DOM rendering with a JSX
backend) the thought process of re-renders and useEffect</code> dependencies starts
to reveal itself. Without going out and building my own virtual DOM framework
(something like snabbdom</a> is a great
start) it's hard to recognize the tradeoffs.</p>
Will constructing crossword puzzles make you a better developer? Almost
certainly not. But it's a ton of fun regardless.</p>


The Most Common React Mistake
2024-12-10T00:00:00+00:00
The React homepage promises that "learning React is learning programming" and I
think the framework somewhat delivers on it. At the very least you don't need to
learn a new templating language thanks to JSX.</p>
That said, don't be completely fooled by this promise. Like every other
JavaScript framework, React is full of subtle complexities and esoteric nuances
that have nothing to do with the language it's programmed in. In vanilla
JavaScript there's no such thing as "the rules of hooks" or the need to avoid
mutable variables in favor of useState</code>.1</a></sup></p>
The subject of this post is one such piece of esoteric knowledge that I see
newcomers trip up against when learning React (spoilers: it's useEffect</code>). It's
a great demonstration of the subtle complexities of React, where the promises of
JavaScript-ness meet the reality of framework design.</p>
The problems of syncing async state</h2>
A classic point of friction is the introduction of asynchronous code. You have
some data from the server and you want to render it in your component to
populate the initial values of a form. That last bit is where the bug arises,
forms usually use controlled components which hold onto their values via
useState</code> calls. Attempting to populate the initial value of useState</code> hooks
from asynchronous code inevitably runs into a tricky issue. It's easiest to
demonstrate by example.</p>
Here's a simple component that wraps an HTML input</code> and captures its value:</p>
const</span> MyInput</span> =</span> ({</span> initialText</span> =</span> ''</span> })</span> =></span> {</span></span>
  const</span> [</span>text</span>,</span> setText</span>]</span> =</span> useState</span>(initialText)</span></span>
</span>
  const</span> handleChange</span> =</span> (</span>ev</span>)</span> =></span> {</span></span>
    setText</span>(ev</span>.</span>target</span>.</span>value)</span></span>
  }</span></span>
</span>
  return</span> <</span>input</span> value</span>=</span>{</span>text</span>}</span> onChange</span>=</span>{</span>handleChange</span>}</span> /></span></span>
}</span></span></code></pre>
It's a
controlled input</a>
because the state variable text</code> dictates the value of input</code>. You might
render MyInput</code> in the template of a form, like so:</p>
const</span> App</span> =</span> ()</span> =></span> {</span></span>
  return</span> (</span></span>
    <</span>form</span>></span></span>
      <</span>MyInput</span> /></span></span>
    </</span>form</span>></span></span>
  )</span></span>
}</span></span></code></pre>
Perhaps even with an initial value by passing the prop initialText</code>:</p>
const</span> App</span> =</span> ()</span> =></span> {</span></span>
  return</span> (</span></span>
    <</span>form</span>></span></span>
      <</span>MyInput</span> initialText</span>=</span>"starting value"</span> /></span></span>
    </</span>form</span>></span></span>
  )</span></span>
}</span></span></code></pre>
This is all fine and dandy. The input correctly initializes with the value of
initialText</code> when passing a string and correctly handles user input.</p>
The problem arises when initialText</code> is asynchronous, as is often the case when
dealing with forms that are populated with data from a server. For example,
introducing a new function getTextFromServer</code> that simulates a 300ms response
time:</p>
const</span> getTextFromServer</span> =</span> (</span>ms</span> =</span> 300</span>)</span> =></span></span>
  new</span> Promise</span>(</span>(</span>resolve</span>)</span> =></span> {</span></span>
    setTimeout</span>(</span>()</span> =></span> {</span></span>
      resolve</span>(</span>'text from server'</span>)</span></span>
    },</span> ms)</span></span>
  }</span>)</span></span>
</span>
const</span> App</span> =</span> ()</span> =></span> {</span></span>
  const</span> [</span>asyncText</span>,</span> setAsyncText</span>]</span> =</span> useState</span>(</span>''</span>)</span></span>
</span>
  useEffect</span>(</span>()</span> =></span> {</span></span>
    const</span> fetch</span> =</span> async</span> ()</span> =></span> {</span></span>
      const</span> text</span> =</span> await</span> getTextFromServer</span>()</span></span>
      setAsyncText</span>(text)</span></span>
    }</span></span>
</span>
    fetch</span>()</span></span>
  },</span> [])</span></span>
</span>
  return</span> (</span></span>
    <</span>form</span>></span></span>
      <</span>MyInput</span> initialText</span>=</span>{</span>asyncText</span>}</span> /></span></span>
    </</span>form</span>></span></span>
  )</span></span>
}</span></span></code></pre>
A routine operation in React code: wrap an async fetch call with a useEffect</code>
and monitor the async state with useState</code>. However, run this code and you'll
find a bug. Can you spot it in the code?</p>
Here's the problem: the initial value of MyInput</code> is never populated with the
value of asyncText</code>. It remains blank, even after the getTextFromServer</code>
promise resolves.</p>
Naturally the first step is to log out what's going on with initialText</code>. Is
the prop not being updated?</p>
const</span> MyInput</span> =</span> ({</span> initialText</span> })</span> =></span> {</span></span>
  console</span>.</span>log</span>(initialText)</span></span>
  // ...</span></span></code></pre>
Here's what you'll see:</p>
""</span></span>
"text from server"</span></span></code></pre>
Well, actually this looks right. On the first render pass, the value is ""</code>,
the initial value of the useState</code> in the parent. After getTextFromServer</code>
responds with the string "text from server"</code>, that useState</code> is updated and
the child component, MyInput</code>, is re-rendered. It receives the new value of
"text from server"</code> from props.</p>
Well then, how come MyInput</code> is blank?</p>
This is where the most common React mistake is introduced. At this point in
debugging, a new developer searches for a framework solution to this problem. We
just encountered one such solution for handling async state by using
useEffect</code>, what if we were to use it again?</p>
const</span> MyInput</span> =</span> ({</span> initialText</span> =</span> ''</span> })</span> =></span> {</span></span>
  const</span> [</span>text</span>,</span> setText</span>]</span> =</span> useState</span>(initialText)</span></span>
</span>
  useEffect</span>(</span>()</span> =></span> {</span></span>
    setText</span>(initialText)</span></span>
  },</span> [initialText])</span></span>
</span>
  const</span> handleChange</span> =</span> (</span>ev</span>)</span> =></span> {</span></span>
    setText</span>(ev</span>.</span>target</span>.</span>value)</span></span>
  }</span></span>
</span>
  return</span> <</span>input</span> value</span>=</span>{</span>text</span>}</span> onChange</span>=</span>{</span>handleChange</span>}</span> /></span></span>
}</span></span></code></pre>
Now when the value of the initialText</code> prop updates asynchronously, MyInput</code>
updates to match. The useEffect</code> monitors the dependency change in
initialText</code> and calls setText</code> in response. No more blank input!</p>
Generally when I see this kind of code appear in the wild, it's accompanied by
the text "for some reason React isn't updating MyInput</code> with the new value of
initialText</code> so I put in a useEffect</code> to keep things in sync." That "for some
reason" is revealing: something is happening in React-land that I don't really
understand, but at least I solved it using a React-like solution.2</a></sup></p>
Here's the rub: sure, this code solves the problem. But it's also incredibly
brittle. This solution isn't obviously incorrect because developer machines are
fast and we're usually dealing with sub-100ms response times from whatever API
we're working with. In other words, because of quick response times, a developer
might not notice the pop-in when MyInput</code> is updated with the asynchronous
value.</p>
The thing is slow connections (e.g. mobile phones accessing your application,
server saturation, etc.) will experience increasingly worse pop-in because of
this useEffect</code> change. In the worst-case scenario, a user could type text into
MyInput</code> and have that text cleared away by the useEffect</code> after asyncText</code>
is loaded! Try increasing getTextFromServer</code> to 3000</code> and see the result
yourself.</p>
The other problem with this kind of code is that we've effectively doubled the
number of renders of the MyInput</code> component. Sure, in this contrived example
more renders is not doing any harm, but you can imagine that for particularly
complicated components that set 10s of hundreds of different pieces of state,
additional renders are to be avoided. State-syncing code of the kind in this
example often leads to more state-syncing due to extraneous render passes, a
problem that keeps on giving as your application grows.3</a></sup></p>
So what's actually happening with the MyInput</code> useState</code>? Why isn't it picking
up the new value of initialText</code> from the component prop? The answer is hidden
away in the React documentation (emphasis mine):</p>

useState</code> Parameters:</p>

initialState</code>: The value you want the state to be initially. It can be a
value of any type, but there is a special behavior for functions. This
argument is ignored after the initial render</strong>.</li>
</ul>
</blockquote>
"Ignored after the initial render", meaning even though the prop initialText</code>
is updated correctly, the useState</code> that wraps text</code> doesn't care. It's
memoized such that any additional renders of the component will have no effect
on the state variable it encapsulates.</p>
If you think about it, this behavior makes sense. In 90% of cases, you wouldn't
want your state variables to be blown away by component re-renders. When you use
useState</code> you expect it to hold onto a value until setState</code> is called, and
the memoization achieves that goal.</p>
Now that we know more about how useState</code> works behind the scenes, we can find
a different solution for the problem of handling asynchronous initial state.</p>
Solution: handle the pending state</h2>
So what should you do instead? The easiest solution is to have the parent
component own the loading state:</p>
const</span> MyInput</span> =</span> ({</span> initialText</span> =</span> ''</span> })</span> =></span> {</span></span>
  const</span> [</span>text</span>,</span> setText</span>]</span> =</span> useState</span>(initialText)</span></span>
</span>
  const</span> handleChange</span> =</span> (</span>ev</span>)</span> =></span> {</span></span>
    setText</span>(ev</span>.</span>target</span>.</span>value)</span></span>
  }</span></span>
</span>
  return</span> <</span>input</span> value</span>=</span>{</span>text</span>}</span> onChange</span>=</span>{</span>handleChange</span>}</span> /></span></span>
}</span></span>
</span>
function</span> App</span>() {</span></span>
  const</span> [</span>isLoading</span>,</span> setIsLoading</span>]</span> =</span> useState</span>(</span>false</span>)</span></span>
  const</span> [</span>asyncText</span>,</span> setAsyncText</span>]</span> =</span> useState</span>(</span>''</span>)</span></span>
</span>
  useEffect</span>(</span>()</span> =></span> {</span></span>
    const</span> fetch</span> =</span> async</span> ()</span> =></span> {</span></span>
      setIsLoading</span>(</span>true</span>)</span></span>
      const</span> text</span> =</span> await</span> getTextFromServer</span>()</span></span>
      setIsLoading</span>(</span>false</span>)</span></span>
      setAsyncText</span>(text)</span></span>
    }</span></span>
</span>
    fetch</span>()</span></span>
  },</span> [])</span></span>
</span>
  return</span> (</span></span>
    <</span>form</span>></span></span>
      {</span>isLoading</span> ? <</span>p</span>></span>loading...</span></</span>p</span>> : <</span>MyInput</span> initialText</span>=</span>{</span>asyncText</span>}</span> /></span>}</span></span>
    </</span>form</span>></span></span>
  )</span></span>
}</span></span></code></pre>
MyInput</code> goes back to its original form: a single useState</code> that accepts
initialText</code> as an argument. Because MyInput</code> is only rendered when
asyncText</code> has been fetched from the server (determined via isLoading</code> in the
parent component) the resulting useState</code> is called once with an initial value
of "text from server"</code>. There's no longer any need to sync state because the
initial render of the component has the desired state.</p>
I'll argue that thinking about loading states is actually the power of avoiding
useEffect</code> to solve these kinds of problems. By moving control of the loading
state up the component hierarchy, developers need to put more thought into the
async nature of their application and how the UI will handle it.</p>
Going back into the discussion of React complexity and the burden of frameworks,
the whole counter-intuitive nature of useState</code> discarding its argument after
the first render is a mind-bender for the beginner. I could imagine spending a
few hours on this problem and getting nowhere because it's hard to conceptualize
that the cause is actually within the framework itself, buried in the
implementation detail of memoization in the useState</code> hook. It takes time to
encounter these kinds of issues in React, but spend enough time with it and they
will inevitably rise to the surface.</p>
^{1</sup>
Although of course there's the vanilla JS alternative of needing to
re-render the DOM when you update application state, but that's neither here
nor there.</p>
</div>
^{2</sup>
I want to re-emphasize that I don't think the developer is at fault here.
They encountered a subtle problem that is super confusing and solved it
using the tools React gives them. I think it's a very natural way of
thinking about things.</p>
</div>
^{3</sup>
State-syncing begets more state-syncing because the lifecycle of state
values becomes hard to reconcile, and the only solution is to set state
again to ensure everything is the most recent.</p>
</div>}}}


Type predicates to avoid casting
2024-12-03T00:00:00+00:00
Type predicates</a>
have been around but today I found a particularly nice application. The
situation is this: I have an interface that has an optional field, where the
presence of that field means I need to create a new object on the server, and
the lack of the field means the object has already been created and I'm just
holding on to it for later. Here's what it looked like:</p>
interface</span> Thing</span> {</span></span>
  name</span>:</span> string</span></span>
  blob</span>?:</span> File</span></span>
}</span></span>
</span>
const</span> things</span>:</span> Thing[]</span> =</span> [</span></span>
  /* ... */</span></span>
]</span></span>
</span>
const</span> uploadNewThings</span> =</span> (</span>things</span>:</span> (Thing</span> &</span> {</span> blob</span>:</span> File</span> }</span>)[]</span>)</span> =></span></span>
  Promise</span>.</span>all</span>(things</span>.</span>map</span>(</span>(</span>thing</span>)</span> =></span> createThing</span>(thing</span>.</span>name</span>,</span> thing</span>.</span>blob)))</span></span></code></pre>
The intersection type Thing & { blob: File }</code> means that uploadNewThings</code> only
accepts things</code> that have the field blob</code>. In other words, things that need to
be created on the server because they have blob content.</p>
However, TypeScript struggles if you try to simply filter the list of things</code>
before passing it into uploadNewThings</code>:</p>
uploadNewThings</span>(things</span>.</span>filter</span>(</span>(</span>thing</span>)</span> => !!</span>thing</span>.</span>blob))</span></span></code></pre>
The resulting error is this long stream of text:</p>
Argument of type 'Thing[]' is not assignable to parameter of type '(Thing & { blob: File; })[]'.</span></span>
  Type 'Thing' is not assignable to type 'Thing & { blob: File; }'.</span></span>
    Type 'Thing' is not assignable to type '{ blob: File; }'.</span></span>
      Types of property 'blob' are incompatible.</span></span>
        Type 'File | undefined' is not assignable to type 'File'.</span></span>
          Type 'undefined' is not assignable to type 'File'.</span></span></code></pre>
The tl;dr being that despite filtering things</code> by thing => !!thing.blob</code>,
TypeScript does not recognize that the return value is actually
Thing & { blob: File }</code>.</p>
Now you could just cast it,</p>
things</span>.</span>filter</span>(</span>(</span>thing</span>)</span> => !!</span>thing</span>.</span>blob)</span> as</span> (Thing</span> &</span> {</span> blob</span>:</span> File</span> }</span>)[]</span></span></code></pre>
But casting is bad! It's error-prone and doesn't really</em> solve the problem that
TypeScript is hinting at. Instead, use a type predicate:</p>
const</span> hasBlob</span> =</span> (</span>t</span>:</span> Thing</span>)</span>:</span> t</span> is</span> Thing</span> &</span> {</span> blob</span>:</span> File</span> }</span> => !!</span>t</span>.</span>blob</span></span>
</span>
uploadNewThings</span>(things</span>.</span>filter</span>(hasBlob))</span></span></code></pre>
With the type predicate (t is Thing & ...</code>) I can inform TypeScript that I do
in fact know what I'm doing, and that the call to filter</code> results in a
different interface.</p>


Data migrations with data-migrate
2024-11-13T00:00:00+00:00
What I traditionally would've used Rake tasks for has been replaced with
data-migrate</a>, a little gem that
handles data migrations in the same way as Rails schema migrations. It's the
perfect way to automate data changes in production, offering a single pattern
for handling data backfills, seed scripts, and the like.</p>
The pros are numerous:</p>

Data migrations are easily generated via CLI and are templated with an up</code>
and down</code> case so folks think about rollbacks.</li>
Just like with Rails schema migrations, there's a migration ID kept around
that ensures data migrations are run in order. Old PRs will have merge
conflicts.</li>
You can conditionally run data migrations alongside schema migrations with
bin/rails db:migrate:with_data</code>.</li>
</ul>
It's a really neat gem. I'll probably still rely on the good ol' Rake task for
my personal projects, but will doubtless keep data-migrate</code> in the toolbox for
teams.</p>


Cool Rails concerns
2024-11-09T00:00:00+00:00
There's something super elegant about Writebook's</a>
use of concerns. I especially like Book:Sluggable</code>:</p>
module</span> Book</span>::</span>Sluggable</span></span>
  extend</span> ActiveSupport</span>::</span>Concern</span></span>
</span>
  included </span>do</span></span>
    before_save </span>:</span>generate_slug</span>,</span> if</span>:</span> -></span> {</span> slug</span>.</span>blank?</span> }</span></span>
  end</span></span>
</span>
  def</span> generate_slug</span></span>
    self</span>.</span>slug</span> =</span> title</span>.</span>parameterize</span></span>
  end</span></span>
end</span></span></code></pre>
Here's a few reasons:</p>

Nesting concerns in a model folder is neat when that concern is an
encapsulation of model-specific functionality: app/models/book/sluggable.rb</code>.</li>
Concerns don't have to be big. They do have to be single-purpose.</li>
Reminds me of a great article by Jorge Manrubla:
Vanilla Rails is plenty</a>.
Down with service objects!</li>
</ul>


Why I Still Use Apple Notes
2024-10-30T00:00:00+00:00
My list of reasons for using Apple Notes isn't very long. In many ways I think
Apple Notes is an inferior app, especially when comparing it to alternatives
like Notion, Obsidian, and the like. There is one thing that keeps me using it,
however. Simplicity.</p>
Organization is a death sentence for spontaneity. Tools like Notion have me
questioning my note placement before I've written a single word, killing the
idea before it's had a moment to begin. I've lost track of ideas due to a
distracting home screen ("Oh, I should check my email"), or navigating a Notion
sidebar ("Where's the archive again?"), or generating the title of the very note
I'm starting to write.</p>
Therefore, I value flow over all else. Nothing is more important than getting
the idea into some storage mechanism as fast as humanly possible. Expedience is
the same reason I don't carry a paper notebook and a pen, despite preferring
writing by hand to tapping on a piece of glass. When inspiration strikes and I
need to jot down an idea right now</em> nothing beats Apple Notes. Pop open the
app, hit the lower-right corner, type type type.</p>
Every month or so I'll peruse my notes and organize them into better, more
permanent places. 90% of the time that means deleting the note. I'm not very
sentimental1</a></sup>. The remaining 10% is moved into a GitHub README if it's a
project idea or drafted into a proper blog post (markdown + git). This whole
categorization phase is a moment of catharsis and feels wholly productive.</p>
I've always been turned off by the term "second brain". Despite what
productivity gurus say I don't think my simple notes will ever amount to some
magnum opus of material, studied by historians in the distant future. Nor do I
think there's much value in the nitpicky categorization that makes up a
zettelkasten. I believe those who spend the majority of their time organizing
notes and staring at their Obsidian graph view are fooling themselves into
thinking they're more productive. Sure, it's pretty. But is my writing any
better?</p>
Productivity software preys upon novelty. New apps tout new approaches that will
always catch me in the allure of efficiency. Let this ode to Apple Notes serve
as a reminder that sometimes simple is better.</p>
^{1</sup>
Part of my notetaking philosophy is that a note has served its purpose
through the mechanism of its creation. Field Notes puts it well: "I'm not
writing it down to remember it later, I'm writing it down to remember it
now." So when I say 90% I mean it.</p>
</div>}


Exploring the Writebook Source Code
2024-10-13T00:00:00+00:00
Earlier this year 37signals released Writebook</a>, a
self-hosted book publishing platform. It's offering number two from their
ONCE</a> series, pitched as the antithesis of SaaS. Buy it once
and own it for life, but run it on your own infrastructure.</p>
Unlike the other ONCE offering, Writebook is totally free. When you "purchase"
it through the ONCE checkout, they hook you up with the source code and a
convenient means of downloading the software on a remote service. Since the
software is free (but not open source) I thought it's fair game to read through
it and write a little post about its implementation. It's not everyday that we
can study a production Rails application made by the same folks behind Rails
itself.</p>

Note: I'll often omit code for the sake of brevity with a "--snip" marker. I
encourage you to download Writebook yourself and follow along so you can
discover the complete context.</p>
</blockquote>
Run the thing</h2>
A good place to start is the application entrypoint: Procfile</code>. I think
Procfile</code> is a holdover from the Heroku-era, when everyone was hosting their
Rails applications on free-tier dynos (RIP). Either way, it describes the
top-level processes that make up the server:</p>
web: bundle exec thrust bin/start-app</span></span>
redis: redis-server config/redis.conf</span></span>
workers: FORK_PER_JOB=false INTERVAL=0.1 bundle exec resque-pool</span></span></code></pre>
Nice and simple. There are three main components:</p>

web</code>, Writebook's web and application server</li>
redis</code>, the backing database for the application cache and asynchronous
workers</li>
workers</code>, the actual process that executes asynchronous tasks</li>
</ul>
The only other infrastructure of note is the application database, which is
running as a single file via SQLite3.</p>
bundle exec thrust bin/start-app</code> might be surprising for folks expecting
bin/rails server</code> as the main Rails process. thrust</code> is the command invocation
for thruster</a>, a fairly recent
HTTP proxy developed by 37signals specifically for ONCE projects. It provides a
similar role to nginx, a web server that sits in front of the main Rails process
to handle static file caching and TLS. The thrust</code> command takes a single
argument, bin/start-app</code>, which contains your standard bin/rails s</code>
invocation, booting up the application server.</p>
Redis and workers</code> fill out the rest of the stack. Redis fills a few different
purposes for Writebook, serving as the application cache and the task queue for
asynchronous work. I'm a little surprised
Solid Queue</a> and
Solid Cache</a> don't make an appearance,
swapping out Redis for the primary data store (SQLite in this case). But then
again, perhaps it's more cost-efficient to run Redis in this case, since
Writebook probably wants to be self-hosted on minimal hardware (and not have
particular SSD requirements).</p>
You can run the application locally with
foreman</a> (note you'll need Redis installed,
as well as libvips for image processing):</p>
foreman start</span></span></code></pre>Pages that render markdown</h2>
When it comes to the textual content of books created with Writebook, everything
boils down to the Page</code> model and it's fancy has_markdown :body</code> invocation:</p>
class</span> Page</span> <</span> ApplicationRecord</span></span>
  # --snip</span></span>
  has_markdown </span>:</span>body</span></span>
end</span></span></code></pre>
That single line of code sets up an
ActionText</a>
association with Page</code> under the attribute name body</code>. All textual content in
Writebook is stored in the respective ActionText table, saved as raw markdown.
Take a look at this Rails console query for an example:</p>
writebook(dev)> Page.first.body.content</span></span>
=> "# Welcome to Writebook\n\nThanks for downloading Writebook...</span></span></code></pre>
To my surprise, has_markdown</code> is not actually a Rails ActionText built-in. It's
manually extended into Rails by Writebook in
lib/rails_ext/action_text_has_markdown.rb</code>, along with a couple other files
that integrate ActionText with the third-party gem
redcarpet</a>:</p>
module</span> ActionText</span></span>
  module</span> HasMarkdown</span></span>
    extend</span> ActiveSupport</span>::</span>Concern</span></span>
</span>
    class_methods </span>do</span></span>
      def</span> has_markdown</span>(</span>name</span>,</span> strict_loading</span>:</span> strict_loading_by_default</span>)</span></span>
		# --snip</span></span>
</span>
        has_one </span>:"</span>markdown_</span>#{</span>name</span>}",</span> -></span> {</span> where</span>(</span>name</span>:</span> name</span>) },</span></span>
          class_name</span>:</span> "ActionText::Markdown"</span>,</span> as</span>: :</span>record</span>,</span> inverse_of</span>: :</span>record</span>,</span> autosave</span>:</span> true</span>,</span> dependent</span>: :</span>destroy</span>,</span></span>
          strict_loading</span>:</span> strict_loading</span></span>
</span>
        # --snip</span></span>
      end</span></span>
    end</span></span>
  end</span></span>
end</span></span>
</span>
# ...</span></span>
</span>
module</span> ActionText</span></span>
  class</span> Markdown</span> <</span> Record</span></span>
	# --snip</span></span>
    mattr_accessor </span>:</span>renderer</span>,</span> default</span>:</span> Redcarpet</span>::</span>Markdown</span>.</span>new</span>(</span></span>
      Redcarpet</span>::</span>Render</span>::</span>HTML</span>.</span>new</span>(</span>DEFAULT_RENDERER_OPTIONS</span>),</span> DEFAULT_MARKDOWN_EXTENSIONS</span>)</span></span>
</span>
    belongs_to </span>:</span>record</span>,</span> polymorphic</span>:</span> true</span>,</span> touch</span>:</span> true</span></span>
</span>
    def</span> to_html</span></span>
      (</span>renderer</span>.</span>try</span>(:</span>call</span>)</span> ||</span> renderer</span>).</span>render</span>(</span>content</span>).</span>html_safe</span></span>
    end</span></span>
  end</span></span>
end</span></span></code></pre>
lib/rails_ext/</code> as the folder name is very intentional. The code belongs in
lib/</code> and not app/lib/</code> because it's completely agnostic to the application.
It's good ol' reusable Ruby code for any Rails application that has ActionText.
rails_ext/</code> stands for "Rails extension", a common naming convention for vendor
monkey patches that might live in a Rails application. This code re-opens an
existing namespace (the ActionText</code> module, in this case) and adds new
functionality (ActionText::Markdown</code>). Within the application, users can use
ActionText::Markdown</code> without evet knowing it's not a Rails built-in.</p>
This is a neat little implementation for adding markdown support to ActionText,
which is normally just a rich text format coupled to the
Trix editor</a>.</p>
Beyond pages</h2>
Page</code> is certainly the most important data model when it comes to the core
functionality of Writebook: writing and rendering markdown. The platform
supports a couple other fundamental data types, that being Section</code> and
Picture</code>, that can be assembled alongside Pages</code> to make up an entire Book</code>.</p>
The model hierarchy of a Book</code> looks something like this:</p>
Book = Leaf[], where Leaf = Page | Section | Picture</span></span></code></pre>
In other words, a Book</code> is made up of many Leaf</code> instances (leaves), where a
Leaf</code> is either a Page</code> (markdown content), a Section</code> (basically a page
break with a title), or a Picture</code> (a full-height image).</p>
</p>
You can see the three different Leaf</code> kinds near the center of the image,
representing the three different types of content that can be added to a Book</code>.
This relationship is clearly represented by the Rails associations in the
respective models:</p>
# app/models/book.rb</span></span>
class</span> Book</span> <</span> ApplicationRecord</span></span>
  # --snip</span></span>
  has_many </span>:</span>leaves</span>,</span> dependent</span>: :</span>destroy</span></span>
end</span></span>
</span>
# app/models/leaf.rb</span></span>
class</span> Leaf</span> <</span> ApplicationRecord</span></span>
  # --snip</span></span>
  belongs_to </span>:</span>book</span>,</span> touch</span>:</span> true</span></span>
  delegated_type </span>:</span>leafable</span>,</span> types</span>:</span> Leafable</span>::</span>TYPES</span>,</span> dependent</span>: :</span>destroy</span></span>
  positioned_within </span>:</span>book</span>,</span> association</span>: :</span>leaves</span>,</span> filter</span>: :</span>active</span></span>
end</span></span></code></pre>
Well, maybe not completely "clearly". One thing that's interesting about this
implementation is the use of a Rails concern and delegated_type</code> to represent
the three kinds of leaves:</p>
module</span> Leafable</span></span>
  extend</span> ActiveSupport</span>::</span>Concern</span></span>
</span>
  TYPES</span> =</span> %w[</span> Page Section Picture </span>]</span></span>
</span>
  included </span>do</span></span>
    has_one </span>:</span>leaf</span>,</span> as</span>: :</span>leafable</span>,</span> inverse_of</span>: :</span>leafable</span>,</span> touch</span>:</span> true</span></span>
    has_one </span>:</span>book</span>,</span> through</span>: :</span>leaf</span></span>
</span>
    delegate </span>:</span>title</span>,</span> to</span>: :</span>leaf</span></span>
  end</span></span>
end</span></span></code></pre>
There are three kinds of Leaf</code> that Writebook supports: Page</code>, Section</code>, and
Picture</code>. Each Leaf</code> contains different attributes according to its kind. A
Page</code> has ActionText::Markdown</code> content, a Section</code> has plaintext, and a
Picture</code> has an image upload and a caption. However, despite their difference
in schema, each of the three Leaf</code> kinds is used in the exact same way by
Book</code>. In other words, Book</code> doesn't care which kind of Leaf</code> it holds a
reference to.</p>
This is where delegated_type</code> comes into play. With delegated_type</code>, all of
the shared attributes among our three Leaf</code> kinds live on the "superclass"
record, Leaf</code>. Alongside those shared attributes is a leafable_type</code>, denoting
which "subclass" the Leaf</code> falls into, one of "Page"</code>, "Section"</code>, or
"Picture"</code>. When we call Leaf#leafable</code>, we fetch data from the matching
"subclass" table to pull the non-shared attributes for that Leaf</code>.</p>
The pattern is made clear when querying in the Rails console:</p>
writebook(dev)> Leaf.first.leafable</span></span>
SELECT "leaves".* FROM "leaves" ORDER BY "leaves"."id" ASC LIMIT 1</span></span>
SELECT "pages".* FROM "pages" WHERE "pages"."id" = ?</span></span></code></pre>
Rails knows from leafable_type</code> that Leaf.first</code> is a Page</code>. To read the rest
of that Leaf</code>'s attributes, we need to fetch the Page</code> from the pages</code> table
associated to the leafable_id</code> on the record. Same deal for Section</code> and
Picture</code>.</p>
Another thing that's interesting about Writebook's use of delegated_type</code> is
that the Leaf</code> model isn't exposed on a route:</p>
  resources </span>:</span>books</span>,</span> except</span>: %i[</span> index show </span>]</span> do</span></span>
    # --snip</span></span>
    resources </span>:</span>sections</span></span>
    resources </span>:</span>pictures</span></span>
    resources </span>:</span>pages</span></span>
  end</span></span></code></pre>
This makes a ton of sense because the concept of Leaf</code> isn't exactly
"user-facing". It's more of an implementation detail. The relation between the
three different Leafable</code> types is exposed by some smart inheritance in each of
the "subclasses". Take SectionsController</code> as an example:</p>
class</span> SectionsController</span> <</span> LeafablesController</span></span>
  private</span></span>
    def</span> new_leafable</span></span>
      Section</span>.</span>new</span> leafable_params</span></span>
    end</span></span>
</span>
    def</span> leafable_params</span></span>
      params</span>.</span>fetch</span>(:</span>section</span>, {}).</span>permit</span>(:</span>body</span>, :</span>theme</span>)</span></span>
        .</span>with_defaults</span>(</span>body</span>:</span> default_body</span>)</span></span>
    end</span></span>
</span>
    def</span> default_body</span></span>
      params</span>.</span>fetch</span>(:</span>leaf</span>, {})[:</span>title</span>]</span></span>
    end</span></span>
end</span></span></code></pre>
All of the public controller handlers are implemented in LeafablesController</code>,
presumably because each Leafable</code> is roughly handled in the same way. The only
difference is the params object sent along in the request to create a new
Leaf</code>.</p>
class</span> LeafablesController</span> <</span> ApplicationController</span></span>
  # --snip</span></span>
  def</span> create</span></span>
    @leaf</span> =</span> @book</span>.</span>press</span> new_leafable</span>,</span> leaf_params</span></span>
    position_new_leaf @leaf</span></span>
  end</span></span>
end</span></span></code></pre>
I appreciate the nomenclature of Book#press</code> to create add a new Leaf</code> to a
Book</code> instance. Very clever.</p>
Authentication and users</h2>
My go-to when setting up authentication with Rails is
devise</a> since it's an easy drop-in
component. Writebook instead implements its own lightweight authentication
around the built-in has_secure_password</code>:</p>
class</span> User</span> <</span> ApplicationRecord</span></span>
  include</span> Role</span>,</span> Transferable</span></span>
</span>
  has_many </span>:</span>sessions</span>,</span> dependent</span>: :</span>destroy</span></span>
  has_secure_password </span>validations</span>:</span> false</span></span>
</span>
  has_many </span>:</span>accesses</span>,</span> dependent</span>: :</span>destroy</span></span>
  has_many </span>:</span>books</span>,</span> through</span>: :</span>accesses</span></span>
  # --snip</span></span>
end</span></span></code></pre>
The authentication domain in Writebook is surprisingly complicated because the
application supports multiple users with different roles and access permissions,
but most of it is revealed through the User</code> model.</p>
The first time you visit a Writebook instance, you're asked to provide an email
and password to create the first Account</code> and User</code>. This is represented via a
non-ActiveRecord model class, FirstRun</code>:</p>
class</span> FirstRun</span></span>
  ACCOUNT_NAME</span> =</span> "Writebook"</span></span>
</span>
  def</span> self.create!</span>(</span>user_params</span>)</span></span>
    account</span> =</span> Account</span>.</span>create!</span>(</span>name</span>:</span> ACCOUNT_NAME</span>)</span></span>
</span>
    User</span>.</span>create!</span>(</span>user_params</span>.</span>merge</span>(</span>role</span>: :</span>administrator</span>)).</span>tap</span> do</span> |</span>user</span>|</span></span>
      DemoContent</span>.</span>create_manual</span>(</span>user</span>)</span></span>
    end</span></span>
  end</span></span>
end</span></span></code></pre>
Whether or not a user can access or edit a book is determined by the
Book::Accessable</code> concern. Basically, a Book</code> has many Access</code> objects
associated with it, each representing a user and a permission. Here's the
Access</code> created for the DemoContent</code> referenced in FirstRun</code>:</p>
#<Access:0x00007f06efac0538</span></span>
  id: 1,</span></span>
  user_id: 1,</span></span>
  book_id: 1,</span></span>
  level: "editor"</span></span>
  #--snip></span></span></code></pre>
Likewise, when new users are invited to a book, they are assigned an Access</code>
level that matches their permissions (reader or editor). Note that all of this
access-stuff is for books that have not yet been published to the web for public
viewing. Writebook allows you to invite early readers or editors for feedback
before you go live.</p>
Whoa, whoa, whoa. What is this rate_limit</code> on the SessionsController</code>?</p>
class</span> SessionsController</span> <</span> ApplicationController</span></span>
  allow_unauthenticated_access </span>only</span>: %i[</span> new create </span>]</span></span>
  rate_limit </span>to</span>:</span> 10</span>,</span></span>
             within</span>:</span> 3</span>.</span>minutes</span>,</span></span>
             only</span>: :</span>create</span>,</span></span>
             with</span>:</span> -></span> {</span> render_rejection </span>:</span>too_many_requests</span> }</span></span></code></pre>
Rails 8 comes with built-in
rate limiting support</a>? That's
awesome.</p>
Style notes</h2>
I like the occasional nesting of concerns under model classes, e.g.
Book::Sluggable</code>. These concerns aren't reusable (hence the nesting), but they
nicely encapsulate a particular piece of functionality with a callback and a
method.</p>
# app/models/book/sluggable.rb</span></span>
module</span> Book</span>::</span>Sluggable</span></span>
  extend</span> ActiveSupport</span>::</span>Concern</span></span>
</span>
  included </span>do</span></span>
    before_save </span>:</span>generate_slug</span>,</span> if</span>:</span> -></span> {</span> slug</span>.</span>blank?</span> }</span></span>
  end</span></span>
</span>
  def</span> generate_slug</span></span>
    self</span>.</span>slug</span> =</span> title</span>.</span>parameterize</span></span>
  end</span></span>
end</span></span></code></pre>
Over on the HTML-side, Writebook doesn't depend on a CSS framework. All of the
classes are hand-written and applied in a very flexible,
atomic</a> manner:</p>
<</span>div</span> class</span>=</span>"page-toolbar fill-selected align-center gap-half ..."</span>></</span>div</span>></span></span></code></pre>
These classes are grouped together in a single file, utilities.css</code>. Who needs
Tailwind?</p>
.</span>justify-end</span> {</span></span>
  justify-content</span>:</span> end</span>;</span></span>
}</span></span>
.</span>justify-start</span> {</span></span>
  justify-content</span>:</span> start</span>;</span></span>
}</span></span>
.</span>justify-center</span> {</span></span>
  justify-content</span>:</span> center</span>;</span></span>
}</span></span>
.</span>justify-space-between</span> {</span></span>
  justify-content</span>:</span> space-between</span>;</span></span>
}</span></span>
/* --snip */</span></span></code></pre>
I'm also surprised at how little JavaScript is necessary for Writebook. There
are only a handful of StimulusJS controllers, each of which encompasses a tiny
amount of code suited to a generic purpose. The AutosaveController</code> is probably
my favorite:</p>
import</span> {</span> Controller</span> }</span> from</span> '@hotwired/stimulus'</span></span>
import</span> {</span> submitForm</span> }</span> from</span> 'helpers/form_helpers'</span></span>
</span>
const</span> AUTOSAVE_INTERVAL</span> =</span> 3000</span></span>
</span>
export default class extends</span> Controller</span> {</span></span>
  static</span> classes</span> =</span> [</span>'clean'</span>,</span> 'dirty'</span>,</span> 'saving'</span>]</span></span>
</span>
  #timer</span></span>
</span>
  // Lifecycle</span></span>
</span>
  disconnect</span>() {</span></span>
    this</span>.</span>submit</span>()</span></span>
  }</span></span>
</span>
  // Actions</span></span>
</span>
  async</span> submit</span>() {</span></span>
    if</span> (</span>this</span>.</span>#dirty)</span> {</span></span>
      await</span> this</span>.</span>#save</span>()</span></span>
    }</span></span>
  }</span></span>
</span>
  change</span>(</span>event</span>) {</span></span>
    if</span> (event</span>.</span>target</span>.</span>form</span> ===</span> this</span>.</span>element</span> && !</span>this</span>.</span>#dirty)</span> {</span></span>
      this</span>.</span>#scheduleSave</span>()</span></span>
      this</span>.</span>#updateAppearance</span>()</span></span>
    }</span></span>
  }</span></span>
</span>
  // Private</span></span>
</span>
  async</span> #</span>save</span>() {</span></span>
    this</span>.</span>#updateAppearance</span>(</span>true</span>)</span></span>
    this</span>.</span>#resetTimer</span>()</span></span>
    await</span> submitForm</span>(</span>this</span>.</span>element)</span></span>
    this</span>.</span>#updateAppearance</span>()</span></span>
  }</span></span>
</span>
  #</span>updateAppearance</span>(</span>saving</span> =</span> false</span>) {</span></span>
    this</span>.</span>element</span>.</span>classList</span>.</span>toggle</span>(</span>this</span>.</span>cleanClass</span>,</span> !</span>this</span>.</span>#dirty)</span></span>
    this</span>.</span>element</span>.</span>classList</span>.</span>toggle</span>(</span>this</span>.</span>dirtyClass</span>,</span> this</span>.</span>#dirty)</span></span>
    this</span>.</span>element</span>.</span>classList</span>.</span>toggle</span>(</span>this</span>.</span>savingClass</span>,</span> saving</span>)</span></span>
  }</span></span>
</span>
  #</span>scheduleSave</span>() {</span></span>
    this</span>.</span>#timer</span> =</span> setTimeout</span>(</span>()</span> =></span> this</span>.</span>#save</span>()</span>,</span> AUTOSAVE_INTERVAL)</span></span>
  }</span></span>
</span>
  #</span>resetTimer</span>() {</span></span>
    clearTimeout</span>(</span>this</span>.</span>#timer)</span></span>
    this</span>.</span>#timer</span> =</span> null</span></span>
  }</span></span>
</span>
  get</span> #</span>dirty</span>() {</span></span>
    return</span> !!</span>this</span>.</span>#timer</span></span>
  }</span></span>
}</span></span></code></pre>
When you're editing markdown content with Writebook, this handy controller
automatically saves your work. I especially appreciate the disconnect handler
that ensures your work is always persisted, even when you navigate out of the
form to another area of the application.</p>
Closing thoughts</h2>
There's more to explore here, particularly on the HTML side of things where
Hotwire does a lot of the heavy lifting. Unfortunately I'm not a good steward
for that exploration since most of my Rails experience involves some sort of
API/React split. The nuances of HTML-over-the-wire are over my head.</p>
That said I'm impressed with Writebook's data model, it's easy to grok thanks to
some thoughtful naming and strong application of lesser-known Rails features
(e.g. delegated_type</code>). I hope this code exploration was helpful and inspires
the practice of reading code for fun.</p>


HEY to Fastmail and Back Again
2024-10-05T00:00:00+00:00
I've read a few stories about folks moving their email from HEY to Fastmail, but
have not seen any in the reverse direction. After two years of Fastmail, I'm
moving back to HEY. Here are my thoughts.</p>
For those unacquainted with HEY, the main pitch is (a) screen unknown senders
(b) into one of three locations: "Imbox", "The Feed", and "Paper Trail". Senders
that are "screened out" are completely blocked, you won't be notified again from
that address. For those "screened in", the split inbox offers more than just
filters and labels. "The Feed" for example aggregates emails into a continuous
reader view that's nice browsing on a weekend morning. There are many
more features</a> but these two are probably the
most important ones.</p>
In my first HEY adventure, I had an @hey.com</code> address for $99/yr. My primary
motivation was moving away from Gmail and freeing some of my dependence on
Google products, which I still maintain is worthwhile. HEY pulled me in with the
marketing, but at $99 I wasn't convinced I was receiving enough value for the
price tag. When I saw that Fastmail supported
Masked Email</a>, my mind was made up. Added
privacy at half the cost? Yes please.</p>
So I migrated, eating the cost of cycling yet another email address but setting
up a custom email domain along the way to future-proof my erratic email
exploration tendencies. I followed this
guide from Franco Correa</a>
to emulate some of the HEY functionality in Fastmail, attempting to hold on to
some of the principles that improved my workflow.</p>
Two years later and I'm moving back to HEY.</p>
Why switch back? The decision mostly comes down to the difference in user
experience between the two apps. Fastmail feels like a chore to use, especially
on iOS where most of my email (and newsletter) reading happens. Here are my two
biggest problems:</p>

I'd often need to close and reopen the Fastmail app because it was stuck on a
black screen. Particularly frustrating when on a slow connection because it
means going through the whole SPA-style loading animation that can take 10-20
seconds.</li>
Using contacts + groups as substitutes for "The Feed" and "Paper Trail" is
tedious. Email addresses that go into either bucket must first be added to
contacts, then edited to include the appropriate filtering group. I honestly
can't remember how to do this in the mobile app.</li>
</ul>
There were also a handful of workflows that I was missing from HEY:</p>

The ability to merge threads and create collections is incredible when dealing
with travel plans. Rather than juggling a bunch of labels for different trips,
email threads are neatly organized into one spot for each.</li>
"Send me push notifications" on an email thread, which will notify me when
that thread and only that thread receives replies, is genius.</li>
I created a "Set Aside" folder in Fastmail but eventually found myself missing
the nice little stack of email threads that are bundled up in a corner in the
HEY app.</li>
Bundling email from certain senders into a single thread</a>
is an excellent solution for notification streams from Github or Amazon, where
I want to be alerted with updates but don't want to have a bunch of separate
email threads taking up space in my inbox.</li>
I really like clips</a> as an
alternative to slapping on a label so I know to revisit an email for some
buried content.</li>
</ul>
Don't get me wrong, Fastmail is a great service. If I didn't find out that
masked email could be replaced by
DuckDuckGo Email Protection</a> I would probably
still be using it1</a></sup>. I'm especially fond of their investment in
JMAP</a> and attempts
to make the technical ecosystem around email better. Also, if you want to have
multiple custom domains routing to the same email platform, Fastmail is way more
cost effective.</p>
But, having moved back to HEY, I've discovered that I'm easily swayed by
software that can please and delight. Many of HEY's features are UX oddities
that don't exactly nail down ways to make email better, but make the experience
of using it more enjoyable. I think HEY gets it right most of the time.</p>
The calendar is a new addition to HEY in the time that I've been away and it's
interesting. I'm not hugely opinionated when it comes to calendars, I hardly use
them outside of work where my company dictates the platform. The HEY calendar
feels split between innovating for the sake of novelty and innovating for the
sake of good ideas.</p>
For one, there's no monthly view. Only day and week. Instead of viewing a
complete month you view an endless scroll of weeks, with about three and a half
fitting on the screen at any given time. The daily/weekly focus of HEY Calendar
seems catered to daily activities: journaling, photography, and habit tracking.
Not so much complicated scheduling workflows.</p>
HEY's email offering still has some rough spots as well:</p>

No import from an existing email.</li>
Adding additional custom domains is prohibitively expensive for a single user.</li>
Feature rollout is asymmetrical, web and Android often outpace iOS.</li>
Two separate apps for calendar and email (minor, but kind of annoying).</li>
Journal integration with the calendar is interesting, but I'm hesitant to use
it because there's no export.</li>
Can't use HEY with an external app (e.g. Thunderbird).</li>
Still can't configure swipe actions on iOS.</li>
</ul>
Some of these (like swipe actions and import) are longtime issues that will
probably never be addressed. It's probably also worth noting that the HEY
workflow is rather opinionated and isn't guaranteed to hit. But hey, give it a
try and see if it works for you.</p>
Moral of the story: use custom email domains. It protects you from email vendor
lock-in so you're free to experiment as you see fit.</p>
^{1</sup>
On that topic, masked email is such a critical privacy feature for email
that I can't believe HEY doesn't offer it. I suppose the screener is meant
to alleviate that concern (since unwanted emails must be manually
screened-in) but it's not quite the same. I'd rather rest easy knowing that
only a randomly-generated email winds up in marketing garbage lists.</p>
</div>}


Crafting Interpreters, Ruby Style
2024-08-18T00:00:00+00:00
I finally have started working through
Crafting Interpreters</a>, a wonderful book
about compilers by Robert Nystrom. The book steps through two interpreter
implementations, one in Java and one in C, that ramp in complexity.</p>
Now I don't know about you, but I hate Java. I can hardly stand to read it, let
alone write it. That's why I decided to write my first Lox interpreter in Ruby,
following along with the book as I can but converting bits and pieces into
Rubyisms as I see fit.</p>
In general, the Java code can be ported 1-1 to Ruby with no changes. Of course
there's some obvious stuff, like lack of types means I need fewer methods and no
coersions, or certain stdlib method namespaces that are updated to match Ruby
idioms (while</code> vs. until</code>, anyone?). However, lots of code I just accept as-is
and allow Nystrom to guide me through.</p>
I've only worked through the first 7 chapters, but I did note down a few things
in the Ruby conversion that I found interesting.</p>
Avoiding switch statement fallthrough with regular expressions</h2>
Admittedly this difference is just a tiny syntactical detail, but one that plays
to Ruby's strengths. Take the book's implementation of scanToken</code>:</p>
private void</span> scanToken</span>() {</span></span>
  char</span> c</span> =</span> advance</span>();</span></span>
  switch</span> (</span>c</span>) {</span></span>
    case</span> '('</span>:</span> addToken</span>(</span>LEFT_PAREN</span>);</span> break</span>;</span></span>
    // ...</span></span>
    default:</span></span>
      if</span> (</span>isDigit</span>(</span>c</span>)) {</span></span>
        number</span>();</span></span>
      }</span> else if</span> (</span>isAlpha</span>(</span>c</span>)) {</span></span>
        identifier</span>();</span></span>
      }</span> else</span> {</span></span>
        Lox</span>.</span>error</span>(</span>line</span>,</span> "Unexpected character."</span>);</span></span>
      }</span></span>
  }</span></span>
}</span></span>
</span>
private boolean</span> isDigit</span>(</span>char</span> c</span>) {</span></span>
  return</span> c </span>>=</span> '0'</span> &&</span> c </span><=</span> '9'</span>;</span></span>
}</span></span>
</span>
// private boolean isAlpha...</span></span></code></pre>
Due to limitations in the Java switch statement, the author adds some
post-fallthrough checks to the default</code> case. This removes the need to check
every number and letter individually (0-9, a-z, A-Z as separate cases) because
the check is deferred into the default case, where an additional conditional
statement is applied. Aesthetically it's not an ideal solution since it breaks
up the otherwise regular pattern of case ... handler</code> that holds for the other
tokens. I don't know, it's just kinda ugly.</p>
With Ruby, I can instead employ regular expressions directly in my switch
statement:</p>
def</span> scan_token</span></span>
  case</span> advance</span></span>
  when</span> "("</span></span>
    add_token</span>(:</span>left_paren</span>)</span></span>
  # ...</span></span>
  when</span> /[</span>[:digit:</span>]</span>]</span>/</span></span>
    number</span></span>
  when</span> /[</span>[:alpha:</span>]</span>]</span>/</span></span>
    identifier</span></span>
  else</span></span>
    Lox</span>.</span>error</span>(</span>@line</span>,</span> "unexpected character"</span>)</span></span>
  end</span></span>
end</span></span></code></pre>
No default fallthrough needed! These tiny details are what keep me programming
in Ruby.</p>
Metaprogramming the easy way</h2>
The largest deviation between the Java and Ruby implementation is definitely the
metaprogramming. In
Implementing Syntax Trees</a>
the author employs metaprogramming through an independent build step.</p>
First, a new package is created (com.craftinginterpreters.tool</code>) with a couple
of classes that themselves generate Java classes by writing strings to a file:</p>
  private static void</span> defineType</span>(</span></span>
      PrintWriter</span> writer</span>,</span> String</span> baseName</span>,</span></span>
      String</span> className</span>,</span> String</span> fieldList</span>) {</span></span>
    writer</span>.</span>println</span>(</span>"  static class "</span> +</span> className </span>+</span> " extends "</span> +</span></span>
        baseName </span>+</span> " {"</span>);</span></span>
</span>
    // Constructor.</span></span>
    writer</span>.</span>println</span>(</span>"    "</span> +</span> className </span>+</span> "("</span> +</span> fieldList </span>+</span> ") {"</span>);</span></span>
</span>
    // Store parameters in fields.</span></span>
    String</span>[]</span> fields</span> =</span> fieldList</span>.</span>split</span>(</span>", "</span>);</span></span>
    for</span> (</span>String</span> field</span> :</span> fields</span>) {</span></span>
      String</span> name</span> =</span> field</span>.</span>split</span>(</span>" "</span>)[</span>1</span>];</span></span>
      writer</span>.</span>println</span>(</span>"      this."</span> +</span> name </span>+</span> " = "</span> +</span> name </span>+</span> ";"</span>);</span></span>
    }</span></span>
</span>
    writer</span>.</span>println</span>(</span>"    }"</span>);</span></span>
</span>
    // Fields.</span></span>
    writer</span>.</span>println</span>();</span></span>
    for</span> (</span>String</span> field</span> :</span> fields</span>) {</span></span>
      writer</span>.</span>println</span>(</span>"    final "</span> +</span> field </span>+</span> ";"</span>);</span></span>
    }</span></span>
</span>
    writer</span>.</span>println</span>(</span>"  }"</span>);</span></span>
  }</span></span></code></pre>
These string builders are hooked up to a separate entrypoint (made for the
tool</code> Java package) and are compiled separately. The result spits out a bunch
of .java</code> files into the com.craftinginterpreters.lox</code> package, whereby the
programmer checks them into the project.</p>
It's not a bad solution by any means, but requiring a separate build step and
metaprogramming by concatenating strings is a little rough. The Ruby solution is
totally different thanks to a bunch of built-in metaprogramming utilities (and
the fact that Ruby is an interpreted language).</p>
Here's how I wired up the expression generation:</p>
module</span> Rlox</span></span>
  module</span> Expr</span></span>
    EXPRESSIONS</span> =</span> [</span></span>
      [</span>"Binary"</span>, [:</span>left</span>, :</span>operator</span>, :</span>right</span>]],</span></span>
      [</span>"Grouping"</span>, [:</span>expression</span>]],</span></span>
      [</span>"Literal"</span>, [:</span>value</span>]],</span></span>
      [</span>"Unary"</span>, [:</span>operator</span>, :</span>right</span>]]</span></span>
    ]</span></span>
</span>
    EXPRESSIONS</span>.</span>each</span> do</span> |</span>expression</span>|</span></span>
      classname</span>,</span> names </span>=</span> expression</span></span>
</span>
      klass</span> =</span> Rlox</span>::</span>Expr</span>.</span>const_set</span>(</span>classname</span>,</span> Class</span>.</span>new</span>)</span></span>
      klass</span>.</span>class_eval</span> do</span></span>
        attr_accessor</span>(</span>*</span>names</span>)</span></span>
</span>
        define_method</span>(:</span>initialize</span>)</span> do</span> |</span>*</span>values</span>|</span></span>
          names</span>.</span>each_with_index</span> do</span> |</span>name</span>,</span> i</span>|</span></span>
            instance_variable_set</span>(:"</span>@</span>#{</span>name</span>}",</span> values</span>[</span>i</span>])</span></span>
          end</span></span>
        end</span></span>
</span>
        define_method</span>(:</span>accept</span>)</span> do</span> |</span>visitor</span>|</span></span>
          visitor</span>.</span>public_send</span>(:"</span>visit_</span>#{</span>classname</span>.</span>downcase</span>}</span>_expr</span>",</span> self</span>)</span></span>
        end</span></span>
      end</span></span>
    end</span></span>
  end</span></span>
end</span></span></code></pre>
When this file is included into rlox.rb</code> (the main entrypoint to the
interpreter), Ruby goes ahead and builds all of the expression classes
dynamically. No build step needed, just good ol' Ruby metaprogramming.
Rlox::Expr.const_set</code> adds the class to the scope of the Rlox::Expr</code> module,
re-opening it on the next line via class_eval</code> to add in the
automatically-generated methods.</p>
To close the loop, here's what one of the generated classes looks like if it
were to be written out by hand (while also avoiding the dynamic instance
variable setter):</p>
module</span> Rlox</span></span>
  module</span> Expr</span></span>
    class</span> Binary</span></span>
      attr_accessor</span> :</span>left</span>, :</span>operator</span>, :</span>right</span></span>
</span>
      def</span> initialize</span>(</span>left</span>,</span> operator</span>,</span> right</span>)</span></span>
        @left</span> =</span> left</span></span>
        @operator</span> =</span> operator</span></span>
        @right</span> =</span> right</span></span>
      end</span></span>
</span>
      def</span> accept</span>(</span>visitor</span>)</span></span>
        visitor</span>.</span>visit_binary_expr</span>(</span>self</span>)</span></span>
      end</span></span>
    end</span></span>
  end</span></span>
end</span></span></code></pre>
Comparing the Ruby and Java implementation is interesting because it highlights
some higher-level advantages and disadvantages between the two languages. With
the Ruby version, adding new types is trivial and does not require an additional
compile + check-in step. Just add a name-argument pair to the EXPRESSIONS</code>
constant and you're done!</p>
The flip-side of this is the class is not easily inspectable. Although I wrote
Rlox::Expr::Binary</code> above this paragraph as regular Ruby code, that code
doesn't exist anywhere in the application where a programmer's eyes can read it.
Instead, developers have to read the metaprogramming code in expr.rb</code> to
understand how the classes work.</p>
I think this implementation leans idiomatic Ruby: metaprogramming is part of the
toolkit so it's expected for developers to learn how to deal with it. If you're
interested in learning how the class works and can't understand the
metaprogramming code, you can always boot up the console and poke around with an
instance of the class. It kind of coincides with the Ruby ethos that a REPL
should be close at hand so you can explore code concepts that you might
otherwise misunderstand by reading the code.</p>
That said, I still have respect for the Java implementation because Ruby
metaprogramming can really end up biting you in the ass.</p>
TDD (well, not really)</h2>
I'm sure Nystrom omitted tests from the book because it would add a ton of
implementation noise to the project, and not in a way that benefited the
explanation. For my purposes, I wanted to make sure I added tests with each
chapter to make sure my implementation wasn't drifting from the expectation.</p>
It's not perfect by any means, but it definitely gives me a ton of confidence
that I'm following along with the material and exercising some of the trickier
edge cases. I was also impressed that Nystrom's implementation is really easy to
test. Here's an example from the parser:</p>
class</span> TestParser</span> <</span> Minitest</span>::</span>Test</span></span>
  def</span> test_it_handles_comparison</span></span>
    got</span> =</span> parse</span>(</span>"2 > 3"</span>)</span></span>
</span>
    assert_instance_of </span>Rlox</span>::</span>Expr</span>::</span>Binary</span>,</span> got</span></span>
    assert_equal </span>:</span>greater</span>,</span> got</span>.</span>operator</span>.</span>type</span></span>
    assert_equal </span>2.0</span>,</span> got</span>.</span>left</span>.</span>value</span></span>
    assert_equal </span>3.0</span>,</span> got</span>.</span>right</span>.</span>value</span></span>
</span>
    got</span> =</span> parse</span>(</span>"2 >= 3"</span>)</span></span>
</span>
    assert_instance_of </span>Rlox</span>::</span>Expr</span>::</span>Binary</span>,</span> got</span></span>
    assert_equal </span>:</span>greater_equal</span>,</span> got</span>.</span>operator</span>.</span>type</span></span>
    assert_equal </span>2.0</span>,</span> got</span>.</span>left</span>.</span>value</span></span>
    assert_equal </span>3.0</span>,</span> got</span>.</span>right</span>.</span>value</span></span>
</span>
    got</span> =</span> parse</span>(</span>"2 < 3"</span>)</span></span>
</span>
    assert_instance_of </span>Rlox</span>::</span>Expr</span>::</span>Binary</span>,</span> got</span></span>
    assert_equal </span>:</span>less</span>,</span> got</span>.</span>operator</span>.</span>type</span></span>
    assert_equal </span>2.0</span>,</span> got</span>.</span>left</span>.</span>value</span></span>
    assert_equal </span>3.0</span>,</span> got</span>.</span>right</span>.</span>value</span></span>
</span>
    got</span> =</span> parse</span>(</span>"2 <= 3"</span>)</span></span>
</span>
    assert_instance_of </span>Rlox</span>::</span>Expr</span>::</span>Binary</span>,</span> got</span></span>
    assert_equal </span>:</span>less_equal</span>,</span> got</span>.</span>operator</span>.</span>type</span></span>
    assert_equal </span>2.0</span>,</span> got</span>.</span>left</span>.</span>value</span></span>
    assert_equal </span>3.0</span>,</span> got</span>.</span>right</span>.</span>value</span></span>
  end</span></span>
</span>
  def</span> parse</span>(</span>str</span>)</span></span>
    scanner</span> =</span> Rlox</span>::</span>Scanner</span>.</span>new</span>(</span>str</span>)</span></span>
    tokens</span> =</span> scanner</span>.</span>scan_tokens</span></span>
    parser</span> =</span> Rlox</span>::</span>Parser</span>.</span>new</span>(</span>tokens</span>)</span></span>
    # Call private method to bubble up exception that is caught by #parse</span></span>
    parser</span>.</span>send</span>(:</span>expression</span>)</span></span>
  end</span></span>
end</span></span></code></pre>
Astute readers might recognize that the parse</code> helper function defined within
the test is also calling into the Rlox::Scanner</code> class. That's one item that
I've taken the quick and easy approach towards: rather than ensure test
isolation by writing out the AST with the Rlox::Expr</code>/Rlox::Statement</code> classes
(which are incredibly verbose), I use Rlox::Scanner</code> so I can write my tests as
string expressions that read like the code I'm testing. Unfortunately, that does
mean that if I write a bug into the Rlox::Scanner</code> class, that bug is
propogated into the Rlox::Parser</code> tests, but in my head it's better than the
alternative of tripling the lines of code for my test files. What can you do?</p>
Next steps</h2>
There might be a part two for this post as I work my way further through the
first Lox interpreter. If you're interested in following along with the code,
check it out on Github</a>.</p>


New stuff in Emacs 30
2024-07-28T00:00:00+00:00
Emacs 30.1 is near on the horizon with the most recent pretest (30.0.93) made
available in late December</a>.
This post highlights some new features in the upcoming release that I find
especially compelling.</p>
If you want to know everything</em> that's upcoming, check out
the full release notes</a>.</p>
Native compilation enabled by default</h2>
This is huge!</p>
Native compilation</a>
was introduced in Emacs 28 behind a configuration flag, so even though it's been
around for a little while you probably aren't using it unless you compile your
Emacs from source (or use a port that explicitly had it enabled). Enabling it by
default brings it to more users.</p>
This feature compiles Emacs Lisp functions to native code, offering 2-5x faster
performance to the byte-compiled counterpart. The downside is an additional
dependency (libgccjit</code>) and a little extra compilation overhead when installing
a package for the first time. The downsides are so minor that enabling it by
default is a no-brainer.</p>
Native (and faster) JSON support</h2>
You no longer need an external library (libjansson</code>) to work with JSON in
Emacs. On top of that, JSON parsing performance in Emacs is significantly
improved (the author provides that parsing is up to 8x faster</strong>). This is all
thanks to Géza Herman's contribution:
I created a faster JSON parser</a>.
He summarizes his changes later in that thread:</p>

My parser creates Lisp objects during parsing, there is no intermediate step
as Emacs has with jansson. With jansson, there are a lot of allocations, which
my parser doesn't have (my parser has only two buffers, which exponentially
grow. There are no other allocations). But even ignoring performance loss
because of mallocs (on my dataset, 40% of CPU time goes into malloc/free), I
think parsing should be faster, so maybe jansson is not a fast parser in the
first place.</p>
</blockquote>
Great stuff.</p>
use-package version control support</h2>
You can now install packages directly from version-controlled repositories (for
those packages that aren't yet in ELPA, Non-GNU ELPA or MELPA).</p>
For example:</p>
(</span>use-package</span> bbdb</span></span>
  :</span>vc</span> (</span>:</span>url</span> "https://git.savannah.nongnu.org/git/bbdb.git"</span></span>
       :</span>rev</span> :</span>newest</span>))</span></span></code></pre>
This also means that you can opt into package updates based on commit instead of
latest release (e.g. :rev :newest</code>). I think this is actually a sleeper feature
of :vc</code>, since the default Emacs package release/update cycle can be a little
wonky at times.</p>
If you want all of your :vc</code> packages to prefer the latest commit (instead of
the latest release), you can set use-package-vc-prefer-newest</code> to t</code>.</p>
Tree-sitter modes are declared as submodes</h2>
I had to read this change a few times before I grokked what it was saying.
Tree-sitter modes, e.g. js-ts-mode</code>, are now submodes of their non-tree-sitter
counterpart, e.g. js-mode</code>. That means any configuration applied to the
non-tree-sitter mode also applies to the tree-sitter mode.</p>
In other words, my .dir-locals.el</code> settings for js-mode</code> simply apply to
js-ts-mode</code> as well, without needing to write it explicitly. A nice quality of
life change to help pare down Emacs configurations that rely on both modes
(which is more common than you might think, given that non-tree-sitter modes are
typically more featureful).</p>
Minibuffer QOL improvements</h2>
Some nice quality-of-life improvements for the default Emacs completions:</p>


You can now use the arrow keys to navigate the completion buffer vertically
(in addition to the M-<up|down></code> keybindings).</p>
</li>

Previous minibuffer completion selections are deselected when you begin typing
again (to avoid accidentally hitting a previous selection).</p>
</li>

completions-sort</code> has a new value: historical</code>. Completion candidates will
be sorted by their order in minibuffer history so that recent candidates
appear first.</p>
</li>
</ul>
Customize interface for dir-locals</h2>
There's now a customize interface for
Directory Variables</a>:</p>
M-x customize-dirlocals</span></span></code></pre>
I always find myself forgetting the .dir-locals.el</code> syntax (even though they're
just lists!) so this is a surprisingly handy feature for me.</p>
New mode: visual-wrap-prefix-mode</h2>
Now this one is cool. I'm the kind of guy who uses auto-mode</code> for everything
because I haven't bothered to figure out how Emacs line wrapping works.
Everything I write hard breaks into newlines after 80 characters.</p>
The new mode visual-wrap-prefix-mode</code> is like auto-mode</code>, except that the
breaks are for display purposes only. I think this is incredibly useful when
editing text that might be reviewed using a diffing tool, since long lines tend
to display more useful diffs than a paragraph broken up with hard breaks. I'm
actually pretty excited about this change, maybe it will get me to stop using
(markdown-mode . (( mode . auto-fill))</code> everywhere.</p>
New command: replace-regexp-as-diff</h2>
You can now visualize regular expression replacements as diffs before they're
accepted. This is actually incredible.</p>
New package: which-key</h2>
Previously a package in GNU ELPA, which-key-mode</code> is now built-in. With
which-key-mode</code> enabled, after you begin a new command (e.g. C-x</code>) and wait a
few seconds, a minibuffer will pop up with a list of possible keybinding
completions. It's a super handy tool for remembering some of the more esoteric
modes.</p>
New customizations</h2>


Show the current project (via project.el</code>) in your modeline with
project-mode-line</code>.</p>
</li>

Add right-aligned modeline elements via mode-line-format-right-align</code>.</p>
</li>

You can now customize the venerable yes-or-no-p</code> function with
yes-or-no-prompt</code>.</p>
</li>
</ul>
A few Emacs Lisp changes</h2>
There are a few small, yet impactful changes around help buffers and Emacs Lisp
types that I think are worth noting.</p>

describe-function</code> shows the function inferred type when available:</li>
</ul>
C-h f concat RET</span></span>
</span>
(concat &rest SEQUENCES)</span></span>
  Type: (function (&rest sequence) string)</span></span></code></pre>

Built-in types show their related classes:</li>
</ul>
C-h o integer RET</span></span>
</span>
integer is a type (of kind ‘built-in-class’).</span></span>
 Inherits from ‘number’, ‘integer-or-marker’.</span></span>
 Children ‘fixnum’, ‘bignum’.</span></span></code></pre>

The byte compiler warns if a file is missing the lexical binding directive.
Lexical bindings have been included in ELisp for awhile now, so it's nice to
see more effort being made towards making it the default.</li>
</ul>
;;; Foo mode  </span>-*-</span> lexical-binding</span>:</span> t</span> -*-</span></span></code></pre>Read the full details</h2>
That wraps up my highlights. There's a ton more stuff included in Emacs 30.1 so
I encourage you to
check it out the NEWS yourself</a>.</p>
PS. Interested in trying out Emacs but don't know where to start? Check out my
MIT-licensed configuration guide:
Start Emacs</a>.</p>


Recently
2024-06-19T00:00:00+00:00
Recently I've been deep down a crossword puzzle rabbit hole. I started a new
side project that has taken most of my writing energy:
them's crossing words</a>, a blog where I post daily
crossword puzzle reviews and articles about the craft of puzzle construction.
Thus far there's about fifty crossword puzzles featured and discussed, a sizable
number of grids with over 10k words dedicated to crossing them.</p>
When I started the project I thought I might burn out quickly on the idea.
Writing a daily review was actually far from my original intent. The thing is,
there's just so much to talk about when it comes to the art of crossword
construction (and puzzles in general, by extension). Every crossword is nuanced
and interesting, built by constructors that bring their own voice into the grid
with interesting clues and clever themes.</p>
The idea of a puzzle blog has been bouncing around in my head for a long time
now, and my motivation to start one was largely influenced by the release of
Braid, Anniversary Edition</a>.
When I was a kid playing through Braid on the Xbox Live Arcade, I didn't
actually care that much for puzzle games. They were too slow and plodding for my
High School brain.</p>
Since then I've come to really appreciate the genre, with games like The Witness
and Outer Wilds completely blowing my mind as to what's possible in the medium
of video games. When Braid re-released this year with loads of developer
commentary, I was in.</p>
Now that I'm playing through it as an adult I have a newfound appreciation for
its narrative and design. There are loads of spots where the narrative of the
tale is paralleled by the mechanics of the gameplay and the design of the
puzzles, a genius combination of factors seen in few games. What really drew me
in, however, was the developer commentary, discussing the minutiae of game,
sound, narrative, and art design behind every level and artistic motif.</p>
The body of commentary in Braid, Anniversary Edition is staggering. The amount
of thought that bleeds into every ounce of that game is an incredible
achievement showing just how artistic the medium of video games can be. It
inspired me to start writing about puzzles because I think they're more than
just a method of wasting time. They're little worlds of simulation where ideas
mesh with action, a creative landscape of human ingenuity clashing with
constraints.</p>
Needless to say I've been noodling on puzzles for the last few months, looking
back on some of my old Puzzlescript prototypes</a> and
some of the things I learned about game design when I hacked them together.
Building a level for a puzzle game is kind of like mentoring new engineers. You
never really know how well you understand an idea until you need to teach it to
someone. Same goes for a mechanic in a puzzle game: what is the truth that
you're trying to expose to the person playing your game? Why is it interesting?</p>
Anyway, this is less of a Recently and more of a ramble.</p>
For this blog, I've also been interested in exploring systems languages now that
I have a year or so of Rust experience under my belt. I'm curious about the idea
of manual memory management and how it is handled by various different
languages, especially with the recent uptick in C-alternatives, like Zig, Odin,
Jai, among others. I've also been wanting to do a post on "learning systems
languages as a webdev" for awhile now, exploring the Rust ecosystem as a Ruby on
Rails/JavaScript developer. I think I need a stronger baseline in systems
performance before I try to tackle that subject.</p>
Right now I'm reading through A Tour of C++</em> and Understanding Software
Dynamics</em>, testing my knowledge of performance programming and how computers
actually work under the hood. It's been a humbling experience working in manual
memory scenarios after so many years of garbage-collected languages. It's a
different landscape when you have to deal with certain hot-paths in a game loop,
for example, where allocations can lead to undesirable performance
characteristics.</p>


Markdown Rendering with Awk
2024-03-23T00:00:00+00:00
I can't believe I'm writing
another post about Awk</a> but I'm just having too
much fun throwing together tiny Awk scripts. This time around that tiny Awk
script is a markdown renderer, converting markdown to good ol' HTML.</p>
Markdown is interesting because 80% of the language is rather easy to implement
by walking through a file and applying a regular expression to each line. Most
implementations seem to start this way. However, once that final 20% is hit some
aspects of the language start to show their warts, exposing the not-so-happy
path that eventually leads to lexical analysis.</p>
To list a few examples,</p>


there are many elements that can span more than one line, like paragraph
emphasis, links, or bolded text</p>
</li>

elements can encompass sub-elements like a russian doll, e.g. headers that
include emphasized text that itself is bolded</p>
</li>

elements can defy existing behavior, like code blocks that can themselves
contain unrendered markdown</p>
</li>
</ul>
Each of these conditions complicates the simple line-based approach.</p>
The renderer that I'm building doesn't aim to be comprehensive, so most of these
edge cases are not handled. For my toy renderer, I'm assuming that the markdown
is written in accordance to a general style guide with friendly linebreaks
between paragraphs.</p>
I am also being careful to call this project an markdown "renderer" and not a
"parser" because it's not really</em> parsing the markdown file. Instead, we're
immediately replacing markdown with HTML. The difference may seem nitpicky but
implies that there's no intermediate format between the markdown and the HTML
output, a nuance that makes this implementation less powerful but also much
simpler.</p>
Let's get cracking.</p>
Initial approach</h2>
Headers are a natural first step. The solution emphasizes Awk's strengths when
it comes to handing line-based input:</p>
/^</span># / { print "<h1>" substr($0, 3) "</h1>" }</span></span></code></pre>
This reads, "On every line, match #</code> followed by a space. Replace that line
with header tags and the text of that line beginning at index 3 (one-based
indexing)." Since we're piping awk</code> into another file, print</code> statements are
effectively writing our rendered HTML.</p>
Line replacements are the name of the game in Awk, where the simplicity of the
syntax really shines. The call to substr</code> is less elegant than the usual
space-delimited Awk fields ($1</code>, $2</code>, etc.), but it's necessary since we want
to preserve the entire line sans the first two characters (the leading header
hashtag).</p>
The remaining headers follow the same pattern:</p>
/^</span># /   { print "<h1>" substr($0, 3) "</h1>" }</span></span>
/^</span>## /  { print "<h2>" substr($0, 4) "</h2>" }</span></span>
/^</span>### / { print "<h3>" substr($0, 5) "</h3>" }</span></span>
# ...</span></span></code></pre>
For something a little trickier, let's move on to block quotes. Block quotes in
Markdown look like the following, leading each line with a caret:</p>
> Deep in the human unconscious is a pervasive need for a logical universe that</span></span>
> makes sense. But the real universe is always one step beyond logic. - Frank</span></span>
> Herbert</span></span></code></pre>
Finding block quote lines is easy, we just use the same approach as our headers:</p>
/^> /</span> {</span> print</span> "<blockquote>"</span>; </span>print</span> substr</span>($0</span>,</span> 3</span>); </span>print</span> "</blockquote>"</span>}</span></span></code></pre>
But as you have probably guessed, this simplification isn't quite what we want.
Instead of wrapping each line with a block quote tag, we want to wrap the entire
block (three lines in this case) with one set of tags. This will require us to
keep track of some intermediate state between line-reads:</p>
/^> /</span> {</span> if</span> (</span>!</span>inquote)</span> print</span> "<blockquote>"</span>; inquote </span>=</span> 1</span>; </span>print</span> substr</span>($0</span>,</span> 3</span>)</span> "}</span></span></code></pre>
If we match a blockquote character and we're not yet inquote</code>, we write the
opening tag and set inquote</code>. Otherwise, we simply write the content of the
line. We need an extra rule to write the closing tag:</p>
inquote </span>&& !/^> /</span> {</span> print</span> "</blockquote>"</span>; inquote </span>=</span> 0</span> }</span></span></code></pre>
If our program state says we're in a quote but we reach a line that doesn't lead
with a block quote character, it's time to close the block. This matches against
paragraph breaks which are normally used to separate paragraphs in Markdown
documents.</p>
This same strategy can be applied to the other block-style markdown elements:
code blocks and lists. Each requires its own variable to keep track of the block
content, but the approach is the same.</p>
Paragraphs are tricky</h2>
It is very tempting to implement inline paragraph elements in the same way as
we've handled other, single-line markdown syntax. However, paragraphs are
special in that they often span more than a single line, especially so if you
use hard-wrapping in your text editor at some column. For example, it's very
common for links to span multiple lines:</p>
A link that spans </span>[multiple lines]</span>(</span>https://definitely-a-valid-link-here.com</span>)</span></span></code></pre>
This breaks the nice, single-line worldview that we've been operating under,
requiring some special handling that will end up leaking into other aspects of
our rendering engine.</p>
My approach is to collect multiple paragraph lines into a single string,
rendering it altogether on paragraph breaks. This allows me to search the entire
string for inline elements (links, bold, italics), effectively matching against
multiple lines of input.</p>
/</span>.</span>/</span>  {</span> for</span> (i</span>=</span>1</span>; i</span><=</span>NF; i</span>++</span>) collect($i) }</span></span>
/^</span>$</span>/</span> { flushp() }</span></span>
</span>
# Concatenate our multi-line string</span></span>
function</span> collect</span>(</span>v</span>)</span> {</span></span>
  line </span>=</span> line sep v</span></span>
  sep </span>=</span> " "</span></span>
}</span></span>
</span>
# Flush the string, rendering any inline HTML elements</span></span>
function</span> flushp</span>()</span> {</span></span>
  if</span> (line) {</span></span>
    print</span> "<p>"</span> render(line)</span> "</p>"</span></span>
    line </span>=</span> sep </span>=</span> ""</span></span>
  }</span></span>
}</span></span></code></pre>
Each line of text is collected into a variable, line</code>, that is persisted
between line-reads. When a paragraph break is hit (a line that contains no text,
/^$/</code>) we render that line, wrapping it in paragraph tags and replacing any
inline elements with their respective HTML tags.</p>
I'll point out that the technique of collecting fields into a string or array is
a very common pattern in Awk, hence the utility variable NF</code> for "number of
fields". The Awk book</a> uses this pattern in quite a few
places.</p>
For completeness, here's what that render function looks like:</p>
function</span> render</span>(</span>line</span>)</span> {</span></span>
    if</span> (</span>match</span>(line</span>,</span> /</span>_(.</span>*</span>)_</span>/</span>)) {</span></span>
        gsub</span>(</span>/</span>_(.</span>*</span>)_</span>/</span>,</span> sprintf</span>(</span>"<em>%s</em>"</span>,</span> substr</span>(line</span>,</span> RSTART</span>+</span>1</span>,</span> RLENGTH</span>-</span>2</span>))</span>,</span> line)</span></span>
    }</span></span>
</span>
    if</span> (</span>match</span>(line</span>,</span> /</span>\</span>*</span>(.</span>*</span>)\</span>*/</span>)) {</span></span>
        gsub</span>(</span>/</span>\</span>*</span>(.</span>*</span>)\</span>*/</span>,</span> sprintf</span>(</span>"<strong>%s</strong>"</span>,</span> substr</span>(line</span>,</span> RSTART</span>+</span>1</span>,</span> RLENGTH</span>-</span>2</span>))</span>,</span> line)</span></span>
    }</span></span>
</span>
    if</span> (</span>match</span>(line</span>,</span> /</span>\</span>[</span>.</span>+</span>\</span>]</span>\(.</span>+</span>\)</span>/</span>)) {</span></span>
        inner </span>=</span> substr</span>(line</span>,</span> RSTART</span>+</span>1</span>,</span> RLENGTH</span>-</span>2</span>)</span></span>
        split</span>(inner</span>,</span> spl</span>,</span> /</span>\</span>]</span>\(</span>/</span>)</span></span>
        gsub</span>(</span>/</span>\</span>[</span>.</span>+</span>\</span>]</span>\(.</span>+</span>\)</span>/</span>,</span> sprintf</span>(</span>"<a href=</span>\"</span>%s</span>\"</span>>%s</a>"</span>,</span> spl</span>[</span>2</span>]</span>,</span> spl</span>[</span>1</span>]</span>)</span>,</span> line)</span></span>
    }</span></span>
</span>
    return</span> line</span></span>
}</span></span></code></pre>
This code is noticeably less clean than our earlier HTML rendering, an
unfortunate consequence of handling multi-line paragraphs. I won't go into too
much detail here since there's a lot of Awk-specific regular expression matching
stuff going on, but the gist is a standard regexp-replace of the paragraph text
with HTML tags for matching elements.</p>
Another problem that we run into when collecting multiple lines into the line</code>
variable is accidentally collecting text from previous match rules. Awk's
expression syntax is like a switch statement that lacks a break: a line will
match as many expressions as it can before moving onto the next. That means that
all of our previous rules for headers, blockquotes, and so on are now also
included in our paragraph text. That's no good!</p>
# I match a header here:</span></span>
/^</span># /  { print "<h1>" substr($0, 3) "</h1>" }</span></span>
</span>
# But I also match "any text" here, so I'm collected:</span></span>
/</span>.</span>/</span>  {</span> for</span> (i</span>=</span>1</span>; i</span><=</span>NF; i</span>++</span>) collect($i) }</span></span></code></pre>
Each of our previous matchers now has to include a call to next</code> to immediately
stop processing and move on to the next line. This prevents them from being
included in paragraph collection.</p>
/^</span># /  { print "<h1>" substr($0, 3) "</h1>"; next }</span></span>
/^</span>## / { print "<h2>" substr($0, 4) "</h2>"; next }</span></span>
# ...</span></span></code></pre>Styling for HTML exports</h2>
The last piece of this Markdown renderer is adding the boilerplate HTML that
wraps our document:</p>
BEGIN</span> {</span></span>
    print</span> "<!doctype html><html>"</span></span>
    print</span> "<head>"</span></span>
    print</span> "  <meta charset=</span>\"</span>utf-8</span>\"</span>>"</span></span>
    print</span> "  <meta name=</span>\"</span>viewport</span>\"</span> content=</span>\"</span>width=device-width, initial-scale=1</span>\"</span>>"</span></span>
    if</span> (head)</span> print</span> head</span></span>
    print</span> "</head>"</span></span>
    print</span> "<body>"</span></span>
}</span></span>
</span>
# ... all of our rules go here</span></span>
</span>
END</span> {</span></span>
    print</span> "</body>"</span></span>
    print</span> "</html>"</span></span>
}</span></span></code></pre>
Unlike other Awk matchers, the special BEGIN</code> and END</code> keywords are only
executed once.</p>
As a nice bonus, we can add an optional head</code> variable to inject a stylesheet
into our rendered markdown, which can be added via the Awk CLI. The following
adds the Simple CSS</a> stylesheet to our rendered output:</p>
awk -v head='  &lt;link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css"&gt;' \</span></span>
    -f awkdown.awk README.md > docs/index.html</span></span></code></pre>
The full source code is available here: https://github.com/mgmarlow/awkdown</a>.</p>


DM Tools with Awk
2024-02-27T00:00:00+00:00
I picked up Awk on a whim and am blown away by how generally useful it is. What
I thought was a quick and dirty tool for parsing tabulated files turns out to be
a fully-featured scripting language.</p>
Before I started reading the second edition of
The Awk Programming Language</a>, my only exposure to Awk was
from better-minded folk on Stack Overflow. After copy-pasting a short script
here or there, I was befuddled by the need for explicit BEGIN</code> and END</code>
statements in Awk one-liners. Shouldn't a program know when it begins and ends?
Why the redundancy?</p>
Oh how wrong I was. Once you understand how Awk works, the syntax of BEGIN</code> and
END</code> makes a ton of sense; it's actually a consequence of Awk's coolest
feature. BEGIN</code> and END</code> are necessary because the default mode of an Awk
script isn't top-to-bottom execution, like other scripting languages. Instead,
Awk programs are executed repeatedly by default, either on the lines of a file
or an input stream.</p>
To demonstrate, say I have a file where each line contains a location:</p>
Forest</span></span>
Hills</span></span>
Desert</span></span>
...</span></span></code></pre>
I can use Awk to turn that list of locations into one that is numbered with a
single statement, no loops required:</p>
$ awk '{ print NR ". " $0 }' locations.txt</span></span>
1. Forest</span></span>
2. Hills</span></span>
3. Desert</span></span>
4. ...</span></span></code></pre>
Without the BEGIN</code> or END</code> markers (which denote "run this before" and "run
this after"), Awk runs statements on every line of its input. In this case, that
means re-printing each location in the file locations.txt</code> with some minor
modifications.</p>
Awk provides a bunch of built-ins that make it easy to work within this
execution model. NR</code> refers to "num row", keeping track of the current line of
input that is being processed. This generates our numbered list.</p>
The dollar-sign variables refer to fields on an individual line. $0</code> is the
entire line, unmodified. $1</code>, $2</code>, and so on refer to subsets of the line,
broken up by a delimiter (e.g. space, tab, or comma) and read from left to
right.</p>
And statements are just the tip of the Awk iceberg! You can assign each
statement a "matcher" that only runs the expression on lines that are truthy.
Here are a few examples:</p>
# Print every row but the first</span></span>
NR</span> !=</span> 1</span> {</span> print</span> $0 }</span></span>
</span>
# Only print a row if the first field matches "cat"</span></span>
$1</span> ~ /</span>cat</span>/</span> {</span> print</span> "not a dog"</span> }</span></span>
</span>
# Maybe your second field is a number?</span></span>
$2</span> >=</span> 12</span> &&</span> $2</span> <</span> 18</span> {</span> print</span> "teenager"</span> }</span></span></code></pre>
Now the BEGIN</code> and END</code> statements are starting to make more sense.</p>
DMing with Awk</h2>
Now for something a little more complicated. As I mentioned before, Awk is a
fully-featured scripting language. You can write functions, generate random
numbers, build arrays, and do everything that you'd expect a normal language to
do (mostly, anyway). I ran across an example in the Awk book that demonstrates
the use of rand()</code> via dice rolling and it sparked an idea: how useful can a
tool like Awk be for a DM running a Dungeons and Dragons game?</p>
Since Awk is great at reading files, I figured it would also be great for
dealing with random tables. Given the locations file that appears earlier in
this post, here's how you can select a single location at random:</p>
awk</span> '{data[NR] = $0} END {srand(); print data[int(rand()*length(data))]}' locations.txt</span></span></code></pre>
It's easier to read with some annotations:</p>
# Add every line in the file to an array, indexed by the line number</span></span>
{ data</span>[</span>NR</span>] =</span> $0 }</span></span>
</span>
# After reading the file,</span></span>
END</span> {</span></span>
  # Seed randomness</span></span>
  srand</span>()</span></span>
</span>
  # Pick a random index from the data array and print its respective value</span></span>
  print</span> data</span>[</span>int</span>(</span>rand</span>()</span> *</span> length</span>(data))</span>]</span></span>
}</span></span></code></pre>
I really like how { data[NR] = $0 }</code> is all that Awk needs to build an array
with the contents of a file. It comes in handy in cases like this where we need
the file contents in memory before we can do something useful.</p>
Now, you might be thinking that this isn't that cool because sort</code> can already
do it better. And you'd be right!</p>
$</span> cat locations.txt</span> |</span> sort</span> -R</span> |</span> head</span> -1</span></span>
Plains</span></span></code></pre>
So how about moving on to the next step instead: character generation. The next
script implements the charater creation rules from
Knave</a>, a game based on old-school
Dungeons and Dragons.</p>
The first thing we need to do is generate some attribute scores. Each score can
be simulated by rolling three 6-sided dice (d6) and taking the lowest result.</p>
BEGIN</span> {</span></span>
    srand</span>()</span></span>
</span>
    map</span>[</span>1</span>] =</span> "str"</span></span>
    map</span>[</span>2</span>] =</span> "dex"</span></span>
    map</span>[</span>3</span>] =</span> "con"</span></span>
    map</span>[</span>4</span>] =</span> "int"</span></span>
    map</span>[</span>5</span>] =</span> "wis"</span></span>
    map</span>[</span>6</span>] =</span> "cha"</span></span>
</span>
    print</span> "hp "</span> roll(</span>8</span>)</span></span>
    for</span> (i </span>=</span> 1</span>; i </span><=</span> 6</span>; i</span>++</span>) {</span></span>
        print</span> map</span>[</span>i</span>]</span> " "</span> lowest_3d6()</span></span>
    }</span></span>
}</span></span>
</span>
function</span> roll</span>(</span>n</span>)</span> {</span></span>
    return</span> int</span>(</span>rand</span>()</span> *</span> n)</span> +</span> 1</span></span>
}</span></span>
</span>
function</span> lowest_3d6</span>(</span>_i</span>, </span>_tmp</span>)</span> {</span></span>
    min </span>=</span> roll(</span>6</span>)</span></span>
    for</span> (_i </span>=</span> 1</span>; _i </span><=</span> 2</span>; _i</span>++</span>) {</span></span>
        _tmp </span>=</span> roll(</span>6</span>)</span></span>
        if</span> (_tmp </span><</span> min) {</span></span>
            min </span>=</span> _tmp</span></span>
        }</span></span>
    }</span></span>
    return</span> min</span></span>
}</span></span></code></pre>
The output looks like:</p>
$ awk -f knave.awk</span></span>
hp 6</span></span>
str 1</span></span>
dex 2</span></span>
con 2</span></span>
int 1</span></span>
wis 1</span></span>
cha 4</span></span></code></pre>
Since this Awk program is not reading from a file (yet), everything is run in a
BEGIN</code> block. This allows us to execute Awk without passing in a file or input
stream. Within that BEGIN</code> block we build a map of integers to attribute names,
making it easy to loop over them to roll for scores. Arrays in Awk are
association lists, so they work well for this use-case.</p>
The strange thing about this code is the use of parameters as local variables in
the function lowest_3d6</code>. The only way in Awk to make a variable local is to
provide it to the parameter list when declaring a function, as all other
variables are global. Idiomatic Awk attempts to reveal this strangeness by
adding an underscore to the parameter names, as I have done, or by inserting a
bunch of spaces before their place in the function definition.</p>
Next up is to make these characters more interesting by assigning them careers
and starting items. A career describes the character's origin, explaining their
initial loot as fitting to their backstory. These careers are taken from Knave
second edition.</p>
First, a new data file:</p>
acolyte: candlestick, censer, incense</span></span>
jailer: padlock, 10’ chain, wine jug</span></span>
acrobat: flash powder, balls, lamp oil</span></span>
jester: scepter, donkey head, motley</span></span>
actor: wig, makeup, costume</span></span>
jeweler: pliers, loupe, tweezers</span></span>
...</span></span></code></pre>
Now that our Awk program is reading lines from a file, we can add a new block
that stores careers into an array so we can make a random selection for the
player.</p>
# ...snip</span></span>
</span>
{ careers</span>[</span>NR</span>] =</span> $0 }</span></span>
</span>
END</span> {</span></span>
    print</span> "</span>\n</span>Career & items:"</span></span>
    print</span> careers</span>[</span>roll(</span>100</span>)</span>]</span>;</span></span>
}</span></span></code></pre>
When the program is executed with the list of careers, the output looks like
this:</p>
$ awk -f knave.awk careers.txt</span></span>
hp 3</span></span>
str 1</span></span>
dex 3</span></span>
con 3</span></span>
int 2</span></span>
wis 3</span></span>
cha 4</span></span>
</span>
Career & items:</span></span>
falconer: bird cage, gloves, whistle</span></span></code></pre>
Not bad!</p>
I doubt these tools will come in handy for your next DnD campaign, but I hope
that this post has inspired you to pick up Awk and give it a go on some
unconventional problems.</p>


A Few Months with Kagi
2024-02-06T00:00:00+00:00
I've subscribed to Kagi</a> for a few months now and wanted to
collect some of my feelings towards it, particularly addressing whether I think
it's worth paying $10/mo for a search engine. To summarize: yes, I do think Kagi
is worth the price. Kagi performs as good or better than the competition for the
majority of things I search (programming stuff and a healthy dose of Emacs) and
offers a few useful features that add to the experience. The fact that it
performs so well without abusing my personal data is quite the achievement.</p>
The thing that got me into Kagi in the first place was their post about
Kagi Small Web</a>. It shouldn't really be
surprising that I am passionate about RSS and self-hosted blogs, you're reading
one. What Kagi is doing to help feature small blogs in their search results is
commendable. It clearly demonstrates the niche that Kagi is trying to carve out
as a search engine in a space owned by giants: the search experience provided by
Google is plagued with incentives that make the web worse and the problems of
such incentives are rooted in ads and SEO.</p>
Whether or not you're willing to pay for Kagi essentially boils down to whether
you think search is important enough to justify the bill, with a couple caveats.
The first caveat is considering what your personal data is worth to you. The
second is whether you think paying for a service subscription is a better
business model than paying with your eyeballs on a free service that serves ads.</p>
To help you figure out how Kagi performs, the rest of this post provides some of
my takeaways for day-to-day features. To put things into perspective, I average
about 1k searches a month and use Kagi across all of my devices: home pc, work
pc, and phone.</p>
Search results</h2>
Let's start with the search results. The vast majority of my searches are
programming-related, either APIs in programming languages, APIs in third-party
libraries, or documentation resources and higher-level ideas. In each of these
categories I find Kagi provides really excellent results, particularly when
compared to my previous search engine, DuckDuckGo (DDG).</p>
My DDG use can be summarized by one symbol: !g</code>. I had to constantly redirect
my searches to Google to get good results on the first page. DDG works fine for
general searches ("what's this word?", "who's in this movie?") but I had a
really hard time using it when doing anything technical. With Kagi, I basically
never use !g</code>.</p>
It's hard to judge "quality of search" without exhaustively comparing results
for certain queries across different search engines, which I am not going to do.
Generally speaking, I'm impressed by Kagi's highest-priority search results.
There seem to be fewer blog-spam articles from sites like Medium or dev.to
(which you can further exclude, see:
personalized results</a>)
and more self-hosted blogs, Stack Overflow posts, and Github discussions/issues.
I am often surprised by the quality of Github content in Kagi, as many of my
queries have been answered by a comment in a Github discussion or an issue that
is near the top of the results page.</p>
By far my favorite aspect of Kagi search results is the prevalence of source
code links. For example, searching "blank? rails" turns up this link to
the Github source</a>
as the third result.</p>
These source code links are so insanely useful. Normally I'd have to (a) search
the library (b) go to the library website (c) try to find the Github link (d)
use Github search to find the relevant file. Kagi bakes all of those steps into
one. I often use Kagi to search for a file that I know exists in some Github
repository, like "autorun minitest" and follow the Kagi result rather than going
to Github and using its navigation features.</p>
Personalized results</h2>
I mentioned this in the previous section, but you can "raise", "lower", or
"block" certain domains to affect their results in your search output. It's not
totally clear to me how significant this setting is, but I use it to prioritize
gnu.org</code> documentation for Emacs searches and lower Medium or dev.to</code> results
to avoid blogspam. I have noticed that lowered results often sit at the bottom
of the page, so if you're a fan of not seeing any Medium articles or Quora
questions in your top-most results it's a very nice feature.</p>
Kagi also hosts a public leaderboard</a>
that shows you how other people use this tool.</p>
Lenses</h2>
Lenses are a Kagi feature that I thought I would never use, but given the right
application they're actually pretty helpful. A lens effectively limits search
results to a particular domain. For example, a Hacker News lens would restrict
results to sites with https://news.ycombinator.com</a>.</p>
I actually use that Hacker News lens frequently to track down articles that I
remember seeing, but don't exactly remember the author or title. I can provide
some vague search terms about the content in the article, filter by my Hacker
News lens, and quickly look through a bunch of submissions that fit the
criteria. I find that the Kagi lens performs better for this specific use-case
than the Hacker News search on the website.</p>
Things kagi does not get right</h2>
Image results are good for the first few columns, but very quickly devolve into
complete nonsense. It's actually hilarious how off-the-rails image searches can
get with Kagi. I've shared my results with friends quite a few times because the
results were so outlandish when compared to the search term that it made for
good comedy. This has improved significantly with a
recent update</a>
but I still go to another source when searching images.</p>
The universal summarizer</a> is a
neat idea but is untrustworthy in very subtle ways. I primarily use it when
summarizing Wikipedia articles with the shorthand flow: first search Wikipedia
("!w dynamic programming"), then summarize the link ("!sum
https://en.wikipedia.org/wiki/Dynamic_programming"). Like all LLMs, the
summarizer sounds authoritative but frequently fabricates ideas or misrepresents
certain pieces of information. Perhaps this is less of a critique of Kagi and
more of LLMs in general, but I have barely touched this feature as a result.</p>
Uptime for Kagi has been generally good, but last month there was a
five-hour outage</a> that was
the source of much hand-wringing and consternation. If anything, this outage
demonstrated to me how much I prefer Kagi to other search engines. The
postmortem</a> is worth a
read.</p>
Should you use Kagi?</h2>
Yes, give it a go! Kagi outlines
why you might want to pay for search</a>
rather eloquently in its documentation. I echo the philosophical argument and
add that the product itself is compelling.</p>


My Year in Reading
2024-01-07T00:00:00+00:00
I read 24 books in 2023, a total of just over 8,000 pages. It was an uncommonly
productive year for me, not driven by any particular goal but rather a general
interest in a few choice authors and compelling works. Here are some of the
highlights.</p>
Murakami</h2>
I read four different books by Haruki Murakami this year, starting with What I
Talk About When I Talk About Running</em> and following up with Hard-Boiled
Wonderland and the End of the World</em>, Men Without Women</em>, and The Wind-up Bird
Chronicle</em>.</p>
This Murakami binge all started from a friend's recommendation. Before 2023 I
was totally unacquainted with Murakami's work, although nowadays I the
ever-growing Murakami section in my local bookstore has me wondering how I
missed it. Beginning with a memoir (What I Talk About</em>) is perhaps a strange
way to meet a new author, offering insights into the mind behind books that I've
not yet encountered. At least with Murakami's memoir the subject stays focused
on his running and life philosophy, it doesn't delve far into the subject matter
of his stories.</p>
Something about the tone of What I Talk About</em> caught me right away: a
relatively simple form of prose packed with emotion and relatability. This
feeling translates into all of Muarakami's writing and is probably the core
reason I find his work so engaging. I struggle to put into words my reasons for
recommending his work to others, other than I think people should try it and
find for themselves whether it holds any meaning in their lives.</p>
Hard-Boiled Wonderland</em> strikes me as one of his tighter novels, at least in
terms of a plot through-line and characters that grow together with the
protagonist. It's an interesting take on a dual narrative, two parallel worlds
representing the "Hard Boiled" detective side and the "End of the World" dream
side. Although I didn't care much for the characters themselves, the themes and
existential explorations were fun to explore.</p>
Men Without Women</em> is a short story collection that I purposefully read before
watching the movie Drive My Car</em>, which itself is based on several of the
stories in the book. The stories are interesting, engaging, and dreamy. Unlike a
full-length novel, a short story doesn't need to work double-time to justify the
existence and evolution of its characters. The constraints of a short story work
in concert with Muarakami's style and I think offer a more enjoyable reading
experience. This is probably the best place to start for new Murakami readers.</p>
The final Murakami novel that I read was The Wind-up Bird Chronicle</em>, which I
had described to me as his magnum opus. Although I finished it more than two
months ago I am still trying to sort out my feelings towards it. It has stuck in
the back of my mind in a way that few novels ever have, and I find myself
dwelling on certain scenes and characters to connect their meaning to events in
my own life. It's a bizarre book that I can't necessarily recommend, even though
I find it endlessly fascinating.</p>
Doom</h2>
John Romero released an autobiography this year, Doom Guy: Life in First
Person</em>, which despite its title (I mean, come on, really?) manages to be an
engaging glimpse into his life and one of the most important periods in video
game history.</p>
There are now two books (that I know of) covering the saga of id Software:
Masters of Doom</em>, probably one of the most famous books written about video
games, and Romero's autobiography. I would not recommend Romero's Doom Guy</em>
over Masters of Doom</em>, as the latter does a much better job developing the
behind-the-scenes drama and pacing itself as a proper story. However, Doom Guy</em>
is still a worthy read for Doom-heads like me, as it provides lots of additional
insight into Romero's evolution as a game designer.</p>
Doom is still going strong, 2023 marking its 30 year anniversary. Following
Doom Guy</em> I went down a pretty deep modding rabbit hole, exploring some of the
incredible stuff that people are making for this game.
MyHouse.wad</a> in
particular is an astounding achievement that is worth checking out, at the very
least in Youtube form</a>. Romero
himself is still churning out new levels in the form of
Sigil</a>.</p>
The Left Hand of Darkness</h2>
Ursula K. Le Guin is quickly becoming one of my favorite Sci-fi authors. Last
year The Dispossessed</em> gripped me with its prose, use of metaphor, and
occasional Taoist reference; I wrote a little bit about my reading experience
[here]({{
'/words/2022-08-13-reading-the-dispossessed.md' | url }}). The Left Hand of
Darkness</em> is a very different story that encompasses many of the things I
enjoyed about The Dispossessed</em>, but also delivers such complexity in its alien
culture that it's unbelievable to me that it's only 400 pages. The
world-building is so sincere and empathetic it's hard to believe that Le Guin
didn't travel to these planets and interview her characters personally.</p>
While writing this post I've also finished Under the Lathe of Heaven</em>, which to
me reads more like Philip K. Dick than Le Guin. The reason I bring up this point
is to contrast The Left Hand of Darkness</em>, which I think delivers a style so
personal and unique to Le Guin that I can't help believing it will be my
favorite work of hers for a long time.</p>
I can't say enough good things about this book!</p>
Lisping</h2>
The percentage of non-fiction that I read is much smaller than fiction, both
because I think fiction is more important to read from a learning and
development standpoint (a view that I think differs from the norm) and because
fiction is more interesting. When I read non-fiction it's almost always a book
about programming, something directly related to my career and skill
development.</p>
Readers of this blog may have guessed, and I confirm, that my Emacs obsession
has likewise hijacked my non-fiction life. Emacs, it seems, is the gateway drug
to an obsession with parentheses, one that inevitably leads down the Common Lisp
rabbit hole, into a place where programmers are trapped in the 80s but at least
have lots of free and venerable literature to choose from.</p>
One of such books is Paul Graham's On Lisp</em>, a Common Lisp book that focuses on
bottom-up programming and the power of macros. It's the first Common Lisp book
that I've worked through that isn't exclusively about the language (like
Practical Common Lisp</em>, also excellent) but factors in higher-level ideas. On
Lisp</em> is widely regarded as the "macro explainer" because it does an excellent
job demonstrating the power of Lisp macros during the early periods of
application architecture. I can likewise agree that On Lisp</em> has given me a
greater appreciation for macros and metaprogramming, as well as a great respect
for the parentheses that rule Lisp-like languages.</p>


How to Install React
2023-11-17T00:00:00+00:00
Tsoding's recent stream about React</a> is a
hilarious reminder of the complications of web development tooling and the lack
of support for beginners who want to take a bottom-up approach to learning.</p>
What I found most surprising about his foray into React is actually the React
documentation itself. It fails to provide any detail into setting up a React
build environment yourself, instead recommending frameworks and tools that hide
away the build mechanisms such that they're entirely opaque to the developer.
For those who want to learn how things work from start to finish there's not
much path forward, and it is all too easy to stumble onto old tools and
processes that have been left to decompose after their fifteen minutes of fame.</p>
For example, the documentation for
Start a New React Project</a>
points developers towards Next.js or Remix, frameworks that I view as highly
specialized and SSR-first. I can't believe that this is an acceptable starting
point for a complete beginner, not only is React super complicated in and of
itself, but to have to learn the abstractions of a meta-framework on top of
that? Sounds like a nightmare! The
Remix documentation</a> alone offers a staggering
number of APIs. Where does React end and the framework begin? How is a beginner
supposed to know the difference?</p>
It's also rather humorous how far React has moved away from its original goal of
being
"A JavaScript library for building user interfaces."</a>.
I know SSR is the bee's knees these days but I don't think it should be
emphasized over the fundamental build processes that make the whole thing work.</p>
In the days of yore, create-react-app</a> was
closer to this vision: run this CLI and bootstrap a React project that is just a
regular React single page application. Nowadays Vite</a> has
effectively superseded this project, and its omission in the React documentation
is surprising. Regardless, both of these projects still hide the details of the
React build process behind a velvet curtain.</p>
I do think it's important for beginners to familiarize themselves with some of
the fundamental tools that drive their favorite frameworks. The new kids on the
block like esbuild</a> are super approachable and
don't involve setting up convoluted Webpack configs or plugin pipelines. The
rest of this post will demonstrate setting up a new React project with esbuild.</p>
Why esbuild?</h2>
Why do we even need a build system in the first place? The answer is explained
in more detail in the next section, but the primary reason is to support
React's JSX syntax</a>. Browsers
don't know what JSX is, so we convert it to JavaScript beforehand.</p>
Before esbuild, most developers were transforming JSX via the
Babel JSX transform plugin</a>
together with a Webpack configuration that handled templating, static files, and
other optimizations. Now you could go and install Babel manually, like Tsoding
did in his stream, and use that instead for your new React project. However,
Babel is both more complicated and slower than esbuild, so I don't think it's a
good entrypoint for beginners.</p>
The esbuild compiler source code</a> is also a
great read.</p>
How to actually install React</h2>
Start by initializing a new npm project:</p>
mkdir</span> react-hello-world</span></span>
cd</span> react-hello-world</span></span>
npm</span> init -y</span></span></code></pre>
Then add your dependencies, React</a>,
ReactDOM</a>, and
esbuild</a>.</p>

Why are react</code> and react-dom</code> different packages? I can only guess at the
intentions of the React core team, but my assumption is react-dom and react
are separate packages to enable some of the non-browser React targets, like
React Native. By shipping them in two packages, you can keep using react</code> for
your application's component/UI code, and easily swap in the
react-dom</code>/react-native</code> entrypoints depending on whether you're building a
web or mobile application. Since we're working with React in a browser, we'll
need ReactDOM to configure the library to the DOM.</p>
</blockquote>
npm</span> install react react-dom --save</span></span>
npm</span> install esbuild --save-dev</span></span></code></pre>
We use --save</code> on React and ReactDOM because they're application dependencies,
things that our application runtime actually depends on. We use --save-dev</code> for
esbuild since it's a development dependency, it's only needed to compile our
application. This is a bit of a pointless distinction at this point, since we're
going to compile our application into a static JS file anyway, but hey, best
practice.</p>
There are two pieces of boilerplate that we need to fill in next, the
index.html</code> webpage where our JavaScript is loaded, and index.jsx</code> which
contains the contents and initialization of our React application.</p>
First index.jsx</code>:</p>
import</span> {</span> createRoot</span> }</span> from</span> 'react-dom/client'</span></span>
</span>
const</span> App</span> =</span> ()</span> =></span> {</span></span>
  return</span> <</span>h1</span>></span>hello react</span></</span>h1</span>></span></span>
}</span></span>
</span>
const</span> root</span> =</span> createRoot</span>(document</span>.</span>getElementById</span>(</span>'app'</span>))</span></span>
root</span>.</span>render</span>(</span><</span>App</span> /></span>)</span></span></code></pre>
And then index.html</code>:</p>
<!doctype</span> html</span>></span></span>
<</span>html</span> lang</span>=</span>"en"</span>></span></span>
  <</span>head</span>></span></span>
    <</span>meta</span> charset</span>=</span>"UTF-8"</span> /></span></span>
    <</span>meta</span> name</span>=</span>"viewport"</span> content</span>=</span>"width=device-width, initial-scale=1.0"</span> /></span></span>
    <</span>meta</span> http-equiv</span>=</span>"X-UA-Compatible"</span> content</span>=</span>"ie=edge"</span> /></span></span>
    <</span>title</span>></span>Hello, React</span></</span>title</span>></span></span>
  </</span>head</span>></span></span>
  <</span>body</span>></span></span>
    <</span>div</span> id</span>=</span>"app"</span>></</span>div</span>></span></span>
    <</span>script</span> src</span>=</span>"./out.js"</span>></span><</span>/</span>script</span>></span></span>
  </</span>body</span>></span></span>
</</span>html</span>></span></span></code></pre>
The important bit to note here is that the script tag in index.html</code> is
pointing to a file that is yet to exist: out.js</code>. Normally JS doesn't require a
build step (although when shipping to production it is a good idea for asset
minification, among other reasons), but React is a special case because of the
JSX syntax. JSX is not part of the ECMAScript specification and is therefore not
known to the browser, so we have to add support for it by compiling our JSX code
into plain old JS (hence esbuild).</p>
In versions of React before the automatic runtime (which I'll get into in a
second), JSX compilation looked something like the following.</p>
This JSX:</p>
// original.jsx</span></span>
import</span> React</span> from</span> 'react'</span></span>
</span>
function</span> App</span>() {</span></span>
  return</span> <</span>h1</span>></span>Hello World</span></</span>h1</span>></span></span>
}</span></span></code></pre>
Is compiled to this JS:</p>
// compiled.js</span></span>
import</span> React</span> from</span> 'react'</span></span>
</span>
function</span> App</span>() {</span></span>
  return</span> React</span>.</span>createElement</span>(</span>'h1'</span>,</span> null</span>,</span> 'Hello world'</span>)</span></span>
}</span></span></code></pre>
In fact, you could write your entire app using the React.createElement</code> API and
avoid the compilation step (although in practice JSX is really why you're here
anyway).</p>
Nowadays the compilation situation is a little more complicated. Programmers
found that repeating the import React from "react";</code> line at the top of every
JSX file was onerous, so the ecosystem grew to support a JSX syntax that doesn't
require it. This is known as
the automatic JSX runtime</a>.</p>
Modern JSX is written without the import statement, like so:</p>
// original.jsx</span></span>
function</span> App</span>() {</span></span>
  return</span> <</span>h1</span>></span>Hello World</span></</span>h1</span>></span></span>
}</span></span></code></pre>
And the compiled JS output is likewise changed to support this new syntax:</p>
// compiled.js</span></span>
import</span> {</span> jsx</span> as</span> _jsx</span> }</span> from</span> 'react/jsx-runtime'</span></span>
</span>
function</span> App</span>() {</span></span>
  return</span> _jsx</span>(</span>'h1'</span>, {</span> children</span>:</span> 'Hello world'</span> }</span>)</span></span>
}</span></span></code></pre>
The react/jsx-runtime</code> is now imported as the responsibility of the compiler,
not the programmer.</p>
All this to say that we'll need to enable the automatic JSX runtime when we
compile our index.jsx</code> script into out.js</code>. Luckily esbuild supports this out
of the box.</p>
Add the following build script to your package.json</code>:</p>
"scripts"</span>: </span>{</span></span>
  "</span>build</span>":</span> "esbuild index.jsx --jsx=automatic --bundle --outfile=out.js"</span></span>
}</span></span></code></pre>
The other point of note is the --bundle</code> flag which inlines all of the
dependencies needed for the application during the build. For our application,
that means esbuild will insert React and ReactDOM from their respective
node_modules/</code> into out.js</code> during the build. out.js</code> is referred to as a
"bundle" (hence --bundle</code>) because it now contains our application and all of
its dependencies.</p>
npm</span> run build</span></span></code></pre>
After running the build, you can open up index.html</code> in your browser and see
your new React app in all of its glory.</p>
What should new developers actually use when starting new projects?</h2>
Look, meta-frameworks like Next.js and Remix are rad. They bake in a ton of best
practices and make it easy to deliver very complicated web applications while
avoiding the pitfalls of a single page application. That said, I don't think
they're a good place for a beginner to start.</p>
Instead, poke around with the different build tools that underly these
frameworks and learn how those megabytes of JS are actually delivered to your
end users. Focus on learning the principles of React alone, and not the
meta-framework glue that gives so many fancy features beneath layered
abstractions.</p>


Hypermedia and Hyperbole
2023-10-26T00:00:00+00:00
My partner and I are slowly working our way through the Myst series and have
finally started Myst 3: Exile. We were both surprised by how much of a departure
this entry is to the previous Myst games. The biggest change isn't so much the
game itself as it is the implementation of freelook: the ability to look around
a scene like it's a three-dimensional room. If this doesn't sound like a big
achievement believe me, it is. The first two games are glorified powerpoint
slides in comparison.</p>
Original Myst (not talking about the remakes) was effectively a deck of static
images with some clickable areas on top. Clicking on one of these areas could
advance you to the next scene (i.e. movement) or jiggle an object so as to
trigger an animation and play some sound effects. While the core gameplay and
presentation is incredibly simple, it doesn't detract too much from the
compelling setting and (mostly) interesting puzzles.</p>
I was fascinated to learn that the control mechanisms for Myst 1 and 2 root back
to early Cyan, before Myst was a thing. Rand and his brother Robyn made
games for the Apple Macintosh</a>
with a piece of software called
HyperCard</a>, an application for
building GUIs based on the principles of hypermedia.</p>
All programs built in HyperCard consist of just two components: cards that store
data and links that navigate between those cards or execute scripts. It's a
simple system that offers a lot of flexibility; even today I think it would make
an awesome prototyping tool. It also seems no coincidence that the scripting
language is named HyperTalk, as the whole environment reminds me of
Smalltalk</a>.</p>
All of the concepts of HyperCard (and the awesome late-80s nerd aesthetic) are
well-explained in this interview with the creator, Bill Atkinson, and an
enthusiast, Danny Goodman:</p>
</iframe>
If that video piqued your interest,
The Complete HyperCard Handbook</em></a>,
written by Danny Goodman in the video, is available to read online.</p>
It always amazes me what creative people can create using simple tools.
HyperCard and the early days of Cyan are no exception; it seems like the duo
were able to find a lot of success by excelling within the constraints of their
software.</p>
Hypermedia systems are super interesting to me, particularly with the renewed
interest in tools like htmx</a> that promise to bring the
hypermedia ethos</a> back to the web. That said, this
post isn't going to talk about how htmx is fighting against the SPA-explosion
that the web industry has experienced over the past decade. Instead, I'd like to
take a look at a far more esoteric hypermedia system:
GNU Hyperbole</a>.</p>
I stumbled on this Emacs package recently and I had this overwhelming sense of
deja vu due to its similarities to HyperCard. It was originally created in the
90s and retains an identity true to that era through some of its naming
conventions (e.g. HyRolo, the rolodex extension). But more than that it is a
full hypermedia engine, just like HyperCard, that is scriptable with Emacs Lisp.</p>
The fact that Emacs contains an entire hypermedia system as an external package
is probably unsurprising given its reputation as an operating system, but do
people actually use it? The answer is yes, and rather extensively given the
amount of material about it on the internet. There were no less than three talks
about it during last year's EmacsConf:</p>

Linking personal info with Hyperbole implicit buttons</a></li>
Build a Zettelkasten with the Hyperbole Rolodex</a></li>
Powerful productivity with Hyperbole and Org Mode</a></li>
</ul>
All there are interesting glimpses into some of the functionality of Hyperbole,
but I found that Ramin Honary's
Building a Zettelkasten</a> did the
best job of answering the question of "why would anyone use this?"</p>
As the title suggests, Ramin's talk demonstrates a Zettelkasten built on
Hyperbole, using its built-in rolodex to store entries with scripted links
between them. That's right, I said rolodex. Hyperbole is from the 90s, remember?</p>
That said, a rolodex is probably not the best way to think about Hyperbole's
record-keeping implementation (named HyRolo). It's not so much about managing
contacts as it is managing record-oriented information. From that perspective it
feels like a natural fit for a Zettelkasten, which literally means "slip box" in
German.</p>
Linking to a zettel in Hyperbole might look something like this:</p>
<hyrolo-fgrep "Immanuel Kant"></span></span></code></pre>
In this case, the link reveals its implementation. It's a call to an Emacs Lisp
function that greps over all HyRolo records for the string matching "Immanuel
Kant".</p>
Of course, you don't actually need to have an ugly link like that in your zettel
text. Instead, you can create what's called an "explicit button" that hides the
actual linking function code in a separate file. With an explicit button your
zettel looks something like this:</p>
<(Immanuel Kant)></span></span></code></pre>
This link behaves in an identical fashion to the previous one, even though it
hides away the details of the Emacs Lisp function powering the search. What's
interesting is where it places those details. If you check your Hyperbole user
directory, you can see the source code of the new button in a special file:
_hypb</code>:</p>
("immanuel_kant" nil nil hyrolo-fgrep ("Immanuel Kant" nil) "me@my-pc" "20231025:04:20:37" nil nil)</span></span></code></pre>
It's just s-expressions all the way down!</p>
Hyperbole is difficult to explain because it's such an abstract concept. Sure we
can link between things, but what's the use? I think looking at the _hypb</code> file
and uncovering the Emacs Lisp engine underneath helps illustrate its
flexibility; it's more than a linking engine because you can make your links any
valid Emacs Lisp expression. Pretty cool.</p>
Now, I don't think anyone is likely to create an entire game with Hyperbole,
like Cyan did with HyperCard. Not because they couldn't per se, but asking
players to learn Emacs as a prerequisite feels a tad much. But if there's
anything to learn from the success of HyperCard, it's that simple interfaces
empower creative people to build interesting things and I think Hyperbole
exemplifies that same characteristic.</p>


Recently
2023-10-09T00:00:00+00:00

I'm taking a page from Tom MacWright's blog</a> and am
trying out a "Recently" series, where I summarize a few things on my mind
since my last post.</p>
</blockquote>
Recently I've been tinkering with
Crafted Emacs</a>, a modularized
Emacs starter kit. The project strongly invokes one of my favorite things about
the Emacs community: taking bits of insight from other configurations and
sprinkling them into your own. The modules from the framework are meant to be
extended or replaced, so they exemplify good Emacs Lisp style and are filled
smart ideas and thorough documentation.</p>
The project is undergoing a major overhaul with its
craftedv2RC1 branch</a>
but it's ready for general use (just don't forget to clone the right branch).
I've been using it for the past few weeks in a professional capacity and have
landed on a pretty lightweight configuration
(my config</a>). It's been a good
excuse to start experimenting with the new Emacs 29 Tree Sitter features, most
of which Crafted Emacs configures automatically.</p>
Tree Sitter is actually surprising complicated to set up even with all of the
work that's gone into Emacs 29. Grammars are shipped separately from the editor,
so you need to install each one from its respective git repository and compile
it before you can use it. Emacs provides a few commands to help this process but
there's still lots of holes in the experience.</p>
Thanks to Crafted Emacs I learned about
treesit-auto</a>, a library that strives
to make the Tree Sitter setup completely automatic. I imagine that as Tree
Sitter gains greater mindshare and major mode development lots of these issues
will be ironed out. Right now it feels a bit bleeding edge.</p>
I discovered Crafted Emacs through the
System Crafters</a> community, which by no
coincidence is also where I got started with Emacs a year or so ago. Lots of
friendly folks working on interesting things over there.</p>
Reading</h2>
I just finished up
The Wind-up Bird Chronicle</a></em>
and it's been lingering in my mind ever since. I really don't know how to
summarize my feelings about Murakami; I've read four of his books so far
(novels, short story collections, and his memoir) and yet I can't really say
whether I like his work. I suppose here I am reading and thinking about it, so
that must mean something.</p>
Murakami's work walks a line of allegory and emotional expression that is
surprising given the simplicity of the prose. The style of writing is just so
plain</em> that it can't help but be compelling in its emotional density. His
references to musical pieces, drinking beer, and reading books reminds me of my
dad.</p>
Side projects</h2>
Crafted Emacs has been the bulk of my open source contribution lately but I've
also been messing around with Fennel</a>, a Lisp that
compiles to Lua. The killer feature for me is programming games with
Love2D</a> and avoiding Lua altogether, since I don't care
much for the language. Bonus points since it's a Lisp and I've been on a Lisp
kick for the last two years.</p>
I don't have any big plans for the language other than to make a few games and
see what happens. Love2D is far and away my favorite game framework, having
worked with some alternatives like Raylib, HaxeFlixel, and Monogame. It's
well-documented and robust, yet remains simple and expressive. It also has an
extensive amount of community material and libraries that provide just about
everything you'd want in a 2D engine. Fortunately Fennel retains the ability to
use these libraries since it just compiles down to Lua.</p>
I discovered Fennel via Andrey Listopadov's blog</a>, where
he documents some of his past games and some other really
insightful posts</a>.</p>


Deno + Tree Sitter + Emacs
2023-08-31T00:00:00+00:00
I've been spending a bunch of time fiddling with Deno lately, mostly in the form
of small scripts and Fresh projects</a>. One thing that
hasn't impressed me doesn't have anything to do with Deno itself but rather the
tooling around it: setting up Deno with Emacs is a little cumbersome. The
problem roots to Deno and TypeScript sharing a file extension (.ts</code>). While
this doesn't cause issue for syntax highlighting (since it's the same for both
languages), it does cause issue when picking an appropriate language server.
Since Emacs generally uses file extensions to associate languages and
functionality it's a bit awkward to have Emacs pick the right LSP program.</p>
For individual projects you can use
Directory Variables</a>
to override Eglot settings just for that directory, telling Eglot that it
belongs to a Deno project and not a regular TypeScript project. This approach
gets old fast, I don't want to have to create a dir-locals.el</code> file just to get
my Deno tooling working.</p>
This lead me to hacking together some Deno project detection into my Emacs
configuration. Basically, if Emacs is in a project (that is, a
version-controlled folder) and finds a deno.json</code> file, Eglot will select the
Deno language server instead of the TypeScript language server. In all other
cases, it defaults to TypeScript.</p>
(</span>defun</span> deno-ts-project-p</span> ()</span></span>
  (</span>when-let*</span> ((</span>project </span>(</span>project-current</span>))</span></span>
              (</span>p-root </span>(</span>project-root project</span>)))</span></span>
    (</span>file-exists-p</span> (</span>concat</span> p-root </span>"deno.json"</span>))))</span></span>
</span>
(</span>defun</span> ts-server-program</span> (</span>&rest</span> _</span>)</span></span>
  (</span>cond</span> ((</span>deno-project-p</span>) '(</span>"deno" "lsp"</span> :</span>initializationOptions</span></span>
                                         (</span>:</span>enable t</span> :</span>lint t</span>)))</span></span>
         (</span>t</span> '(</span>"typescript-language-server" "--stdio"</span>))))</span></span>
</span>
(</span>add-to-list</span> '</span>eglot-server-programs</span> '(</span>web-mode </span>.</span> ts-server-program</span>))</span></span></code></pre>
This technique works great, provided you always version control your Deno
projects. Emacs 29 introduces a new variable that we can use to improve project
detection for Deno, relying solely on the presence of a deno.json</code> file:</p>
(</span>add-to-list</span> '</span>project-vc-extra-root-markers</span> "deno.json"</span>)</span></span></code></pre>
These changes got me thinking, why not create a major mode for Deno? That way
all of these configuration options could be shipped with the major mode and
Emacs would inform the user in their mode-line whether they're working in a
TypeScript project or a Deno project. Moreover, since we're already using Emacs
29 features, what if that major mode was built on tree-sitter? It's a great
excuse for finally trying that library out. And so I set out to build
deno-ts-mode</code>.</p>
Setting up tree-sitter requires a few extra steps. Firstly, you need
Emacs 29.1</a> (the most recent
release) installed. Secondly, you must compile
parsers</a> for each
language you want to use. For Deno, that means a TypeScript parser and a TSX
parser.</p>
Assuming cc</code> is available on your system, you can install both parsers with
this script:</p>
(</span>setq treesit-language-source-alist</span></span>
      '((</span>typescript </span>"https://github.com/tree-sitter/tree-sitter-typescript" "master" "typescript/src"</span>)</span></span>
        (</span>tsx </span>"https://github.com/tree-sitter/tree-sitter-typescript" "master" "tsx/src"</span>)))</span></span>
</span>
(</span>mapc</span> #'</span>treesit-install-language-grammar</span> (</span>mapcar</span> #'</span>car treesit-language-source-alist</span>))</span></span></code></pre>
The parsers are installed to your Emacs user directory as DLLs. You can test
that everything installed correctly by trying out typescript-ts-mode</code>.</p>
With tree-sitter good to go, let's create a new major mode for Deno that's based
on the TypeScript tree-sitter mode:</p>
(</span>define-derived-mode</span> deno-ts-mode</span></span>
  typescript-ts-mode </span>"Deno"</span></span>
  "Major mode for Deno."</span></span>
  :</span>group</span> '</span>deno-ts-mode</span>)</span></span></code></pre>
At this stage, deno-ts-mode</code> is near identical to typescript-ts-mode</code>. The
only difference is that Deno shows up in your mode-line when deno-ts-mode</code> is
activated, all syntax highlighting is inherited from typescript-ts-mode</code>.</p>
The next step is to figure out whether a visited .ts</code> file should use our new
Deno mode or the TypeScript mode. For this we can use our earlier function,
deno-project-p</code>, and apply it to auto-mode-alist</code>, the association list
mapping file extensions to major modes. Since auto-mode-alist</code> accepts a
function, we can create a couple of wrappers around the two major modes in
question to resolve based on the result of deno-project-p</code>:</p>
(</span>defun</span> deno-ts--ts-auto-mode</span> ()</span></span>
  (</span>cond</span> ((</span>deno-ts-project-p</span>) (</span>deno-ts-mode</span>))</span></span>
        (</span>t</span> (</span>typescript-ts-mode</span>))))</span></span>
</span>
(</span>defun</span> deno-ts--tsx-auto-mode</span> ()</span></span>
  (</span>cond</span> ((</span>deno-ts-project-p</span>) (</span>deno-ts-mode</span>))</span></span>
        (</span>t</span> (</span>tsx-ts-mode</span>))))</span></span>
</span>
(</span>add-to-list</span> '</span>auto-mode-alist</span> '(</span>"\\.ts\\'"</span> .</span> deno-ts--ts-auto-mode</span>))</span></span>
(</span>add-to-list</span> '</span>auto-mode-alist</span> '(</span>"\\.tsx\\'"</span> .</span> deno-ts--tsx-auto-mode</span>))</span></span></code></pre>
When visiting a .ts</code> or .tsx</code> file, Emacs will smartly select either
deno-ts-mode</code> or typescript-ts-mode</code> (or TSX) based on the presence of a
deno.json</code> file. Pretty great!</p>
This simplifies our Eglot setup considerably, since there's no need to check
deno-project-p</code>. The major mode has solved that already!</p>
(</span>use-package</span> eglot</span></span>
  :</span>ensure t</span></span>
  :</span>hook</span> ((</span>deno-ts-mode </span>.</span> eglot-ensure</span>))</span></span>
  :</span>config</span></span>
  (</span>add-to-list</span> '</span>eglot-server-programs</span></span>
               '(</span>deno-ts-mode </span>.</span> (</span>"deno" "lsp"</span> :</span>initializationOptions</span></span>
                                              (</span>:</span>enable t</span> :</span>lint t</span>)))))</span></span></code></pre>
These features plus a few more (task automation, accepting deno.json</code> and
deno.jsonc</code>) are all available in my package
deno-ts-mode</a>. Give it a try and let
me know what you think!</p>


Building a Compiler for My Static Site Generator
2023-07-26T00:00:00+00:00
My side project has exploded in scope. My original goal was to build a static
site generator to learn how they work, not to support lots of features. Yet here
I am building a compiler for my own template language.</p>
Before the compiler, I had a very simple model for handling templates focused
around variable replacement. That is, given some
mustache expression</a>, replace the requested
variable with one from the parent environment.</p>
;; An example from Orgify's test suite</span></span>
(</span>assert-compile-to-string</span></span>
  :</span>input</span>    "Hello, {{ name }}!"</span></span>
  :</span>expected</span> "Hello, world!"</span></span>
  :</span>env</span>      '((</span>name </span>.</span> "world"</span>))</span></span></code></pre>
Originally I had implemented these substitutions via search and replace,
something Emacs is adept at. It looked something like this:</p>
(</span>defun</span> parse-handlebars</span> (</span>handlebars</span>)</span></span>
  (</span>string-trim</span> (</span>substring</span> handlebars </span>2</span> (</span>-</span> (</span>length</span> handlebars</span>)</span> 2</span>))))</span></span>
</span>
(</span>defun</span> search-and-replace-handlebars</span> (</span>env</span>)</span></span>
  (</span>while</span> (</span>re-search-forward</span> "{{[ ]*[a-z]*[ ]*}}"</span> nil</span> t</span>)</span></span>
    (</span>let</span> ((</span>expr </span>(</span>save-match-data</span></span>
                  (</span>and</span> (</span>match-string</span> 0</span>)</span></span>
                       (</span>parse-handlebars </span>(</span>match-string</span> 0</span>))))))</span></span>
      (</span>unless</span> (</span>alist-get</span> expr env</span>)</span></span>
        (</span>error</span> (</span>concat</span> "Unrecognized variable: "</span> (</span>match-string</span> 0</span>))))</span></span>
      (</span>replace-match</span> (</span>alist-get</span> expr env</span>)))))</span></span></code></pre>
I was happy with this solution because it solved variable replacement in a super
simple, Emacs-y way. I soon learned, however, that this method is very difficult
to extend. It expects too many assumptions:</p>

The code operates within the context of a single buffer</li>
Expressions are not multi-line</li>
Expressions are always immediately replaced</li>
The content of an expression is always a value from an alist (association
list)</li>
</ul>
With this in mind, I ditched the prior code in favor of a more traditional,
compiler-driven approach. The new Orgify template language goes through the
usual tokenize, parse, and generate cycle. The result resembles
Handlebars</a>, but with the added ability to execute
Emacs Lisp expressions.</p>
;; You can include any Emacs Lisp code in mustache templates:</span></span>
(</span>assert-compile-to-string</span></span>
  :</span>input</span> "{{ (+ 1 41) }}"</span></span>
  :</span>expected</span> "42"</span>)</span></span></code></pre>
The rest of this post describes how the new compiler works.</p>
Building the compiler</h2>
Orgify's compiler has three phases: tokenization, parsing, and code generation
(although the last two steps are actually performed at the same time).</p>
Tokenization</h3>
The goal of tokenization is to make the text easier to parse by breaking it down
into smaller tokens that pick out language symbols. This step is surprisingly
crucial. The difference in a program's ability to understand a list of tokens
vs. raw text is night and day.</p>
My template language only cares about a few tokens:</p>

obrace</code>: opening handlebars expression</li>
cbrace</code>: closing handlebars expression</li>
oeach</code>: opening loop expression</li>
ceach</code>: closing loop expression</li>
text</code>: everything else, e.g. HTML or Emacs Lisp</li>
</ul>
The scope of each token is intentionally small. It's very easy to accidentally
blur the line between the job of the tokenizer and the job of the parser by
trying to capture tokens that contain too much information. This path leads only
to headaches.</p>
Finding these tokens in the original text still relies on regular expressions,
though the implementation is quite a bit different from the original approach.
Rather than using re-search-forward</code>, which operates on a buffer, I use
string-match</code>, which operates on a string. Additionally, I use an incrementing
index to ensure the regular expression is always matching against the beginning
of the current position in the string (important due to some quirks in Emacs
Lisp regular expression language).</p>
Altogether, tokenization looks like this:</p>
(</span>defun</span> tokenize</span> (</span>input</span>)</span></span>
  (</span>let</span> ((</span>tokens </span>'()) (</span>cur-text </span>""</span>) (</span>idx </span>0</span>))</span></span>
    ;; A helper function to append text tokens</span></span>
    (</span>cl-flet</span> ((</span>purge-text </span>()</span></span>
                (</span>when</span> (</span>></span> (</span>length</span> cur-text</span>)</span> 0</span>)</span></span>
                  (</span>push</span> (</span>list</span> '</span>text cur-text</span>)</span> tokens</span>)</span></span>
                  (</span>setq cur-text </span>""</span>))))</span></span>
      ;; Looping over the input string, one character at a time</span></span>
      (</span>while</span> (</span><</span> idx </span>(</span>length</span> input</span>))</span></span>
        ;; Need to use (eq ... idx) to ensure regex is matching from</span></span>
        ;; idx onwards (e.g. start of string only).</span></span>
        (</span>cond</span> ((</span>eq</span> (</span>string-match</span> "{{"</span> input idx</span>)</span> idx</span>)</span></span>
               (</span>purge-text</span>)</span></span>
               (</span>push</span> `(</span>obrace ,</span>(</span>match-string</span> 0</span> input</span>))</span> tokens</span>)</span></span>
               (</span>setq idx </span>(</span>1-</span> (</span>match-end</span> 0</span>))))</span></span>
              ((</span>eq</span> (</span>string-match</span> "}}"</span> input idx</span>)</span> idx</span>)</span></span>
               (</span>purge-text</span>)</span></span>
               (</span>push</span> `(</span>cbrace ,</span>(</span>match-string</span> 0</span> input</span>))</span> tokens</span>)</span></span>
               (</span>setq idx </span>(</span>1-</span> (</span>match-end</span> 0</span>))))</span></span>
              ;; ...snip</span></span>
</span>
              ;; For everything else, just append the character</span></span>
              ;; to cur-text.</span></span>
              (</span>t</span></span>
               (</span>setq cur-text </span>(</span>concat</span></span>
                                cur-text</span></span>
                                (</span>char-to-string</span> (</span>aref</span> input idx</span>))))))</span></span>
        (</span>cl-incf</span> idx</span>))</span></span>
      (</span>purge-text</span>))</span></span>
    (</span>reverse</span> tokens</span>)))</span></span>
</span></code></pre>
For every index in the string, decide whether the string starting at that index
matches one of the language tokens via regular expression. If it does, purge any
text that might be hanging around from previous iterations and push a new token
to the list. If it doesn't, append the current character to the growing string
of characters for the next text purge.</p>
It might be easier to visualize by looking at an example template:</p>
;; Template:</span></span>
;; <p>Hello {{ name }}!</p></span></span>
;;   <ul></span></span>
;;     #each page in pages</span></span>
;;       <li>{{ page }}</li></span></span>
;;     /each</span></span>
;; </ul></span></span>
</span>
;; Tokens:</span></span>
'((</span>text </span>"<p>Hello "</span>)</span></span>
  (</span>obrace </span>"{{"</span>)</span></span>
  (</span>text </span>"name"</span>)</span></span>
  (</span>cbrace </span>"}}"</span>)</span></span>
  (</span>text </span>"!</p></span>\</span>n</span>\</span>n<ul></span>\</span>n  "</span>)</span></span>
  (</span>text </span>"</span>\</span>n  <li></span>\</span>n    "</span>)</span></span>
  (</span>oeach </span>"#each page in pages"</span>)</span></span>
  (</span>obrace </span>"{{"</span>)</span></span>
  (</span>text </span>"page"</span>)</span></span>
  (</span>cbrace </span>"}}"</span>)</span></span>
  (</span>text </span>"</span>\</span>n  </li></span>\</span>n  "</span>)</span></span>
  (</span>ceach </span>"/each"</span>)</span></span>
  (</span>text </span>"</span>\</span>n</ul>"</span>))</span></span></code></pre>Parsing and code generation</h3>
The next step in compilation feeds these tokens to the parser. The parser runs
through the list of tokens and gives them structure, appending them as leaves
and branches to an abstract syntax tree (AST).</p>
(</span>defun</span> parse</span> (</span>tokens</span>)</span></span>
  (</span>let</span> ((</span>expressions </span>'()) (</span>cur </span>0</span>))</span></span>
    (</span>while</span> (</span><</span> cur </span>(</span>length</span> tokens</span>))</span></span>
      (</span>let</span> ((</span>token </span>(</span>nth</span> cur tokens</span>)))</span></span>
        (</span>cond</span> ((</span>eq</span> '</span>text</span> (</span>car</span> token</span>))</span></span>
               ;; Handle text...)</span></span>
              ((</span>eq</span> '</span>obrace</span> (</span>car</span> token</span>))</span></span>
               ;; Handle opening braces...)</span></span>
              ((</span>eq</span> '</span>cbrace</span> (</span>car</span> token</span>))</span></span>
               ;; Handle closing braces...)))</span></span>
      (</span>setq cur </span>(</span>1+</span> cur</span>)))</span></span>
    (</span>reverse</span> expressions</span>)))</span></span>
</span></code></pre>
The call to reverse</code> here might be unexpected, but it's a common Lisp-ism since
push</code> prepends items to the front of the list. Reversing expressions</code> ensures
the order of the tree matches the order of the original tokens.</p>
I commented out the implementation of each token branch because there are some
important prerequisite topics to cover: quoting and eval. These two tools are
crucial for this compiler, so it's worth explaining them with some extra detail.</p>
Quoting</h4>
There's a very interesting consequence of building an AST for this compiler in
Lisp. Because Lisp code is naturally structured as lists, the parser able to
directly generate a tree of Emacs Lisp code, rather than a tree of generic nodes
that need another layer of translation. This is accomplished through quoting, a
Lisp special form that returns an object without evaluating it.</p>
(</span>+</span> 1 2</span>)</span></span>
;; => 3</span></span>
</span>
'(</span>+</span> 1 2</span>)</span></span>
;; => (+ 1 2)</span></span></code></pre>
The ability to pend evaluation by quoting is incredibly useful for a compiler
that generates instructions. Every node in the AST generated by the parser is a
quoted Emacs expression. It satisfies not only the AST data structure, a tree
representing the program shape, but also the code that need be generated from
the source tokens.</p>
This aspect of code-as-data in Lisp is referred to as
homoiconicity</a>.</p>
Taking it one step further, the backtick character enables mixing quoting and
evaluation. This is how macros are generally written in Lisp.</p>
(</span>setq value </span>42</span>)</span></span>
</span>
`(</span>+</span> 5</span> value</span>)</span></span>
;; => (+ 5 value)</span></span>
</span>
`(</span>+</span> 5</span> ,</span>value</span>)</span></span>
;; => (+ 5 42)</span></span></code></pre>
Anywhere a comma falls is an expression that is evaluated. By mixing quoted
forms and evaluation, it's easy to construct complex snippets of code for the
compiler.</p>
Evaluating Emacs Lisp expressions</h4>
Given that the parser generates quoted Emacs Lisp code, how does the compiler
actually evaluate it? With eval</code>.</p>
(</span>eval</span> '(</span>+</span> 1 2</span>))</span></span>
;; => 3</span></span></code></pre>
One problem remains, however. My original approach relied on alist-get</code> to
insert values from the parent environment into the source template when
replacing regular expressions. This assumed that all text inside mustache braces
was represented by a key-value pair in an association list.</p>
;; Recall, replacing a variable in a template</span></span>
(</span>assert-compile-to-string</span></span>
  :</span>input</span>    "Hello, {{ name }}!"</span></span>
  :</span>expected</span> "Hello, world!"</span></span>
  :</span>env</span>      '((</span>name </span>.</span> "world"</span>))</span></span></code></pre>
How does eval</code> similarly replace variables from the parent environment? The key
is the third argument of eval</code>:</p>
Signature</span></span>
(eval FORM &optional LEXICAL)</span></span>
</span>
Documentation</span></span>
Evaluate FORM and return its value.</span></span>
</span>
If LEXICAL is t, evaluate using lexical scoping.</span></span>
LEXICAL can also be an actual lexical environment, in the form of an</span></span>
alist mapping symbols to their value.</span></span></code></pre>
If an alist is passed into eval</code> it uses it as the lexical environment with
which variables are evaluated. This approach solves the problem of variable
substitution without hard-coding the use of alist-get</code>.</p>
(</span>eval</span> '</span>name</span> '((</span>name </span>.</span> "world"</span>)))</span></span>
;; "world"</span></span></code></pre>
When quoted symbols are evaluated, Emacs Lisp knows to look up that symbol from
the ENV</code> alist for its value. Cool.</p>
Requiring a quoted symbol for the variable actually poses a bit of a problem for
this compiler. When a layout is tokenized, that layout is input as a string. All
of the generated tokens reference string values. Since eval</code> requires a symbol,
those strings need to be converted.</p>
Luckily this problem is easily solvable with the function read-from-string</code>:</p>
(</span>read-from-string</span> "name"</span>)</span></span>
;; '(name . 4)</span></span>
</span>
(</span>eval</span> (</span>car</span> (</span>read-from-string</span> "name"</span>)) '((</span>name </span>.</span> "world"</span>)))</span></span>
;; "world"</span></span></code></pre>Parsing</h4>
With quoting and eval out of the way, it's time to fill in the parser. For each
conditional branch against a token, the parser pushes a tree of Emacs Lisp
expressions into the AST. When mustaches are detected (e.g. obrace</code>) a call to
eval-string</code> is to pend the execution of that text as an Emacs Lisp expression.
Regular text is inserted as-is.</p>
(</span>defun</span> lastcar</span> (</span>l</span>)</span></span>
  "Extract the last element from list L."</span></span>
  (</span>car</span> (</span>cdr</span> l</span>)))</span></span>
</span>
(</span>defun</span> eval-string</span> (</span>string env</span>)</span></span>
  (</span>eval</span> (</span>car</span> (</span>read-from-string</span> string</span>))</span> env</span>))</span></span>
</span>
(</span>defun</span> parse</span> (</span>tokens</span>)</span></span>
  (</span>let</span> ((</span>expressions </span>'()) (</span>cur </span>0</span>))</span></span>
    (</span>while</span> (</span><</span> cur </span>(</span>length</span> tokens</span>))</span></span>
      (</span>let</span> ((</span>token </span>(</span>nth</span> cur tokens</span>)))</span></span>
        (</span>cond</span> ((</span>eq</span> '</span>text</span> (</span>car</span> token</span>))</span></span>
               (</span>push</span> `(</span>insert</span> ,</span>(</span>lastcar token</span>))</span> expressions</span>))</span></span>
              ((</span>eq</span> '</span>obrace</span> (</span>car</span> token</span>))</span></span>
               ;; Assume that the only token between an obrace</span></span>
               ;; and a cbrace is text.</span></span>
               (</span>push</span> `(</span>insert</span> (</span>eval-string</span></span>
                               ,</span>(</span>lastcar </span>(</span>nth</span> (</span>1+</span> cur</span>)</span> tokens</span>))</span></span>
                               env</span>))</span></span>
                     expressions</span>)</span></span>
               (</span>setq cur </span>(</span>+</span> cur </span>2</span>)))</span></span>
              ((</span>eq</span> '</span>cbrace</span> (</span>car</span> token</span>))</span></span>
               (</span>error</span> "Unexpected closing brace"</span>))))</span></span>
      (</span>setq cur </span>(</span>1+</span> cur</span>)))</span></span>
      ;; ,@ means spill the contents, kind of like</span></span>
      ;; the ... operator in JS or Rust.</span></span>
    `(</span>lambda</span> (</span>env</span>) ,@(</span>reverse</span> expressions</span>))))</span></span>
</span>
;; How the generated code is actually executed.</span></span>
(</span>defun</span> compile-and-exec</span> (</span>input env</span>)</span></span>
  (</span>funcall</span> (</span>parse </span>(</span>tokenize input</span>))</span> env</span>))</span></span></code></pre>
It's probably a little easier to look at the generated code:</p>
;; Hello {{ name }}</span></span>
</span>
(</span>lambda</span> (</span>env</span>)</span></span>
  (</span>insert</span> "Hello, "</span>)</span></span>
  (</span>insert</span> (</span>eval-string </span>"name"</span> env</span>)))</span></span></code></pre>
The root of the tree is a lambda expression, taking the env as a single
argument. The lexical environment containing the page variables and other
metadata are assembled earlier in the static site generator and passed down as
an alist.</p>
Everything else boils down to insert statements, writing a string into the
current buffer. What's great about the generated code is the deferred evaluation
of env</code>. The parser builds quoted forms to avoid working with env</code> until the
very last minute, that is, when the lambda expression is evaluated. This keeps
the parser decoupled from anything that may happen in the lexical environment.</p>
compile-and-exec</code> is meant for use with a fresh buffer, since the insert
statements will mutate that buffer with their string arguments. Something like
with-temp-file</code>, which will write the buffer contents to a new file:</p>
(</span>with-temp-file</span> destination-file</span></span>
  (</span>compile-and-exec template-string env</span>))</span></span></code></pre>
That about wraps it up. Orgify</a> supports some
additional syntax not mentioned in this article, but hopefully it's clear how
the components from the parser can be altered to add loops and conditionals.</p>


Small Weekend Projects
2023-07-05T00:00:00+00:00
I love small weekend projects. A project completed in two days is either smartly
scoped or hacked together; the core of a great idea that's been sitting in the
back of your mind or a feat of engineering spontaneity that is given just enough
space to flourish into reality. Either way it's a great way to learn new things.</p>
I was compelled this weekend to build my own
static site generator</a>, not because I found existing
ones lacking, but because I wanted one to call my own. The basics are easy to
get right but the details expand into a surprisingly interesting problem space.
I guess that's one reason for why so many already exist.</p>
I started by settling on Org</a> as my generator's primary
markup format. It's supported OOTB in Emacs and already supports HTML exports
(via ox-html</code>) so I didn't need to spend my weekend writing an exporter.
Instead, I focused on the basics. Copy some static files, convert the contents
of Org files to HTML, and substitute that content into HTML layouts.</p>
Where things start getting interesting is with layouts and templates. There's a
whole host of template expressions that you might want to support in a
generator, from basic substitutions to loops and conditionals. I learned that
Emacs Lisp has an incredibly elegant solution for handlebars-like template
substitutions:</p>
(</span>while</span> (</span>re-search-forward</span> "{{[ ]*[a-z]*[ ]*}}"</span> nil</span> t</span>)</span></span>
  (</span>if</span> (</span>gethash</span> (</span>match-string</span> 0</span>)</span> template-content</span>)</span></span>
      (</span>replace-match</span> (</span>gethash</span> (</span>match-string</span> 0</span>)</span> template-content</span>))</span></span>
    (</span>error</span> "expression not recognized: %s"</span> (</span>match-string</span> 0</span>))))</span></span></code></pre>
This code searches the current buffer for a regular expression matching
handlebars, like {{ foobar }}</code>. As long as a match is found, lookup the match
in a hash-table containing the original file's frontmatter (template-content</code>).
Then, swap out the template expression in-place with its matching value via
replace-match</code>. Super easy!</p>
The final product looks something like this:</p>

Loop over the directory of Org files.</li>
Use ox-html</code> to parse an Org file, storing the HTML content and frontmatter
keywords separately.</li>
Insert the Org file's associated layout into a new buffer.</li>
Search for handlebar expressions in the current buffer and substitute them
with the HTML from step 2.</li>
Write the current buffer to a new HTML file in the user's output directory.</li>
</ol>
I'm super happy with where the project ended up as an MVP, though there's still
a few features I need to implement before it can actually be used for a blog
(namely: template loops and collections).</p>
You can check out the documentation (built in Orgify!) here:
https://orgify.pages.dev</a>. Or, read the source code:
https://git.sr.ht/~mgmarlow/orgify</a>.</p>


Building a Flymake Backend for Clippy
2023-06-19T00:00:00+00:00
Last weekend I had a great time building my own Flymake backend for Clippy (the
Rust linter): flymake-clippy</code></a>.
If you haven't heard of Flymake, it's old-school Emacs tech for showing
squiggly-lines in your editor. You can build your own Flymake extensions by
creating a function, referred to as a backend, that collects diagnostics and
reports them to Flymake. Register that backend in your Emacs config and you've
got squiggles whenever you open up a Rust file. Pretty cool!</p>
flymake-clippy</code> is an extension of the
annotated example</a>
found in the Emacs Manual. While the example serves as a great starting point, I
found that in practice it leaves too many details unexplained. Most of my
development time was spent looking through the Emacs documentation, learning
about regular expression match groups, external processes, and buffer searching.
There were also some surprises when trying to integrate flymake-clippy</code> with
Eglot, the LSP package that now ships with Emacs.</p>
How does it work?</h2>
With Flymake mode active, each backend function included in the variable
flymake-diagnostic-functions</code> is called on the current Emacs buffer. When the
flymake-clippy</code> backend is invoked, the following things happen in sequence:</p>

cargo clippy</code> is called and its output is thrown into a temporary buffer
(*flymake-clippy*</code>)</li>
A
process sentinel</a>
is triggered, invoking a callback that parses the contents of that temporary
buffer and collects diagnostic information into a list</li>
That list of diagnostics is sent to Flymake via another callback function</li>
The temporary buffer and process are cleaned up</li>
</ol>
These steps are repeated many times throughout the lifecycle of a single buffer,
creating and destroying squiggles as problems are introduced or addressed.</p>
Code walkthrough</h2>
In a bit more detail, the first step is to create a process:</p>
(</span>make-process</span></span>
 :</span>name</span> "flymake-clippy"</span> :</span>noquery t</span> :</span>connection-type</span> '</span>pipe</span></span>
 :</span>buffer</span> (</span>generate-new-buffer</span> "*flymake-clippy*"</span>)</span></span>
 :</span>command</span> '(</span>"cargo" "clippy"</span>)</span></span>
 :</span>sentinel</span></span>
 (</span>lambda</span> (</span>proc _event</span>)</span></span>
   (</span>when</span> (</span>memq</span> (</span>process-status</span> proc</span>) '(</span>exit</span> signal</span>))</span></span>
     ...</span>)))</span></span></code></pre>
This process runs the command cargo clippy</code>, our linter, and pipes its output
into the buffer *flymake-clippy*</code> (named via the call to
generate-new-buffer</code>). While that process is active, several events are sent to
the sentinel, invoking its respective lambda. flymake-clippy</code> only cares about
the exit</code> or signal</code> events, which are checked via process-status</code>. All other
events are ignored.</p>
The core of flymake-clippy</code> lives in the rest of that lambda function:</p>
(</span>lambda</span> (</span>proc _event</span>)</span></span>
  ;; ... snip ...</span></span>
  (</span>with-current-buffer</span> (</span>process-buffer</span> proc</span>)</span></span>
    (</span>goto-char</span> (</span>point-min</span>))</span></span>
    (</span>cl-loop</span></span>
     while</span> (</span>search-forward-regexp</span></span>
            (</span>flymake-clippy--build-regexp</span>)</span></span>
            nil</span> t</span>)</span></span>
     for</span> msg </span>=</span> (</span>match-string</span> 1</span>)</span></span>
     for</span> sourcefile </span>=</span> (</span>match-string</span> 2</span>)</span></span>
     for</span> (</span>beg </span>.</span> end</span>)</span> =</span> (</span>flymake-diag-region</span></span>
                        source</span></span>
                        (</span>string-to-number</span> (</span>match-string</span> 3</span>)))</span></span>
     for</span> type </span>=</span> (</span>if</span> (</span>string-match</span> "^warning"</span> msg</span>)</span></span>
                     :</span>warning</span></span>
                   :</span>error</span>)</span></span>
     when</span> (</span>and</span> sourcefile </span>(</span>string-match-p</span> sourcefile filename</span>))</span></span>
     collect</span> (</span>flymake-make-diagnostic source</span> beg end type msg</span>)</span></span>
     into</span> diags</span></span>
     finally</span> (</span>funcall</span> report-fn diags</span>)))</span></span>
  (</span>kill-buffer</span> (</span>process-buffer</span> proc</span>)))</span></span></code></pre>
This code is pretty dense but most of it is facilitating a loop through the
*flymake-clippy*</code> buffer and parsing the Clippy output into variables.
cl-loop</code> is a powerhouse looping macro that actually comes from
Common Lisp</a>. It's
accessible in Emacs through the library cl-lib</code>, a compatibility library that
brings a bunch of Common Lisp functions/macros into Emacs Lisp.</p>
The while</code> keyword has this code searching via a regular expression, looking
for matches that are transformed into Flymake diagnostic output.</p>
The regular expression for flymake-clippy</code> looks something like this:</p>
"^\\(warning:.*\\)</span>\</span>n.*--> \\(.*\\):\\([0-9]+\\):\\([0-9]+\\)$"</span></span></code></pre>
Matching text like:</p>
warning: using `clone` on type `Status` which implements the `Copy` trait</span></span>
  --> src/foo.rs:31:29</span></span></code></pre>
At the core of the regexp are four match groups:</p>

The message, prefixed with "warning:"</li>
The file, prefixed with "-->"</li>
The line number</li>
The column number</li>
</ol>
Each one of these match groups is assigned to a variable in cl-loop</code> via the
match-string</code> function, grabbing match data from the most recent regular
expression. Most of these variables are handed off to Flymake as-is, with the
exception of line number. Clippy's line number needs a little translation (via
flymake-diag-region</code>) so it's useful in a buffer context.</p>
Since Clippy runs against the entire Cargo project and not just a single file, I
also include a when</code> expression to compare the open buffer filename against the
filename match group. Otherwise, messages from other files will show up in the
diagnostics.</p>
With the collect</code> keyword, cl-loop</code> collects the diagnostic variables into a
list of Flymake data structures. These data structures are handed off to Flymake
via the callback: (funcall report-fn diags)</code>.</p>
Testing regular expressions</h2>
I found it much easier to iterate on a regular expression by writing tests
rather than manually executing Emacs commands, so I used
ERT</a> to run the
regular expression against a temporary buffer of Clippy output:</p>
(</span>require</span> '</span>flymake-clippy</span>)</span></span>
(</span>require</span> '</span>ert</span>)</span></span>
</span>
(</span>defun</span> run-regexp</span> ()</span></span>
  ;; Reset regexp match data</span></span>
  (</span>set-match-data</span> nil</span>)</span></span>
  (</span>search-forward-regexp</span> (</span>flymake-clippy--build-regexp</span>)</span> nil</span> t</span>)</span></span>
  (</span>list</span> (</span>match-string</span> 1</span>)</span></span>
        (</span>match-string</span> 2</span>)</span></span>
        (</span>match-string</span> 3</span>)))</span></span>
</span>
(</span>ert-deftest</span> clippy-test-regexp </span>()</span></span>
  "Tests regexp matches diagnostic information."</span></span>
  (</span>should</span></span>
   (</span>equal</span></span>
    ;; Open a temp buffer with the contents of a test</span></span>
    ;; fixture that contains Clippy output</span></span>
    (</span>with-temp-buffer</span></span>
      (</span>insert-file-contents</span> "./test/fixture.txt"</span>)</span></span>
      (</span>run-regexp</span>))</span></span>
    '(</span>"warning: unused variable: `user`" "src/database/foo.rs" "42"</span>))))</span></span></code></pre>
This file is also a good demonstration of the regular expression match groups
that are passed into flymake-make-diagnostic</code>.</p>
Working with Eglot</h2>
I ran into a few surprises setting up flymake-clippy</code> and Eglot in my
configuration. It turns out that Eglot hijacks Flymake, suppressing all other
Flymake backends while Eglot is running. This isn't an issue with Eglot per se,
but a design decision (see
eglot#268</a>); Eglot uses Flymake
to demonstrate LSP diagnostics and suppresses other backends to avoid duplicate
messages.</p>
There is a workaround that I use in my configuration that allows Clippy and
Eglot to coexist:</p>
(</span>use-package</span> flymake-clippy</span></span>
  :</span>vc</span> (</span>:</span>fetcher sourcehut </span>:</span>repo mgmarlow/flymake-clippy</span>)</span></span>
  :</span>hook</span> (</span>rust-mode</span> .</span> flymake-clippy-setup-backend</span>))</span></span>
</span>
(</span>defun</span> manually-activate-flymake</span> ()</span></span>
  (</span>add-hook</span> '</span>flymake-diagnostic-functions</span> #'</span>eglot-flymake-backend</span> nil</span> t</span>)</span></span>
  (</span>flymake-mode</span> 1</span>))</span></span>
</span>
(</span>use-package</span> eglot</span></span>
  :</span>ensure t</span></span>
  :</span>hook</span> ((</span>rust-mode</span> .</span> eglot-ensure</span>)</span></span>
         (</span>eglot--managed-mode </span>.</span> manually-activate-flymake</span>))</span></span>
  :</span>config</span></span>
  (</span>add-to-list</span> '</span>eglot-stay-out-of</span> '</span>flymake</span>))</span></span></code></pre>
eglot-stay-out-of</code> disables Eglot's control over Flymake. This opens up the
possibility of running other Flymake backends in a buffer with Eglot, but also
removes Eglot's backend from the flymake-diagnostic-functions</code> list. It's
important to add eglot-flymake-backend</code> back to that list, as well as manually
activate it during eglot--managed-mode</code>.</p>
Flymake vs. Flycheck</h2>
Those in the know may be wondering why I built a Flymake backend instead of one
for Flycheck</a>. The two libraries
are now very similar, though in past Emacs releases they deviated substantially.</p>
Flymake is the older of the two (since Emacs 22) and is included in Emacs as a
built-in package. There was a period of time between Emacs 22 and 27 where
Flymake was not receiving much love and attention, languishing with some
long-standing issues. Flycheck rose during this time as a drop-in replacement.</p>
Nowadays, thanks to the efforts of Eglot author João Távora, Flymake and
Flycheck are on mostly equal footing. I chose Flymake simply because it's built
into Emacs and I didn't want to introduce a new dependency. That said,
Flycheck vs. Flymake</a>
discusses the pros and cons in more detail.</p>
flymake-clippy</h2>
If you want to see Clippy warnings in your Rust buffers, check out
flymake-clippy</a>. Refer to the
README</a>
for setup instructions.</p>


Thoughts on Taiji
2023-05-29T00:00:00+00:00
As a big fan of
The Witness</a> I'm always
on the lookout for games that scratch a similar itch. Unfortunately that list is
fairly short; common recommendations include games of direct inspiration (Cyan's
Myst</a>), games with puzzle design expertise
(Stephen's Sausage Roll</a>), games with
meta-philosophical commentary
(The Talos Principle</a>),
among others. Although these games are great in their own way (and often equally
abstract or mysterious) they ultimately don't play much at all like The Witness.</p>
The element that's lacking in these other games is the special sauce that makes
the puzzles in The Witness so satisfying: the gradual reveal of a complex puzzle
language that's explained only by the player's own tinkering and theory
crafting. There's no direct tutorialization in The Witness, at least not in the
form of expository text. The tutorial is the game itself</em>, every puzzle a
Rosetta Stone for some mechanic or interaction that is remixed, combined, or
built upon in future puzzles.</p>
While this quality is present in the games I mentioned previously (as it's a
necessary quality for a great puzzle game), it differs in The Witness because
the entire game is built around it. The Witness understands its method of
teaching and weaponizes it in its puzzle design, leading to puzzles layered in
mechanics that understand their history. It's a language filled with idioms and
slang whose purpose is to bring epiphany.</p>
Taiji</a> is about as close to The Witness as a game can
get without actually being The Witness. This similarity is both good and bad. On
one hand, Taiji evokes the same sense of wonderful epiphany that comes from
discovering its secrets. On the other, it is impossible to discuss without
comparing it to a game that is broader both in scope and team size.</p>
This leads me to mixed feelings about Taiji. Although it clearly understands
what makes The Witness great and manages to evoke a similar experience while
establishing its own language, I found many of its puzzles messy and obscured by
its presentation.</p>
This problem is mostly apparent in areas with environmental queues, like The
Ruins or The Graveyard. Many times I solved a puzzle thinking I understood the
designer's intent, feeling good about my progress. Then I'd hit a wall on a
later puzzle where some concept I had missed re-emerges. Finding the solution
seems so far outside my assumptions that I lack a language for experimentation.
Instead, I frustrate myself by floundering around with oddball ideas. It's only
after replaying earlier puzzles in the sequence that I recognize I had wrongly
interpreted some environmental cue or missed a subtle detail that drastically
changes the intended progression. I'm deprived of an "Aha!" moment, feeling more
like I was blinded by extraneous details than properly working through a
difficult problem.</p>
That's not to say all of the puzzles in the game have this issue, it just
happened to be most present in some of the first areas I ventured into. I found
the game at its best when the puzzles were constrained to the interactive grid,
no environmental details needed. I most enjoyed solving The Mine, The Shrine,
and The Mill for this reason. The areas of The Ruins, The Graveyard, and The
Gallery (easily my least favorite area) feel weaker due to the game's
perspective and composition of environmental details. My issues with instruction
are less apparent when all of the details are constrained to a well-purposed
grid.</p>
In a similar vein, my favorite puzzles were the ones in the canonical bad ending
of the game, The Black. Without spoiling too much, these puzzles flip the
interactive elements of the grid and completely change the way in which the
player approaches a solution. The language is the same but the tools are
inverted, the way you solve it re-applies everything you've learned in an
unforeseen way. It's great!</p>
Contrast this with The White, a series of environmental puzzles that I skipped
in favor of looking up the solutions on the internet. Perhaps this last section
would have had a greater impact if I hadn't already played through The Witness.</p>
That said, Taiji is a worthy game in its own right, even if it doesn't live up
to the quality of puzzle design in its inspiration, The Witness. Its scope and
price-point are perfection for those looking for a solid puzzle game.</p>


New Emacs Package: git-share
2023-04-29T00:00:00+00:00
Today I released an open source Emacs package:
git-share</a>.</p>
This is my first real attempt at a proper Emacs package, bringing together some
scattered elisp scripts I had in my config into a complete, unit-tested whole. I
use this command just about every working day to send code links to colleagues
across our different git repositories.</p>
With Emacs 29 it's easy to install the package straight from the repository. Add
these lines to your Emacs config:</p>
(</span>unless</span> (</span>package-installed-p</span> '</span>git-share</span>)</span></span>
  (</span>package-vc-install </span>"https://github.com/mgmarlow/git-share"</span>))</span></span></code></pre>
Invoke M-x git-share</code> when your Emacs point is positioned on a line of code
you'd like to share and the link will be copied (killed) to your system's
clipboard.</p>
Tips and Tricks</h2>
Here are some tips I stumbled on when building this package:</p>

You can generate the comment boilerplate for your Emacs package with
M-x auto-insert</code>. It prompts you for a description and some tags, then fills
in the requisite copyright notice, author fields, and other structural
comments for your package. More info:
Conventional Headers for Emacs Libraries</a>.</li>
Unit testing with
ERT</a> is really
straightforward. I use
this Makefile</a>
to run the test suite against the compiled (.elc</code>) package.</li>
When browsing for functions with C-h f</code> it's easy to accidentally include
ones that aren't shipped with Emacs, but are autoloaded by other packages
(notably in my case, string helpers from
s.el</a>). Using ERT batch testing helped me
find these problems since it works against the vanilla Emacs install.</li>
Read the
Emacs Lisp Coding Conventions</a>.</li>
Even if you're not contributing to MELPA, their
contributing guidelines</a>
are a great source of tips.</li>
</ol>


A Note-taking System for Work
2023-04-04T00:00:00+00:00
Keeping a code journal has been a gratifying way to measure my professional
growth and keep track of esoteric information. Over the years I've experimented
with tons of different methods</a>, but code
notes are trickier than word notes and are constrained to a digital environment.</p>
Daily entries are too sparse to be useful, spreading information in a way that
is irrecoverable without a tagging nightmare. Zettelkasten-style is too
nit-picky, exhausting too much of my time in organization and placement. I've
settled on a nice middle ground: a weekly coding scratchpad with backlinks to
longer-form reference material.</p>
Emacs is a great tool for coding notes in particular, thanks to the
literate programming</a>
environment
org-mode babel</a>. The
same org file</a> that contains my todos also serves as a
dynamic code environment, turning code snippets into executable scripts. Linking
between notes is also easily supported with a lightweight package like
denote</a>.</p>
Together these tools are powerful but not overwhelming. Denote handles naming
conventions for my files so I don't need to think about consistency or
placement; org-mode handles markup, tagging, code execution, and todos.</p>
It's also very easy to extend. Here's the Emacs command I use to generate my
weekly scratchpad, along with its template:</p>
(</span>require</span> '</span>denote</span>)</span></span>
</span>
(</span>defun</span> my/denote--weekly-template</span> ()</span></span>
  (</span>concat</span> "* Friday"</span></span>
          "</span>\</span>n</span>\</span>n"</span></span>
          "- [ ] Retrospective</span>\</span>n"</span></span>
          "</span>\</span>n"</span></span>
          "* Thursday"</span></span>
          "</span>\</span>n</span>\</span>n"</span></span>
          "* Wednesday"</span></span>
          "</span>\</span>n</span>\</span>n"</span></span>
          "* Tuesday"</span></span>
          "</span>\</span>n</span>\</span>n"</span></span>
          "* Monday"</span></span>
          "</span>\</span>n</span>\</span>n"</span></span>
          "* Notes"</span>))</span></span>
</span>
(</span>setq denote-templates </span>`((</span>weekly </span>.</span> ,</span>(</span>my/denote--weekly-template</span>))))</span></span>
</span>
(</span>defun</span> my/denote-weekly</span> ()</span></span>
  "Find or create a weekly journal entry."</span></span>
  (</span>interactive</span>)</span></span>
  (</span>let*</span> ((</span>display-time</span> (</span>format-time-string</span> "%G-%U"</span> (</span>current-time</span>)))</span></span>
         (</span>title </span>(</span>concat</span> "week-"</span> display-time</span>))</span></span>
         (</span>pattern </span>(</span>concat</span> ".*--"</span> title</span>))</span></span>
         (</span>matches </span>(</span>denote-directory-files-matching-regexp pattern</span>)))</span></span>
    (</span>if</span> matches</span></span>
        (</span>find-file</span> (</span>car</span> matches</span>))</span></span>
      (</span>denote title </span>'(</span>"journal" "weekly"</span>) '</span>org</span> nil nil</span> '</span>weekly</span>))))</span></span></code></pre>
Calling the command my/denote-weekly</code> in Emacs will either (a) create a new
denote file with the title "week-YYYY-ww" and the appropriate tags, or (b) open
the existing denote file if one was already created.</p>
The org files themselves end up looking something like this:</p>
#+title:      week-2023-01</span></span>
#+date:       [2023-01-02 Mon 08:02]</span></span>
#+filetags:   :journal:weekly:</span></span>
#+identifier: 20230101T080211</span></span>
</span>
* Friday...</span></span>
* TODO Thursday</span></span>
</span>
- [X] Already done!</span></span>
- [ ] Cool coding stuff here</span></span>
</span>
** Testing scripts for something</span></span>
</span>
#+begin_src elisp</span></span>
  (message "I was executed with org-babel-execute-src-block!")</span></span>
#+end_src</span></span>
</span>
#+RESULTS:</span></span>
: I was executed with org-babel-execute-src-block!</span></span></code></pre>
Occasionally I'll need to convert from org to markdown to copy something from my
notes into a work document or task. Calling org-md-export-as-markdown</code> opens up
a new buffer with the entire contents of my weekly note in markdown, ready for
copy+paste.</p>
Org itself is rich with features</a> but the
real game-changer for me is the ability to paste code links from disc into an
org file (via org-store-link</code>). Clicking the link will open the source file in
Emacs at the line of code where the link was stored. I used to rely on a similar
workflow by linking to Github (via a custom
Emacs command</a>), but linking to local
files within Emacs is way better for browsing, editing, and note-taking.</p>
As far as retrieval goes, denote timestamps notes on creation so they're neatly
organized in a flat directory:</p>
~/denote/</span></span>
  20230102T080211--week-2023-01__journal_weekly.org</span></span>
  20221228T091238--week-2022-52__journal_weekly.org</span></span>
  20221221T083238--week-2022-51__journal_weekly.org</span></span>
  20221223T113238--active-record-tips__rails.org</span></span>
  ...</span></span></code></pre>
And since org files are plaintext, you can use org-mode, Emacs, or grep to
search through their contents. Check out
Advanced searching</a>
in the org-mode documentation to see what's possible.</p>


Burn After Writing
2023-03-21T00:00:00+00:00
I think I've experimented with just about every method imaginable for organizing
my writing. Recent trends point me towards zettelkastens, backlinks, and other,
less savory terms like "second brain". When I spend so much time writing useless
things I feel I owe myself to organize them, lest I miss out on some revelatory
moment that spurs a successful novel. I'm still waiting.</p>
Despite trying all the flavors, no technique has stuck. Most often the strategy
is too strict; the burden of placing a note in the right place has me forgetting
my original intention for writing it.</p>
The conclusion I've come to is that I've spent far too many hours researching a
topic that is uniquely personal.</p>
My primary goal in writing is to write. Not to denote, tag, or organize. Not to
bibliograph, or space-ly repeat, or architect a knowledge graph. And the best
tool I've found for the job of writing remains pen and paper.</p>
Paper doesn't hide mistakes and offers no grammar plugin to help disguise your
voice. Writing by hand is slow and meditative, ensuring each word is adequately
chewed over before it's spat out. Best of all, I can stash that thought deep
inside a notebook on my shelf and never have to look at it again.</p>
That shelf houses all of my writings, a bunch of notebooks piled together in
neat stacks. I'm comforted that I won't easily find thoughts from previous me
without digging through them all, one by one. What use are those ideas anyway,
now that I've changed since writing them?</p>


Anatomy of a Screenplay
2023-02-11T00:00:00+00:00
Here are some notes I took during
An Introduction to Screenwriting</a>.
The course breaks down the standard film screenplay format and helps
conceptualize the process of writing one yourself.</p>
The pitch</h2>
Before moving from idea to paper you'll need to clarify your intentions. Use
these five points as the baseline:</p>

Genre</li>
Main protagonist</li>
Goal</li>
Obstacle</li>
Why this story is important</li>
</ol>
Draw special attention to point 5. What makes your story unique, what theme are
you trying to portray? That theme will guide the rest of the screenwriting
process.</p>
Once you've got a good pitch nailed down it's time to write your logline.</p>
The logline</h2>
Take your pitch and throw it into a one-sentence summary. Here are some
examples:</p>

Apocalypse Now</strong>: During the U.S.-Vietnam War, Captain Willard is sent on a
dangerous mission into Cambodia to assassinate a renegade colonel who has set
himself up as a god among a local tribe.</p>
</blockquote>

The Matrix</strong>: A computer hacker learns from mysterious rebels about the true
nature of his reality and his role in the war against its controllers.</p>
</blockquote>

Reservoir Dogs</strong>: After a simple jewelry heist goes terribly wrong, the
surviving criminals begin to suspect that one of them is a police informant.</p>
</blockquote>
Don't stress out about this step, you'll likely tweak and revise as you write.</p>
Flesh out your story</h2>
Build upon your pitch with more details. Film is all about character and change,
use those principles to string together your story beats.</p>
What's a beat?</h3>
A story event that transforms the character and story at a critical juncture. A
beat is at the heart of every scene.</p>
Three act structure</h3>
A three-act story maps to a 25-50-25 rhythm, delivering a 100 minute screentime.
The broad strokes of a three act structure are as follows:</p>

Protagonist and goal introduction (25min)</li>
</ol>
Introduce the setting, genre, characters, themes, and protagonist. Set the tone
for how the audience should consume the movie.</p>

What's the obstacle? (50min)</li>
</ol>
Obstacles force the character into new situations, relationships, and
circumstances.</p>

Resolve the story (25min)</li>
</ol>
Does the protagonist get what they want? How have they changed?</p>
Save the Cat Beat Sheet</h3>
The Save the Cat Beat Sheet</a> is a well-known
boilerplate structure for your average screenplay. Take bits and pieces of it to
help structure your story beats.</p>

Opening image: make the look & feel of your story immediately apparent.</li>
Theme stated: communicate your story's theme. Often in a way that your
protagonist doesn't quite grasp.</li>
Set-up: establish setting, character, status quo. Who is your character now
so that we can recognize their change?</li>
Catalyst: disrupt your protagonist's status quo. They may not be ready to
make a choice, but the story doesn't wait.</li>
Debate: the protagonist has doubts about leaving routine behind.</li>
Break into act II: it's time to set out on adventure.</li>
B story: subplots ensure, often concerning romance.</li>
Fun and games: the protagonist has fun in their new reality.</li>
Midpoint: the protagonist closes in on their goal.</li>
Bad guys close in: the protagonist may be close, but antagonist
forces/obstacles don't make it easy.</li>
All is lost: dire circumstances lead to loss.</li>
Dark night of the soul: the protagonist grapples with change and reminisces
on their old reality. Hope is lost.</li>
Break into act III: with misery comes a revival.</li>
Finale: climatic resolution of conflict.</li>
Final image: a bookend that re-invokes the central theme.</li>
</ol>
Writing the script</h2>
Time to put your hard work to paper.</p>

Write down your pitch.</li>
Develop a logline.</li>
Draft up a summary (a few pages in length).</li>
Lay out the major story beats (~15). Index cards are a great tool for this
purpose, one beat per card.</li>
Write your scenes.</li>
</ol>
Screenwriting and film</h2>
There's nothing revolutionary here but it's interesting to see the guts of a
movie exposed. Where do films deviate from these structures, and to what effect?</p>
Campbellian archetypes</a>
tell us that storytelling is fundamental to humanity and that the stories
themselves often map to a common structure. It's interesting to explore such
structures and relate them to our own experience. Whether or not the
monomyth</a> is the beginning and
end of storytelling doesn't dismiss its ubiquity in modern media.</p>
Here we see the same base structures in the form of the Save the Cat Beat Sheet.
Perhaps part of the enjoyment we get from watching movies and listening to
stories is the recognition of common patterns, conflicts, and themes. I suppose
more generally that's a trait in all art. Patterns are comforting in their
familiarity, alarming in subversion.</p>
Recognizing these meta-structures is one of my favorite techniques of analysis.
With a good understanding of patterns and archetypes a story can be broken into
its base components. Those components reveal the author's intent, emphasizing
deviations and reinforcing themes.</p>


Nostalgia for the Early Web
2023-02-06T00:00:00+00:00
Although it was a bit before my time I still have nostalgia for the early web.
You know, that time when everyone still used rainbow
marquees</a>
and site-visit counters. Sure, the early web was ugly compared to our modern
minimalist leanings, but it was also fresh and original and full of useless
curios.</p>
My fondest memories of the early web are probably those spent browsing
StumbleUpon</a>, the website slot
machine. I'd click aimlessly and travel the world for hours, reading high school
drama or learning sailing knots or sending zombocom vibes</a>
to my friends.</p>
So many people used personal websites to air their emotions to the world and
broadcast their cool hobbies. It might've been twice the words that can fit in a
tweet but it was also twice the personality. The web at this era wasn't the
place for your office suite, and it hadn't yet attained the status of "useful".</p>
I think the modern web lost something in the transition away from these
self-hosted blogs. Projects like theuselessweb.com</a>
can emulate that sort of creative energy, but the web as a whole is lacking in
it.</p>
Things look particularly dire when you come across unfriendly patterns so often:
subscription pop-up modals with microscopic dismissal buttons, SEO spam
cluttering up the first page of Google results, invasive advertisements and
autoplaying videos (thanks Fandom). Browsing websites randomly is a recipe for
disaster. Instead, we rely on centralized platforms like Twitter, Medium, or
Substack, all complete with their own set of issues and worried foremost about
monetization.</p>
Recently I discovered the Gemini Protocol</a>,
the origin of my recent wave of early web nostalgia. It's an alternative to the
web, built around a protocol that is inherently limiting. Gemini restricts
content to just text and links, no JavaScript, CSS, or HTML5.</p>
Exploring Gemini servers has been a delightful experience. For example, the
Midnight Pub</a> is a tiny message board themed around its
namesake, full of interesting posts. Some are in character, most are just
regular blogs.</p>

The city is buzzing, the streets are like arteries. You see an intriguing
place in the alley, with a moon on its door. It reads "The Midnight Pub".</p>
</blockquote>
There's something raw and emotional and even voyeuristic about the types of blog
posts that you find on Gemini. A lot of them channel the feelings I have towards
my early experience with the web, or the modern re-telling of something like
Hypnospace Outlaw</a>.</p>
Although I don't have any faith that Gemini will replace the web, nor would I
particularly want it to, I welcome it as an interesting alternative. If you're
interested in checking it out, read the guide over at
geminiquickst.art</a>.</p>


Emacs 29 Quick Start
2023-01-18T00:00:00+00:00

Update: I created Start Emacs</a> as an
easier way to get up and running with Emacs. It follows many of the same
principles in this guide and throws in some extras.
Check it out here</a></p>
</blockquote>
The no-nonsense guide to getting started with Emacs.</p>
By the end of this guide you'll have Emacs 29 configured with better default
settings, IDE features like code-completion and LSP support, and much improved
minibuffer completion. Everything listed here is available out of the box or
downloaded from the default Emacs package server,
GNU Elpa</a>.</p>
Installation</h2>
Begin by installing Emacs 29 for your OS:</p>

Mac OS: emacs-plus</a> via
Homebrew</li>
Linux: Build from source</a> (see
INSTALL</a>)</li>
Windows: Download an
alpha.gnu.org snapshot</a></li>
</ul>
It's important to use Emacs 29+ and not a prior version. Emacs 29 ships with two
important libraries (eglot</a> and
use-package</a>) that are used
extensively in this guide.</p>
Run through the tutorial</h2>
Go ahead and launch Emacs. You're greeted with the startup screen which presents
a bunch of useful information and a dated logo. Of particular note is the Emacs
tutorial, which you should click on before continuing with the rest of this
guide.</p>
You can also launch the tutorial via C-h t</code>.
(What is C-h</code></a>?)</p>
Settings</h2>
You've installed Emacs and you know some basic commands. It's time to edit your
emacs configuration file:</p>
C-x C-f ~/.emacs.d/init.el</span></span></code></pre>
Drop in the following
Emacs Lisp</a>
code:</p>
;; Hide UI</span></span>
(</span>menu-bar-mode</span> -1</span>)</span></span>
(</span>tool-bar-mode</span> -1</span>)</span></span>
(</span>scroll-bar-mode</span> -1</span>)</span></span>
</span>
;; Better default modes</span></span>
(</span>electric-pair-mode</span> t</span>)</span></span>
(</span>show-paren-mode</span> 1</span>)</span></span>
(</span>setq-default</span> indent-tabs-mode </span>nil</span>)</span></span>
(</span>save-place-mode</span> t</span>)</span></span>
(</span>savehist-mode</span> t</span>)</span></span>
(</span>recentf-mode</span> t</span>)</span></span>
(</span>global-auto-revert-mode</span> t</span>)</span></span>
</span>
;; Better default settings</span></span>
(</span>require</span> '</span>uniquify</span>)</span></span>
(</span>setq uniquify-buffer-name-style </span>'</span>forward</span></span>
      window-resize-pixelwise t</span></span>
      frame-resize-pixelwise t</span></span>
      load-prefer-newer t</span></span>
      backup-by-copying t</span></span>
      custom-file </span>(</span>expand-file-name</span> "custom.el"</span> user-emacs-directory</span>))</span></span>
(</span>add-hook</span> '</span>prog-mode-hook</span> '</span>display-line-numbers-mode</span>)</span></span>
</span>
;; Refresh package archives (GNU Elpa)</span></span>
(</span>require</span> '</span>package</span>)</span></span>
(</span>unless</span> package-archive-contents</span></span>
  (</span>package-refresh-contents</span>))</span></span></code></pre>
I'm not going to walk through each line of code here, you can do that yourself
with the built-in Emacs help system. Use M-x describe-function</code> or
M-x describe-variable</code>:</p>
M-x describe-function menu-bar-mode</span></span>
</span>
M-x describe-variable window-resize-pixelwise</span></span></code></pre>
Or equivalently,</p>
C-h f menu-bar-mode</span></span>
</span>
C-h v window-resize-pixelwise</span></span></code></pre>
It's best to get acquainted with the
Emacs help system</a>
and learn how to find help within Emacs itself. Later on you'll install
vertico</a> and
marginalia</a>, two packages that make
navigating the minibuffer for commands (like M-x</code>) much more enjoyable.</p>
Packages</h2>
With those settings out of the way, we're going to install some packages. All of
these packages are available on the default Emacs package server,
GNU Elpa</a>. If you'd like to configure alternatives, like
MELPA, consult the docs</a>.</p>
;; Great looking theme</span></span>
(</span>use-package</span> modus-themes</span></span>
  :</span>ensure t</span></span>
  :</span>init</span></span>
  (</span>modus-themes-load-themes</span>)</span></span>
  :</span>config</span></span>
  (</span>modus-themes-load-vivendi</span>))</span></span>
</span>
;; Code completion at point</span></span>
(</span>use-package</span> company</span></span>
  :</span>ensure t</span></span>
  :</span>hook</span> (</span>after-init </span>.</span> global-company-mode</span>)</span></span>
  :</span>custom</span></span>
  (</span>company-idle-delay </span>0</span>))</span></span>
</span>
;; Better minibuffer completion</span></span>
(</span>use-package</span> vertico</span></span>
  :</span>ensure t</span></span>
  :</span>custom</span></span>
  (</span>vertico-cycle t</span>)</span></span>
  (</span>read-buffer-completion-ignore-case</span> t</span>)</span></span>
  (</span>read-file-name-completion-ignore-case</span> t</span>)</span></span>
  (</span>completion-styles</span> '(</span>basic substring partial-completion flex</span>))</span></span>
  :</span>init</span></span>
  (</span>vertico-mode</span>))</span></span>
</span>
;; Save minibuffer results</span></span>
(</span>use-package</span> savehist</span></span>
  :</span>init</span></span>
  (</span>savehist-mode</span>))</span></span>
</span>
;; Show lots of useful stuff in the minibuffer</span></span>
(</span>use-package</span> marginalia</span></span>
  :</span>after vertico</span></span>
  :</span>ensure t</span></span>
  :</span>init</span></span>
  (</span>marginalia-mode</span>))</span></span></code></pre>Next steps</h2>
Save your configuration file, close and re-open Emacs. Time to experiment!</p>
If you have an LSP server already installed, e.g. solargraph for Ruby, browse to
a source file and activate eglot</a> with
M-x eglot</code>. You can ensure this happens automatically by adding an
eglot-ensure</code> hook to your Emacs configuration:</p>
(</span>use-package</span> eglot</span></span>
  :</span>ensure t</span></span>
  :</span>hook</span> (</span>ruby-mode</span> .</span> eglot-ensure</span>))</span></span></code></pre>
From here, it's really up to you to explore and learn on your own. Here are some
suggestions to help you along:</p>

Read about
Basic Editing Commands</a></li>
Read about
Working with Projects</a></li>
Read about
Dired, the Directory Editor</a></li>
Browse my other Emacs posts</a></li>
Check out Mickey Peterson's Mastering Emacs</a></li>
</ul>


Case Study: Zach Gage
2023-01-15T00:00:00+00:00
Lately I've been playing a ton of Knotwords</a>, an
intensely clever puzzle game that is conceptually distinct from crossword
puzzles but rides some of the same highs and lows. The game was created by Zach
Gage and Jack Schlesinger, a duo behind several other standout App Store hits
that carry many aesthetic and conceptual similarities.</p>
With such a strong portfolio</a>, I figured that
there must be something I can learn by digging a bit into Zach Gage's interview
and GDC material. What I came away with are five or so design principles that
are present in some of his more recent games.</p>
Subway legibility</h2>
A term coined in his
GDC 2018 talk</a>, subway
legibility is the ability for someone to understand a game by observing it over
the shoulder of someone else playing it on the subway.</p>
Many of Zach's aesthetic design decisions are based on this principle,
communicating information in such a way that a quick glance exposes the core
game mechanisms. The onlooker should be intrigued by the puzzle presented on the
screen, as opposed to overwhelmed by clutter and detail.</p>
This principle is the enemy of a busy user interface (UI). Zach breaks game UIs
down with a method called the "three reads":</p>

The first glance should convey the important bits, pulling you in.</li>
The second glance should add supporting detail without overwhelming.</li>
The third fills in the rest.</li>
</ol>
The designer can employ techniques of font size, UI composition, and point of
view to help reinforce the three reads.</p>
Successful legibility exposes the most important details first and foremost. In
Knotwords, this is the arrangement of words and letters in the grid. Secondary
are key details that support the core game components. To follow the same
example, the dotted-lines and letter superscripts that denote the Knotwords
puzzle constraint. Finally are necessities that are unimportant to the gameplay,
e.g. the main menu button.</p>
Exploratory design process</h2>
In his
Playdate developer interview</a>,
Zach discusses his exploratory design process.</p>

Usually the experience I have is I'm playing a game, and one cool thing
happens--or, one cool thing almost happens. Then it's like 'oh, is there a way
I could've engineered that within the mechanics?'</p>
</blockquote>
The gist of the interview is leaving yourself enough room to explore game
mechanics that emerge from gameplay, mechanics that often lead you down
completely unanticipated avenues. When these surprising moments are discovered
during the design process, make sure to double-down on them and expose them to
the player.</p>
This idea reminds a lot of the advice given by Jonathan Blow and Marc Ten Bosch
in their IndieCade 2011 talk</a>.
They title the presentation "Designing to Reveal The Nature of the Universe" and
the central idea is much the same as what Zach discusses in the above quote.</p>
When designing levels for your game, there will inevitably be situations where
unanticipated interactions arise and expose interesting extensions of your core
game ideas. When these moments do arise, it's critical to invest yourself fully
in uncovering what spurred on the interest and excitement. That epiphany is the
kernel of good level design, and it's the level designer's responsibility to
demonstrate it to the player and deliver the same euphoric effect.</p>
Gesture-forward controls</h2>
Another consistent quality of Zach's games is attention to control mechanisms
that are unique to the mobile platform. For example, in Knotwords there's a
great usability feature that hinges on a directional swipe. Swipe horizontally
from your current square and letters are entered left-right. Swipe vertically
and letters are entered top-bottom.</p>
For a game that is fundamentally about typing letters into an asymmetrical grid,
swapping between left-right and top-down is a critical feature. It's hard to
explain how this little gesture changes the overall usability of the game,
unless you have some experience with the NYT Crossword app.</p>
In NYT Crossword you swap letter direction by tapping on your current square.
Since a tap simply toggles between two states, if you tap one time too many you
effectively undo the change. This leads to a very frustrating experience where
you enter in a stream of letters in the wrong direction because you fat-fingered
a square.</p>
With Knotwords, there's no way to fall into this problem because the swipe is
directional--swiping twice in the same direction makes no difference. This is
just one example of the many unique control mechanisms in Zach's games, each
designed to work around common usability issues.</p>
Unobtrusive tutorialization</h2>
The first time I played through Good Sudoku</a> I
was extremely impressed by the tutorialization. Most textual explanations are
tucked away in little icons next to their respective control. If you interact
with the icon, you trigger the tutorial. Otherwise you can just play the game.</p>
I imagine this design is heavily catered to the mobile game market. With so many
freemium apps competing for users, developers want to ensure their app holds the
user's attention past the 30-second first-time user experience. Obstructive
tutorials and unskippable videos are probably the top two reasons I will
immediately close an app, never to play it again.</p>
Of course, it's entirely possible that no tutorials are just as bad,
particularly if a user is dropped into the middle of a game they have no idea
how to play. I think Zach's UI design and "subway legibility" do a lot of heavy
lifting in this space. Designs that are easy to read serve a dual purpose: they
capture the user's attention and they communicate core game mechanics. Without
good legibility, it would be much harder to belay tutorials in favor of player
exploration.</p>
Elevator pitch</h2>
When you first open up Knotwords or Good Sudoku, you're presented with a short
textual blurb from Zach describing his design goals and the game's origin. It's
a nice, personalized message that helps introduce the player to the game while
emphasizing its uniqueness.</p>
Not only does this set Zach's apps apart from others in the App Store, it
demonstrates the clarity of game design carried throughout the development
process. The message strikes me as a confident appeal: the game in your hands
isn't a product of random chance and a lucky idea, but of careful design and
focused effort.</p>
Conclusion</h2>
There's probably more to unpack from Zach Gage's games, but this post summarizes
what I've been thinking about while playing Knotwords and Good Sudoku. These
games are certainly small in scope and heavily rooted in the puzzle genre, but I
think that the core principles are generally applicable to game designers of all
types.</p>
While Knotwords and Good Sudoku are simple games, it's too easy to dismiss
simplicity as an easy road while missing the long path of careful design that
came before it.</p>


Advent of Code with Common Lisp
2022-12-19T00:00:00+00:00
One observation I've had working through
Advent of Code</a> with Common Lisp is that the LOOP</code>
macro is an absolute powerhouse.</p>
When first learning Common Lisp, it's common to hear that the language is
actually comprised of three separate languages: Common Lisp, FORMAT</code>, and
LOOP</code>. Common Lisp itself is made up of the parenthetical soup that is easily
recognizable. FORMAT</code> and LOOP</code>, on the other hand, each have their own
bespoke syntax that looks next to nothing like Lisp.</p>
Although the unique syntax of FORMAT</code> and LOOP</code> brings a learning curve on top
of Common Lisp itself, both tools bring an incredible amount of power to the
language. LOOP</code> in particular has been fantastically useful in this year's
Advent of Code.</p>
Most Advent of Code exercises involve (a) reading lines of data from a file and
(b) accumulating or counting some result from the data. This sort of operation
is handled very gracefully by LOOP</code>.</p>
Here's a simple example from Day 2, summing scores from a file:</p>
(</span>defun</span> score</span> (line) ...)</span></span>
</span>
(</span>with-open-file</span> (in </span>"day02.txt"</span>)</span></span>
  (</span>loop</span> for line </span>=</span> (</span>read-line</span> in </span>nil</span>)</span></span>
        while line</span></span>
        summing (score line) into total</span></span>
        finally (</span>return</span> total)))</span></span></code></pre>
Within the LOOP</code> macro, I'm reading one line from the input file at a time,
storing it into the variable, LINE</code>. After checking that the LINE</code> is
non-empty or EOF, I pass it into the SCORE</code> function. The result of that
function call is accumulated into a variable, TOTAL</code>, which is incremented on
each iteration of the loop. Finally, once the entire file is processed (and
LINE</code> is NIL</code>) I return TOTAL</code>.</p>
Not very "Lispy", but very expressive and readable.</p>
Day 12 has a more complex example. The following loops over all possible
starting positions for a graph (the input) and determines the path to the given
endpoint via a breadth-first search. While collecting these paths, the macro
saves the shortest path into a variable, MIN</code>, then returns it as the result.
This variable is compared against all iterations, only changing value if the
iteration is less than the stored result.</p>
(</span>defun</span> bfs</span> (start end) ...)</span></span>
</span>
(</span>loop</span> for start in </span>*starting-positions*</span></span>
      for path </span>=</span> (bfs start </span>#\E</span>)</span></span>
      when</span> (</span>not</span> (</span>null</span> path))</span></span>
      minimizing (</span>length</span> path) into </span>min</span></span>
      finally (</span>return</span> (</span>1- min</span>))</span></span></code></pre>
Note that you can assign as many iterators as you want by adding additional
for VAR = EXPRESSION</code>. You can similarly accumulate iterators from an
automatically incremented value, like an index: for VAR from 0</code>.</p>
Another cool feature is the ability to loop over successive CDR</code>s of a list.
This feature was super handy for Day 13, when I needed to zip together pairs
from a list of inputs:</p>
(</span>loop</span> for el on </span>'</span>(a b c d e f)</span></span>
      if (</span>and</span> (</span>>=</span> (</span>length</span> el) </span>2</span>)</span></span>
              (</span>=</span> (</span>mod</span> (</span>length</span> el) </span>2</span>) </span>0</span>))</span></span>
        collect (</span>subseq</span> el </span>0 2</span>))</span></span>
</span>
;; Result: ((A B) (C D) (E F))</span></span></code></pre>
When looping via on</code>, the value bound into EL</code> is the CDR</code> of that list,
similar to calling NTHCDR</code> with the index of that iteration:</p>
(</span>nthcdr</span> 0 '</span>(a b c d))</span></span>
;; '(a b c d)</span></span>
</span>
(</span>nthcdr</span> 1 '</span>(a b c d))</span></span>
;; '(b c d)</span></span>
</span>
(</span>nthcdr</span> 2 '</span>(a b c d))</span></span>
;; '(c d)</span></span></code></pre>
By collecting SUBSEQ</code>, I'm only collecting a slice of the list from the
starting index to the end, forming pairs of two.</p>
(</span>subseq</span> '</span>(a b c d) </span>0 2</span>)</span></span>
;; '(a b)</span></span></code></pre>
Combine these two things, and protect against out-of-index errors, and pairs are
achieved. A two-length slice is collected on each iteration from consecutive
CDR</code>s of the list.</p>
The LOOP</code> rabbit hole goes far deeper than what's shown in this post. A chapter
of Peter Seibel's Practical Common Lisp</em> has an entire chapter dedicated to the
macro, the aptly named
LOOP for Black Belts</a>.</p>


Why not Doom Emacs?
2022-11-12T00:00:00+00:00
The thing I credit most for sticking with Emacs after several failed attempts is
building my own configuration [from
scratch]({{ '/words/2022-05-02-learning-emacs' | url }}). Not only was the
project easier than expected, it left me with the distinctive fullness created
by the product of joyful work.</p>
My previous experiments with frameworks like
Doom Emacs</a> or
Spacemacs</a> were dropped shortly after the first
sign of trouble. It was hard not to feel overwhelmed by the complexity of the
ecosystem and frustrated by my inability to troubleshoot my own problems.</p>
Don't get me wrong, Emacs frameworks offer compelling benefits for the lazy
hacker. They pack in loads of sensible defaults, equip you with a sweet-looking
UI, and offer modern language support out-of-the-box. Doom Emacs has over 15k
stars on Github and it's not just because of the adorable cacodemon in the
README</a>.</p>
That said, if you're anything like me you'll quickly become overwhelmed after
installing Doom Emacs for the first time. Perhaps your installation doesn't
quite work, so you have to fix a few problems with bin/doom doctor</code>. Maybe you
want to change your fonts, so you dig through the documentation until you
stumble upon the
FAQ</a>.
Inevitably the framework that you installed to shortcut learning Emacs may not
be as quick and easy as you expected.</p>
Even with frameworks, there is no escaping the need to learn Emacs fundamentals
to configure the editor to match your expectations. However, frameworks make the
process of learning these fundamentals more difficult by greatly increasing the
complexity space of your editor and introducing more points of failure.</p>
That's why I recommend Emacs beginners start their journey with vanilla Emacs.</p>

Frameworks front-load learning the framework over learning Emacs</li>
New points of failure make diagnosing problems "the Emacs way" more difficult</li>
Framework defaults may not match your needs and expectations</li>
Modern (28+) vanilla Emacs isn't as bad as you think</li>
Emacs principles will serve you well if you adopt a framework later</li>
</ul>
If you're looking to get started with vanilla Emacs, I recommend diving into the
System Crafters tutorials</a> and kickstarting your
configuration with a
few defaults</a>.</p>


LSP with Emacs 29
2022-10-29T00:00:00+00:00
Eglot</a>, an Emacs package that integrates
the
language server protocol</a>
(LSP) into Emacs, was just merged into
Emacs main</a>.
It joins tree-sitter</a> and
use-package</a> as another reason to be
excited about the Emacs 29 release.</p>
This post aims to answer some common questions I observed in recent discussions
around the Eglot merge. In particular, what is LSP and how do alternatives
compare to Eglot?</p>
What is LSP?</h2>
LSP was originally designed to provide IDE language features to Visual Studio
Code, e.g., "Go to definition" or "Find references" popups. The project was
later open sourced by Microsoft and now has a
formal specification</a>.</p>
The protocol came out of the need to design an editor-specific compiler that
prioritizes the features programmers care about when actively writing code, as
opposed to compilers that work with code that is already written. While such a
compiler can be built on an ad-hoc basis for a specific IDE, it is difficult to
share that work with other editors that may be built using a different
programming language. With LSP, the compiler is run in an
independent process</a>
that communicates to the editor via messages, serialized as JSON.</p>
Decoupling the language server implementation from the editor or extension
implementation is a great move that has seen a
broad level of adoption</a> in the
editor space, even outside of Visual Studio Code. And now with Emacs 29, we have
support built into Emacs.</p>
Why was Eglot merged instead of alternatives?</h2>
Two primary reasons come to mind:</p>

Free Software Foundation (FSF) licensing</li>
Idiomatic Emacs Lisp and package standards</li>
</ol>
The former reason refers to the
GNU requirement</a> that
"legally significant</a>"
contributions (e.g. 15+ LOC) are accompanied by signed paperwork. If you've ever
tried contributing to an Emacs package that lives in Emacs main you're probably
already familiar with the process of submitting a request, signing the
documents, and sending them in for approval.</p>
Since the nature of this requirement extends to all contributors of an Emacs
package, it can be difficult to gain approval to merge a new package into Emacs
main without requiring copyright from the beginning. Otherwise, package
maintainers will need to hunt down contributors to get them to sign the relevant
paperwork (see
use-package#282</a> as an
example).</p>
The secondary reason has to do with Eglot's implementation. Compared to
alternatives, Eglot doesn't depend on any packages external to Emacs and
integrates nicely with existing Emacs tools like
Flymake</a>,
Xref</a>,
etc. These qualities make it easier to merge and ship with the standard Emacs
distribution.</p>
How do alternatives differ?</h2>
lsp-mode</h3>
The alternative I have the most experience with is
lsp-mode</a>, which I used for six or so
months before switching to Eglot. Unlike Eglot, lsp-mode has
no intention of being merged into Emacs main</a>,
allowing it some more flexibility in its design and implementation.</p>
Compared to Eglot, lsp-mode is the more maximal package. For one, it supports
the entire LSP specification. It also has a ton of extra features, including
bespoke UI</a>, non-ELPA package integrations
like dap-mode</a> and
dash</a>, and support for
multiple language servers</a>
for a single file.</p>
Whether you decide to pick lsp-mode over Eglot probably comes down to your
reaction to lsp-ui</a>. If you desire a
fully-featured IDE experience, lsp-mode will serve you well. Otherwise, you may
appreciate Eglot's simpler take.</p>
No matter which LSP package you pick, it's worth reading through lsp-mode's
performance documentation</a>.
It's beneficial no matter which LSP package you choose.</p>
lsp-bridge</h3>
lsp-bridge</a> aims to be "the
fastest LSP client in Emacs". Contributor Matthew Zeng recently gave an
introduction to the package at
EmacsConf 2022</a>, walking through
it's implementation and goals.</p>
In general, lsp-bridge aims to work around the single-threaded bottlenecks
present in Emacs and Emacs Lisp. Since LSP works via JSON RPC, most of the
performance issues are due to blocking IO and JSON parsing. lsp-bridge splits
processing into two threads to better handle asynchronous communication between
server and editor.</p>
The quest for performance comes with a cost, however, in that lsp-bridge
requires Python dependencies and ties its implementation to a specific
completion framework bundled with the package.</p>
tl;dr</h2>
Eglot is a rad LSP package that is now merged into Emacs main, staged for
release with Emacs 29. It's well worth giving it a try, even if you already use
lsp-mode. You may prefer its comparatively lightweight feel.</p>
Eglot</h3>

Minimalist implementation that "just works"</li>
Available out of the box with Emacs 29</li>
Development may slow down since it's now integrated in Emacs main</li>
No dependencies outside of Emacs</li>
</ul>
lsp-mode</h3>

Fully supports LSP specification</li>
Optional UI extras with lsp-ui</a></li>
Debugging support with dap-mode</a></li>
Support for Flycheck</a>, a Flymake
alternative</li>
Can be a pain to set up properly</li>
</ul>
lsp-bridge</h3>

Great performance at the cost of idiomatic Emacs conventions</li>
Coupled to a specific completion framework bundled with the package</li>
</ul>


Reading: The Puzzler
2022-09-22T00:00:00+00:00
Talking about The Puzzler</em> by A.J. Jacobs.</p>
If you can ignore Jacobs musings on the virtues of puzzling (which is, despite
the book's subtitle, mercifully light), The Puzzler</em> offers some entertaining
stories about puzzle fanaticism. Just don't go in expecting much else.</p>
Each chapter is about a blog-post's worth of content that follows a formula
common to every puzzle in the book. Most interesting are Jacobs's explorations
into puzzling esoterica, e.g. Kryptos</a>
or the MIT Mystery Hunt</a>. Although the formula gets
tiring quickly, Jacobs keeps it alive by offering up historical puzzles that the
reader can peruse on their own terms.</p>
None of what Jacobs provides would be so egregious if his tone and humor weren't
representative of the lowest common denominator of The New York Times</em> readers.
The repertoire of jokes at Jacobs disposal is seemingly limited to the political
and social circumstances of 2020, a time I'd much rather forget than reminisce
with the author's patronizing guidance.</p>
Moreover, his grand ideas on the applicability of puzzles to everyday life are
marred by his inclusions of "nerd culture" stereotypes. At one point Jacobs asks
a Rubik's Cube aficionado whether his "Rubik's Cube renown led to him dating the
head cheerleader" (31).</p>
Ultimately The Puzzler</em> is a disappointing read. Perhaps if the book were
instead a series of blog posts I would be more forgiving to its content and
meandering lack of purpose. But viewed as a whole, the book doesn't justify its
own existence.</p>
tl;dr</strong>: read Rex Parker</a> instead.</p>


Building Emacs from source on MacOS
2022-09-08T00:00:00+00:00
This is a guide for building Emacs from source for Mac OSX (tested on 12.4, M1)
with
native compilation</a>
enabled. If you don't want native compilation (though I highly recommend it),
feel free to drop the the --with-native-compilation</code> flag when you run the
./configure</code> script.</p>
Prerequisites</h2>

Xcode command line tools</li>
libgccjit</code></a>, required for native
compilation</li>
</ul>
Building Emacs</h2>
First, clone the repo (you can also use the
Github mirror</a> instead):</p>
git clone https://git.savannah.gnu.org/git/emacs.git</span></span></code></pre>
These next few steps are taken straight from the
INSTALL.REPO</a>
file in the source repository, with the addition of a few options during
configuration.</p>
Run autogen</h3>
After the code is pulled down, cd into the directory and run the autogen.sh</code>
script. This initial script generates another script (configure</code>) that you'll
use to actually configure the Emacs Makefile</code> to build on your OS.</p>
cd emacs/</span></span>
./autogen.sh</span></span></code></pre>Run configure</h3>
You can view all of the available options for configure</code> by passing in the
--help</code> flag:</p>
./configure --help</span></span></code></pre>
Here is the list of options that are recommended for Mac OS, compiled from
various</a>
sources</a>. I've included the
--help</code> output with each option:</p>

--with-native-compilation</code>: compile with Emacs Lisp native compiler support</li>
--with-json</code>: compile with native JSON support</li>
--with-ns</code>: use Nextstep (macOS Cocoa or GNUstep) windowing system. On by
default on macOS</li>
--with-xwidgets</code>: enable use of xwidgets in Emacs buffers (requires macOS
Cocoa,
more info</a>)</li>
--without-dbus</code>: don't compile with D-Bus support
(more info</a>)</li>
--without-compress-install</code>: don't compress some files (.el, .info, etc.)
when installing</li>
--disable-silent-rules</code>: enable verbose build output</li>
</ul>
Run the configure</code> script with these options to create the Makefile</code> you'll
use to build Emacs.</p>
./configure --with-native-compilation \</span></span>
            --with-json \</span></span>
            --with-ns \</span></span>
            --with-xwidgets \</span></span>
            --without-dbus \</span></span>
            --without-compress-install \</span></span>
            --disable-silent-rules</span></span></code></pre>
After this finishes, it's time to build Emacs proper.</p>
Build emacs</h3>

Note: if make</code> fails, take a look at "Troubleshooting" down below. Your best
bet is to run make bootstrap</code> instead.</p>
</blockquote>
make</span></span></code></pre>
This creates an Emacs binary at src/emacs</code>. You can verify that everything
worked properly by running emacs -Q</code>, launching it with no configuration.</p>
src/emacs -Q</span></span></code></pre>
After you've verified that everything is good to go, the last step is to
assemble Emacs.app</code> proper:</p>
make install</span></span></code></pre>
You'll notice that a hefty Emacs.app</code> application now lives in the nextstep/</code>
directory. Go ahead and move it into your /Applications/</code> directory.</p>
mv nextstep/Emacs.app /Applications/</span></span></code></pre>
I also like to include src</code> and lib-src</code> on PATH</code> so I can run Emacs from the
CLI (particularly important for emacsclient</code>):</p>
# Syntax for fish shell</span></span>
set PATH $HOME/projects/emacs/src $PATH</span></span>
set PATH $HOME/projects/emacs/lib-src $PATH</span></span></code></pre>
Congratulations, you have officially built Emacs from source!</p>
Next steps</h3>
With everything running smoothly, you're now ready to make your first
contributions to the Emacs codebase. Here are some excellent guides to get
started:</p>

Contributing to Emacs</a>
by Colin Woodbury</li>
Welcome, New Emacs Developers</a>
by Lars Ingebrigtsen</li>
</ul>
Best of luck, new Emacs contributor!</p>
Troubleshooting</h2>
If make</code> fails, one of the easiest ways to resolve most problems is to use the
bootstrap script instead:</p>
# Clean out any dangling build artifacts</span></span>
make clean</span></span>
</span>
make bootstrap</span></span></code></pre>
This is effectively a "slower and more thorough" build of the application, and
successfully resolved a few issues I ran into when I updated from Emacs 28
to 29.</p>


Reading: The Dispossessed
2022-08-13T00:00:00+00:00
Talking about The Dispossessed</em> by Ursula K. Le Guin.</p>
Before diving into the contents of this book, it's interesting to note that
Ursula K. Le Guin was a big fan of Taoism, big enough to publish
her own commentary</a> on
the Tao Te Ching. This perspective lends an additional layer of analysis when
discussing The Dispossessed</em>, making it difficult to discuss the book without
looking for influences from one to the other.</p>
In particular, where Taoism was a rejection of traditionalist and hierarchical
Confucianism, so too Odonian ethics a rejection of Urras capitalism. These
ethics embody principles that on a whole resemble those of Taoism, particularly
with their emphasis on work being a reward in and of itself, a rejection of
"egoism" and accomplishments aimed at elevating the image of self, and the
"acting to one's own nature" that is consistent with the lack of laws and
governmental structure on Anarres.</p>
In a way, Shevek can be portrayed as a Taoist Sage. Shevek keeps his theory
protected not for the pursuit of aggrandizement, but to release it
intergalactically such that all can benefit. "Hence the sage is able [...] to
accomplish his great achievements. It is through his not making himself great
that he can accomplish them" (p. 89 Tao Te Ching</em>).</p>
The relation to Taoism aside, what struck me most about this novel was its
achievement not as political commentary, but as an expression of empathy and
unity. Shevek's struggle with shared suffering and problems common to humans
forming communities of governance make for an excellent mirror for
self-reflection. None of the communities are without issue; the narrative lens
does not focus on perfection of institutions but rather the exploration of
learning from shared experience. An "ambiguous utopia" indeed.</p>


Emacs from scratch
2022-05-08T00:00:00+00:00

Update: I created Start Emacs</a> as an
easier way to get up and running with Emacs. It follows many of the same
principles in this guide and throws in some extras.
Check it out here</a></p>
</blockquote>
Four months after writing this article and I'm still using Emacs full-time with
my own, custom configuration. I continue to find great pleasure in extending my
setup with small snippets I stumble upon from Emacs hackers far wiser than
myself. Those tweaks aside, my
current configuration</a> is going strong.</p>
I maintain the opinion that creating your own Emacs configuration is not nearly
as daunting as is often presented. With a few tweaks to the base defaults you
can be up-and-running with an editor that looks and feels far closer to modern
alternatives. A few packages later and you're well on your way to Emacs nirvana.</p>
For those of you who have decided to build your own configuration from scratch:
enjoy the process! The greatest thing about Emacs is the satisfaction of
building a tool to suit your preferences. I hope this article helps you on that
journey.</p>
Original article</strong></p>
Like any self-respecting programmer, I often find myself struggling with text
editor envy. This time, like the three previous times, the source of that envy
is Emacs</a>. All it takes is a stray link to
emacsrocks</a> and I'm back in that vicious cycle.</p>
Unlike those previous flings, however, I have managed to stick to Emacs with a
new level of tenacity. I have even found myself enjoying</em> it.</p>
What has changed is my fundamental approach to learning Emacs. Rather than
reaching for a prebuilt distribution, like
doomemacs</a> or
spacemacs</a>, I decided to build my own configuration
from scratch.</p>
This effort, previously believed insurmountable, was easy and educational. With
just a few packages, I managed to match the functionality of my primary text
editor. Most importantly, I found myself reaching for Emacs's built-in help
system instead of scouring the web, reinforcing my familiarity with the tool and
accelerating my proficiency.</p>
Prebuilt distributions are an awesome demonstration of what is possible with
Emacs, but I don't think they're a good introduction to the editor. Instead, I
think the best way to get started with Emacs is with a minimum-viable
configuration. Just enough stuff to bring Emacs up to par with a modern editor
and nothing else.</p>
Follow along with the rest of this article and you'll have your own, very
capable Emacs ready for experimentation.</p>
First steps</h2>
After downloading Emacs</a>, I recommend
running through the built-in tutorial
(also available on the web</a>). Some
basic knowledge of Emacs keybindings will help make the rest of this guide
easier to follow.</p>
If looking at the default Emacs theme is too much to bear, swap to one of the
dark-mode themes:</p>
M-x load-theme RET deeper-blue</span></span></code></pre>

Remember: C-<chr></code> means hold the Control key while typing the character
<chr></code>. M-<chr></code> means hold the Meta key (Alt on Windows) and pressing
<chr></code>. (Emacs tutorial)</p>
</blockquote>
Rebind caps lock to control</h2>
One thing you'll quickly notice from the tutorial, if you weren't already aware
of Emacs pinky</a>, is that
pressing Control all of the time can get pretty taxing on your wrist. RSI is no
joke! Take care of those wrists.</p>
Rebind your Caps Lock key to Control and never look back.</p>
Instructions:
MacOS</a>,
Windows 10</a></p>
Start your configuration</h2>
All of your Emacs files will go into .emacs.d</code>, so go ahead and create a new
directory:</p>
# Cool stuff goes in here</span></span>
mkdir ~/.emacs.d/</span></span></code></pre>
Back in Emacs, make a new file with M-x find-file</code>, or the following
keybinding:</p>
C-x C-f ~/.emacs.d/init.el</span></span></code></pre>
This will create a new Emacs Lisp file, init.el</code>, in your Emacs configuration
directory. Emacs will automatically load this file on startup.</p>
From here, you can go ahead and start making some changes to your editor theme:</p>
;; Load a dark mode theme</span></span>
(</span>load-theme</span> '</span>deeper-blue t</span>)</span></span></code></pre>
Although many guides will recommend removing the ugly menu/tool bars at the top
of your editor, I think it's a good idea to keep them around until you're more
comfortable with Emacs keybindings. The very sight of them may offend your
sensibilities, but at least they can help you when you forget basic editor
functions.</p>
That said, if you want to remove them you can do so with the following code:</p>
;; Disable menu bar, scroll bar, and tool bar</span></span>
(</span>menu-bar-mode</span> -1</span>)</span></span>
(</span>scroll-bar-mode</span> -1</span>)</span></span>
(</span>tool-bar-mode</span> -1</span>)</span></span></code></pre>
After saving, you can apply the changes from your configuration file by closing
Emacs and re-opening it. Alternatively, you can apply the changes immediately in
Emacs by using the command M-x eval-buffer</code>.</p>
Sensible defaults</h2>
Once Emacs is themed to your preference, I'd recommend tweaking some of the
built-in settings with "better" defaults. Emacs has been around for a long time
(as you can probably tell by the default theme) and these settings put it more
in line with modern editors.</p>
My recommendations are either sourced from other configuration files I found in
the wild (better-defaults</a> and
crafted-emacs</a> are two great
examples) or from tweaking the performance of some CPU-intensive packages like
lsp-mode</a>.</p>
First up are some performance threshold tweaks that will help Emacs run faster
on a modern machine. Recall that you can look up the help documentation of any
of these variables by invoking C-h v</code>, or M-x describe-variable</code>.</p>
(</span>setq gc-cons-threshold </span>100000000</span>)</span> ; 100 mb</span></span>
(</span>setq read-process-output-max </span>(</span>*</span> 1024 1024</span>))</span> ; 1mb</span></span></code></pre>
The remaining recommendations are more personal in nature. I'd urge you to read
about each of these options and decide for yourself whether you'd like to
include them. In particular, you may find yourself enjoying the customization UI
that ships with Emacs
(M-x customize</code></a>)
more than me.</p>
;; Auto-refresh buffers when files on disk change.</span></span>
(</span>global-auto-revert-mode</span> t</span>)</span></span>
</span>
;; Ensure unique names when matching files exist in the buffer.</span></span>
;; e.g. This helps when you have multiple copies of "main.rs"</span></span>
;; open in different projects. It will add a "myproj/main.rs"</span></span>
;; prefix when it detects matching names.</span></span>
(</span>require</span> '</span>uniquify</span>)</span></span>
(</span>setq uniquify-buffer-name-style </span>'</span>forward</span>)</span></span>
</span>
;; Place backups in a separate folder.</span></span>
(</span>setq backup-directory-alist </span>`((</span>"."</span> .</span> "~/.saves"</span>)))</span></span>
(</span>setq auto-save-file-name-transforms </span>`((</span>".*" "~/.saves/"</span> t</span>)))</span></span>
</span>
;; I store automatic customization options in a gitignored file,</span></span>
;; but this is definitely a personal preference.</span></span>
(</span>setq custom-file </span>(</span>locate-user-emacs-file</span> "custom.el"</span>))</span></span>
(</span>when</span> (</span>file-exists-p</span> custom-file</span>)</span></span>
  (</span>load</span> custom-file</span>))</span></span></code></pre>Get ready for packages</h2>
While Emacs ships with a ton of useful features, we're all here for the
packages. This is the moment where you can really start turning your Emacs from
text editor status into full-blown operating system.</p>
By default, Emacs comes with a curated package registry in the form of
GNU Elpa</a>. You'll want to extend this default list of
packages with those from a larger, also curated list called
MELPA</a>. With these two lists (and Emacs's built-in
packages), you can find just about everything you'll ever need.</p>
Add the following lines to your ~/.emacs.d/init.el</code>:</p>
;; You'll be installing your packages with the</span></span>
;; built-in package.el script</span></span>
(</span>require</span> '</span>package</span>)</span></span>
</span>
;; Add MELPA to your list of package archives</span></span>
(</span>add-to-list</span> '</span>package-archives</span></span>
	         '(</span>"melpa"</span> .</span> "https://melpa.org/packages/"</span>))</span></span>
</span>
(</span>package-initialize</span>)</span></span>
</span>
;; Go ahead and refresh your package list to</span></span>
;; make sure everything is up-to-date</span></span>
(</span>unless</span> package-archive-contents</span></span>
  (</span>package-refresh-contents</span>))</span></span></code></pre>Install your first package</h2>
With MELPA ready to go, it's time to install your first package. Add the
following to your ~/.emacs.d/init.el</code>.</p>
(</span>unless</span> (</span>package-installed-p</span> '</span>use-package</span>)</span></span>
  (</span>package-install</span> '</span>use-package</span>))</span></span></code></pre>
use-package</code></a> is a very deliberate
first install, as you'll use it instead of package-install</code> to install all of
your other packages.</p>
Why not just keep installing packages with package-install</code>? The reason has to
do with the customization that you'll add to the packages after you install
them.</p>
use-package</code> bundles your keybindings, custom variables, package hooks, and
dependencies together in a convenient and well-organized API. While you could
manage all of these details manually, it's very convenient to use use-package</code>
instead. It makes it easier to install new packages while keeping your init.el</code>
organized and clean.</p>
The importance of text completion</h2>
I know you're excited to install packages, but forgive me for a brief aside. By
far the most important thing to configure in Emacs is your
completion framework</a>.
Doing so will not only make Emacs more familiar when coming from existing
editors, it will drive your ability to teach yourself Emacs from within Emacs</em>.</p>
But before you grab a text completion package off the internet, I think it's
helpful to take a look at Emacs's built-in capabilities. Doing so will help you
make some informed decisions about what features you'd like a text completion
framework to fulfill.</p>
That said, the completion framework ecosystem within Emacs is nuanced and
idiosyncratic, but I'll try my best to break it down.</p>
When you attempt any operation that prompts you for text in Emacs, you'll be
presented with a
minibuffer</a>
asking for you to fill in that information. Oftentimes that information will be
the path to a file or an Emacs Lisp function. In either of these cases it's
vastly preferable to have Emacs fill in your text so you don't have to type it
all in yourself (hence, completion).</p>
With the default Emacs completion framework, you allow Emacs to fill in text for
you by mashing the TAB</code> key endlessly. Go ahead and try it: C-x C-f</code>, begin
typing a path, then have Emacs autocomplete it with TAB TAB</code>. Even worse is
looking up an Emacs command with M-x</code>. Try M-x find TAB TAB</code>. Functional,
sure. But also a surefire path to RSI.</p>
Luckily there are a few built-in alternatives, a subject to which Mickey
Peterson
dedicates an entire blog post</a>.
I'll mention one here that is a personal favorite, fido-vertical-mode</code> which
uses Emacs
icomplete</a>
under the hood.</p>
Give it a try and you'll immediately notice the difference:</p>
M-x fido-vertical-mode</span></span></code></pre>
Try to lookup an Emacs command like M-x find-file</code>. It even includes the
keybindings in the margin!</p>
This exact benefit is the reason I dedicated an entire section of this guide to
your chosen completion framework. It makes it infinitely easier to lookup Emacs
commands when searching for documentation or trying to remember the keybindings.</p>
Vertico and Marginalia</h2>
Now, if fido-vertical-mode</code> works for you, great! No need to install a separate
completion framework. However I find that an alternative,
Vertico</a>, offers both better performance and
greater features.</p>
Vertico is built by Daniel Mendler</a> and integrates
nicely into other tools by the same author, as well as Emacs built-ins. One I'll
recommend alongside Vertico is
Marginalia</a>, a package that adds more
annotations to your completions. Similar to the keybindings in the earlier
example with M-x find-file</code>, Marginalia displays the beginning of the entire
docstring.</p>
Install the packages with use-package</code>:</p>
(</span>use-package</span> vertico</span></span>
  :</span>ensure t</span></span>
  :</span>init</span></span>
  (</span>vertico-mode</span>))</span></span>
</span>
(</span>use-package</span> marginalia</span></span>
  :</span>after vertico</span></span>
  :</span>ensure t</span></span>
  :</span>init</span></span>
  (</span>marginalia-mode</span>))</span></span></code></pre>
Finally, I like to throw savehist</code> in there as well so my recent completions
appear at the top of the minibuffer. This one omits :ensure t</code> since it ships
with Emacs.</p>
(</span>use-package</span> savehist</span></span>
  :</span>init</span></span>
  (</span>savehist-mode</span>))</span></span></code></pre>Finding Help</h2>
Your choice of completion framework is a huge benefit when learning Emacs, as
the entire library of Emacs commands is available at your fingertips with M-x</code>.
As soon as I discovered Vertico and Marginalia I threw out my Emacs cheatsheet.
When all of Emacs's documentation is so easily accessible, there's really no
reason to keep one around for reference.</p>
When it comes to reaching out to Emacs for help, remember the following:</p>

You can execute any Emacs command with M-x <command></code>.</li>
Keybindings are available in the minibuffer thanks to Marginalia, but you can
also discover them with M-x where-is RET <command></code>.</li>
You can view the documentation of any command you know how to press with
C-h c</code>. Try C-h c RET C-x C-f</code>.</li>
C-h ?</code> is an all-encompassing help menu for you to get your bearings.</li>
</ol>
As long as you're familiar with basic Emacs terminology (e.g. buffers, windows,
and frames) every Emacs command is available to you with a quick search.</p>
Project management with project.el</h2>

Edit</strong>: This used to be a section about
Projectile</a>, a package that provides
project navigation utilities to Emacs. Since writing this article, I've
actually found the default Emacs package project.el</code> to be a completely
viable alternative, no extra package needed. YMMV, so definitely check out
Projectile if you need more than is provided by project.el</code>.</p>
</blockquote>
Navigating files with C-x C-f</code> is incredibly cumbersome, particularly for large
projects. Far better is the Emacs Project framework,
project.el</a>.
As long as you have a project that is initialized with git</code>, project.el</code> lets
you search files with minibuffer completion, grep queries with
xref</a>, and
manage directories with
dired</a>.</p>
First, open up a project by browsing to a version-controlled file with
C-x C-f</code>. You'll now be able to use the project.el</code> commands to navigate this
project:</p>

C-x p f</code>: Visit a file in the current project.</li>
C-x p g</code>: Grep a query across all files in the current project.</li>
C-x p d</code>: Open dired in the chosen directory.</li>
</ul>
As soon as you've opened a project one time, it'll be available in the project
cache. You can browse any previously-visited projects on your system with
C-x p p</code>.</p>
Next steps</h2>
With use-package</code>, Vertico</code>, and the basics of project.el</code> under your
fingertips, you're ready to explore the rest that Emacs has to offer. Here are a
few branching points that I would suggest based on your goals.</p>

If you want your Emacs experience to have IDE-like code-completion, look into
company-mode</a> and
eglot</a>.</li>
If you want to be amazed by one of the best git interfaces in the world of
text editors, dive into Magit</a>.</li>
If you're interested in org-mode</a> and follow the
Zettelkasten hype train, read all about org-roam</a>
or denote</a>.</li>
</ul>
Outside of new packages, I also recommend reading some open source Emacs
configurations that are out in the wild. Here are a few projects I've taken
inspiration from:</p>

Technomancy's
Better defaults</a></li>
System Crafter's
Crafted Emacs</a></li>
</ul>
Welcome to your new Emacs journey!</p>


Clean git
2022-02-12T00:00:00+00:00
Well-organized commits are a treat. They are your guide to the theory of
developers come and gone, a ledger filled with important decisions. Knowing how
to structure commits into a readable, retrievable, and reviewable history is one
of the keys to a maintainable codebase.</p>
Compare a change request (CR) with the following commits:</p>
8e74f78 Add new button feature WIP</span></span>
</span>
47e9c34 Fix linter</span></span>
</span>
b409804 Finish button feature</span></span>
</span>
0643984 Cleanup</span></span></code></pre>
To one with more detail, yet fewer commits:</p>
8e74f78 feat: Add disabled state to button</span></span>
</span>
47e9c34 fix: Button tooltip and disabled state clash</span></span>
</span>
When a button has a tooltip and is disabled, ensure that the tooltip</span></span>
theme matches that of the disabled state.</span></span></code></pre>
Before even looking at the code, which CR would you prefer reviewing?</p>
This isn't a lesson on how to write good commits, because
cbeams has that down to a science</a>. Instead, this
post covers the tools and workflows that make writing good commits easier.</p>
Responding to CR comments</h2>
There are few experiences more frustrating than using git blame</code> on a line of
code, praying some amount of insight can save your lack of understanding, only
to be met with "PR changes".</p>
def</span> add_ten</span>(</span>v</span>)</span></span>
  # git blame: You, 3 years ago. "PR changes"</span></span>
  if</span> something_that_has_nothing_to_do_with_anything</span></span>
    v </span>+</span> 15</span></span>
  else</span></span>
    v </span>+</span> 10</span></span>
  end</span></span>
end</span></span></code></pre>
Please do not create, let alone merge, commits titled "PR changes". Instead,</p>

use
fixup commits</a>
during the CR review to inform your reviewer of changes</li>
use
interactive rebasing</a>
to squash your fixups into the commits they're fixing</li>
</ul>
Fixing commits</h3>
The temptation to create the "PR changes" commit comes from a good place. You
don't want to force push</code> your branch, because it makes it hard to re-review
changes and breaks local collaborators. Moreover, those commits aren't really
doing anything new—they're just fixing what you wrote previously.</p>
Fixups offer a better way. Say you have the following commits in CR:</p>
$ git log --oneline</span></span>
b409804 feat: Disable form on validation</span></span>
8e74f78 feat: Add disabled state to button</span></span>
22e8539 Initial commit</span></span></code></pre>
Your CR reviewer points out a bug introduced by your button component, so you
make the changes and stage them:</p>
$ git status -s</span></span>
M Button.tsx</span></span></code></pre>
Your new changes are necessary to fix your prior commit, "feat: Add disabled
state to button", and don't belong as a separate thought. Instead of creating a
new commit manually, use git commit --fixup <SHA></code>, indicating that your
changes fix a prior commit:</p>
$ git commit --fixup 8e74f78</span></span>
[main e69dff9] fixup! feat: Add disabled state to button</span></span>
 1 file changed, 1 insertion(+), 1 deletion(-)</span></span>
</span>
$ git log --oneline</span></span>
e69dff9 fixup! feat: Add disabled state to button</span></span>
b409804 feat: Disable form on validation</span></span>
8e74f78 feat: Add disabled state to button</span></span>
22e8539 Initial commit</span></span></code></pre>
With --fixup</code>, git automatically creates a new commit for you with a special
fixup!</code> prefix. The rest of the commit's title is identical to the one it's
fixing.</p>
Now you're ready to git push</code> that branch and await your CR approval.</p>
Squashing fixups for clean history</h3>
Fixups are great for CRs, but you don't want them to clutter your project's
history. After CR approval, you need to perform an extra step before you can
merge your CR into the main branch.</p>
Use interactive rebase with the --autosquash</code> option to automatically squash
your fixup commits into their respective targets:</p>
$ git log --oneline</span></span>
e69dff9 fixup! feat: Add disabled state to button</span></span>
b409804 feat: Disable form on validation</span></span>
8e74f78 feat: Add disabled state to button</span></span>
22e8539 Initial commit</span></span>
</span>
$ git rebase --interactive 22e8539 --autosquash</span></span></code></pre>
Within the interactive rebase window, your fixup!</code> commits are automatically
repositioned with the fixup</code> action (instead of pick</code>):</p>
pick 8e74f78 feat: Add disabled state to button</span></span>
fixup e69dff9 fixup! feat: Add disabled state to button</span></span>
pick b409804 feat: Disable form on validation</span></span></code></pre>
Once you save this window your fixup commits are squashed into their target
commits and your history is left clean:</p>
$ git log --oneline</span></span>
b409804 feat: Disable form on validation</span></span>
8e74f78 feat: Add disabled state to button</span></span>
22e8539 Initial commit</span></span></code></pre>
Now you can git push --force</code> this branch and merge it into main.</p>
Unwinding over-eager commits</h2>
Sometimes you're in a rush to get your changes up on the server, so you throw
all of your changes into one big "WIP" commit:</p>
$ git commit -am "WIP"</span></span></code></pre>
That's fine for local development, but as soon as you expect someone to review
your CR you had better break apart your history into something meaningful.</p>
A common strategy is to reset your changes and commit the files one-by-one:</p>
$ git reset HEAD~1</span></span>
</span>
$ git status -s</span></span>
M Button.tsx</span></span>
M Form.tsx</span></span>
?? helper.ts</span></span>
</span>
$ git add Button.tsx</span></span>
$ git commit -m "feat: Add disabled state ..."</span></span></code></pre>
This strategy works great when every change to a file represents the same
thought. But what about when you make two very different changes to the same
file?</p>
As a contrived example, say you have two new additions to a Rails controller:</p>
$ git diff</span></span>
@@ -1,3 +1,9 @@</span></span>
 class PostsController < ApplicationController</span></span>
+  def index</span></span>
+    @posts = Post.all</span></span>
+  end</span></span>
</span>
+  def new</span></span>
+    @post = Post.new</span></span>
+  end</span></span>
 end</span></span></code></pre>
Adding this file in one go makes it harder to describe the commit since you're
changing two different and unrelated pieces of code.</p>
Rather than staging the entire file, you want to stage each method separately.
To do this, pass in the --patch</code> option when adding the file. This enters
interactive patch mode</a>,
which allows you to add your changes as separate units. Each unit is referred to
as a hunk.</p>
$ git add --patch</span></span>
@@ -1,3 +1,9 @@</span></span>
 class PostsController < ApplicationController</span></span>
+  def index</span></span>
+    @posts = Post.all</span></span>
+  end</span></span>
</span>
+  def new</span></span>
+    @post = Post.new</span></span>
+  end</span></span>
 end</span></span>
(1/1) Stage this hunk [y,n,q,a,d,s,e,?]?</span></span></code></pre>
In interactive mode, you're brought to a screen that looks very similar to a
normal git diff</code>, with the addition of a "Stage this hunk" question at the
bottom.</p>
You don't want to stage this hunk as-is. Instead, you want to split it apart
(s):</p>
(1/1) Stage this hunk [y,n,q,a,d,s,e,?]? s</span></span>
Split into 2 hunks.</span></span>
@@ -1,2 +1,5 @@</span></span>
 class PostsController < ApplicationController</span></span>
+  def index</span></span>
+    @posts = Post.all</span></span>
+  end</span></span>
</span>
(1/2) Stage this hunk [y,n,q,a,d,j,J,g,/,e,?]?</span></span></code></pre>
When you split a hunk, git will automatically divide the changes into two
smaller pieces. After splitting, you can see that the preview window shows (1/2)
instead of (1/1), indicating that you have two separate hunks ready to stage.</p>
Enter yes (y) on the first hunk and no (n) on the second, staging the changes
made to "index" but not the changes made to "new":</p>
(1/1) Stage this hunk [y,n,q,a,d,s,e,?]? s</span></span>
Split into 2 hunks.</span></span>
@@ -1,2 +1,5 @@</span></span>
 class PostsController < ApplicationController</span></span>
+  def index</span></span>
+    @posts = Post.all</span></span>
+  end</span></span>
</span>
(1/2) Stage this hunk [y,n,q,a,d,j,J,g,/,e,?]? y</span></span>
@@ -2,2 +5,5 @@</span></span>
</span>
+  def new</span></span>
+    @post = Post.new</span></span>
+  end</span></span>
 end</span></span>
(2/2) Stage this hunk [y,n,q,a,d,K,g,/,e,?]? n</span></span></code></pre>
Take a look at your git status. You'll see that your original file has both
unstaged and staged changes, since you accepted the "index" hunk and declined
the "new" hunk:</p>
$ git status</span></span>
Changes to be committed:</span></span>
modified: app/controllers/posts_controller.rb</span></span>
</span>
Changes not staged for commit:</span></span>
modified: app/controllers/posts_controller.rb</span></span></code></pre>
Now you can create two commits, one for each method:</p>
$ git commit -m "feat: Add index"</span></span>
$ git add app/controllers/posts_controller.rb</span></span>
$ git commit -m "feat: Add new"</span></span></code></pre>Review</h2>
Commits are important for maintaining the health of your codebase and the sanity
of your CR reviewers. Remember these key tools:</p>

git commit --fixup <SHA></code>: apply your staged changes as fixes to an existing
commit with
fixup commits</a></li>
git commit --interactive <SHA> --autosquash</code>: automatically squash fixup
commits so they don't clutter your history with
interactive rebasing</a></li>
git add --patch</code>: stage changes with
interactive patch mode</a>
to split up changes that are made in the same file</li>
</ul>


Introducing ReScript
2022-01-10T00:00:00+00:00
A few weeks ago I revisited ReScript</a> and
experimented with the ecosystem during Advent of Code. I was pleased to discover
that the language is in a much better place than four years ago.</p>
Although I don't think I'll be writing ReScript in production any time soon, I
put together a presentation today to introduce it to my colleagues. Below is the
transcript of that presentation.</p>
What is it?</h2>
A strongly-typed language that compiles to JavaScript.</p>

Powered by OCaml</li>
Functional feel</li>
More of a TypeScript competitor than alternatives like
Elm</a>, PureScript</a>, or
ClojureScript</a>.</li>
</ul>
Why use it instead of TypeScript?</p>

Only cover a small, curated subset of JavaScript</li>
Types are sound (will not lie to you)</li>
Fast compilation</li>
Minimal type annotations</li>
Gradual adoption strategy</li>
Compiler optimizations</li>
</ul>
Emphasizes:</p>

Functions</a>
over classes</li>
Pattern matching</a>
over conditionals or virtual dispatches</li>
Data modeling</a>
(variants) over string abuse</li>
First class support for React</a></li>
</ul>
History</h2>
You may recognize this project under a different name,
Reason</a>.</p>

Used by Facebook Messenger</li>
Promised strong types w/ safe inference derived from OCaml</li>
Reason was just a syntax layer, BuckleScript was doing the real work</li>
BuckleScript was a fork of the OCaml compiler that output JS</li>
BuckleScript and Reason were two separate teams</li>
</ul>
Last year, BuckleScript rebranded to ReScript</a></strong>.</p>

Directly integrated Reason into BuckleScript</li>
Combined both teams under the same umbrella</li>
</ul>
Reason & BuckleScript are now united as ReScript</strong>.</p>
Syntax comparison</h2>
OCaml</h3>
type</span> tree</span> =</span> Leaf</span> of</span> int</span> |</span> Node</span> of</span> tree</span> *</span> tree</span></span>
</span>
let</span> rec</span> exists_leaf</span> test tree</span> =</span></span>
  match</span> tree</span> with</span></span>
  |</span> Leaf</span> v</span> -></span> test v</span></span>
  |</span> Node</span> (</span>left</span>,</span> right</span>)</span> -></span></span>
      exists_leaf test left</span></span>
      ||</span> exists_leaf test right</span></span>
</span>
let</span> has_even_leaf</span> tree</span> =</span></span>
  exists_leaf</span> (</span>fun</span> n</span> -></span> n</span> mod</span> 2</span> =</span> 0</span>)</span> tree</span></span></code></pre>Reason</h3>
type</span> tree</span> =</span></span>
  |</span> Leaf</span>(</span>int</span>)</span></span>
  |</span> Node</span>(</span>tree, tree</span>)</span>;</span></span>
</span>
let</span> rec</span> exists_leaf</span> =</span> (</span>test</span>,</span> tree</span>)</span> =></span></span>
  switch</span> (</span>tree</span>)</span> {</span></span>
  | Leaf(</span>v</span>) </span>=</span>> test(v)</span></span>
  | Node(left, right) =></span></span>
	  exists_leaf(test, left) || exists_leaf(test, right)</span></span>
  }</span>;</span></span>
</span>
let</span> has_even_leaf</span> =</span> tree</span> =></span></span>
	exists_leaf</span>(</span>n</span> =></span> n</span> mod</span> 2</span> ==</span> 0</span>,</span> tree</span>)</span>;</span></span></code></pre>ReScript</h3>
type</span> rec </span>tree</span> =</span></span>
  |</span> Leaf</span>(</span>int</span>)</span></span>
  |</span> Node</span>(</span>tree, tree</span>)</span></span>
</span>
let</span> rec</span> existsLeaf</span> =</span> (</span>test</span>,</span> tree</span>)</span> =></span></span>
  switch tree</span> {</span></span>
  | Leaf(</span>v</span>) </span>=</span>> test(v)</span></span>
  | Node(left, right) =></span></span>
		existsLeaf(test, left) || existsLeaf(test, right)</span></span>
  }</span></span>
</span>
let</span> hasEvenLeaf</span> =</span> tree</span> =></span></span>
	existsLeaf</span>(</span>n</span> => mod</span>(</span>n</span>,</span> 2</span>)</span> ==</span> 0</span>,</span> tree</span>)</span></span></code></pre>Type soundness</h2>
The ReScript docs state that the ReScript type system is sounder than
TypeScript’s. What does this mean in practice?</p>

Most type systems make a guess at the type of a value and show you a type in
your editor that's sometime incorrect. We don't do that.</p>
</blockquote>
Quick points:</p>

No undefined</code> or null</code>. There’s interop available, but they don’t exist in
idiomatic ReScript</li>
Types are compiler-only constructs, they won’t affect your runtime performance</li>
Type checking is way faster than tsc</code></li>
Almost no need for annotations</li>
</ul>
Why is TypeScript unsound?</h3>
TypeScript doesn’t prioritize soundness</em>, it prioritizes completeness</em> (which
is totally fine!).</p>
const</span> nums</span>:</span> number</span>[]</span> =</span> []</span></span>
const</span> n</span> =</span> nums[</span>0</span>]</span></span>
</span>
const</span> adder</span> =</span> (</span>a</span>:</span> number</span>,</span> b</span>:</span> number</span>)</span> =></span> a</span> +</span> b</span></span>
</span>
// What does this output?</span></span>
console</span>.</span>log</span>(</span>adder</span>(n</span>,</span> 2</span>))</span></span></code></pre>
playground link</em></a></p>
Meanwhile, ReScript will actually throw a compiler error when indexing an array,
since there may not be an item at that index.</p>
open</span> Belt</span></span>
</span>
// </span>Note</span>: no annotations needed</span></span>
let</span> nums</span> =</span> []</span></span>
let</span> n</span> =</span> nums</span>[</span>0</span>]</span></span>
</span>
let</span> adder</span> =</span> (</span>a</span>,</span> b</span>)</span> =></span> a</span> +</span> b</span></span>
</span>
adder</span>(</span>n</span>,</span> 2</span>)</span></span>
//</span> Compiler</span> error</span>!</span></span>
//</span> [E] Line</span> 7</span>,</span> column</span> 6</span>:</span></span>
//</span></span>
//</span> This</span> has</span> type</span>:</span> option</span><</span>'</span>a</span>></span></span>
//</span>   Somewhere </span>wanted</span>:</span> int</span></span></code></pre>
We can fix the compiler error by wrapping the array access with a switch</code>
statement, defaulting the value to 0</code>.</p>
open</span> Belt</span></span>
</span>
let</span> nums</span> =</span> []</span></span>
let</span> n</span> =</span> switch nums</span>[</span>0</span>] {</span></span>
| Some(</span>v</span>) </span>=</span>> v</span></span>
| None => 0</span></span>
}</span></span>
</span>
let</span> adder</span> =</span> (</span>a</span>:</span> int</span>,</span> b</span>:</span> int</span>)</span> =></span> a</span> +</span> b</span></span>
</span>
adder</span>(</span>n</span>,</span> 2</span>)</span></span></code></pre>
This is just one of many examples of TypeScript’s unsoundness. Here’s another:</p>
const</span> a</span>:</span> Record</span><</span>string</span>,</span> string</span>></span> =</span> {</span></span>
  id</span>:</span> 'd4346fda-7480-4e47-a51a-786a431b3272'</span>,</span></span>
}</span></span>
</span>
const</span> fn</span> =</span> (</span>t</span>:</span> {</span> id</span>?:</span> number</span> })</span> =></span> {</span></span>
  // Runtime type is `string`</span></span>
  // Type is `number | undefined` ❌</span></span>
  console</span>.</span>log</span>(t</span>.</span>id)</span></span>
}</span></span>
</span>
// Expected error here but got none</span></span>
fn</span>(a)</span></span></code></pre>
playground link</a></em></p>
The ReScript version outputs a compiler error:</p>
let</span> a</span> =</span> Js</span>.</span>Dict</span>.</span>empty</span>()</span></span>
Js</span>.</span>Dict</span>.</span>set</span>(</span>a</span>, "id", "d4346fda-7480-4e47-a51a-786a431b3272"</span>)</span></span>
</span>
let</span> fn</span> =</span> (</span>t</span>:</span> Js</span>.</span>Dict</span>.</span>t</span><</span>option</span><</span>int</span>>></span>)</span> =></span> {</span></span>
  Js</span>.</span>log</span>(</span>Js</span>.</span>Dict</span>.</span>get</span>(</span>t</span>, "</span>id</span>"))</span></span>
}</span></span>
</span>
//</span> This</span> has</span> type</span>:</span> Js</span>.</span>Dict</span>.</span>t</span><</span>string</span>></span> (</span>defined as </span>Js_dict</span>.</span>t</span><</span>string</span>></span>)</span></span>
//  Somewhere </span>wanted</span>:</span></span>
//</span>    Js</span>.</span>Dict</span>.</span>t</span><</span>option</span><</span>int</span>></span>></span> (</span>defined as </span>Js_dict</span>.</span>t</span><</span>option</span><</span>int</span>></span>></span>)</span></span>
//</span></span>
//  The </span>incompatible parts</span>:</span></span>
//</span>  string vs option</span><</span>int</span>></span></span>
fn</span>(</span>a</span>)</span></span></code></pre>Variant and Option</h3>
TypeScript tackles variants with string literals:</p>
type</span> Animal</span> =</span> '</span>cat</span>'</span> |</span> '</span>dog</span>'</span></span>
</span>
const</span> fn</span> =</span> (</span>animal</span>:</span> Animal</span>)</span> =></span> {</span></span>
  switch</span> (animal)</span> {</span></span>
    case</span> 'cat'</span>:</span></span>
      console</span>.</span>log</span>(</span>"I'm a cat"</span>)</span></span>
      break</span></span>
    case</span> 'dog'</span>:</span></span>
      console</span>.</span>log</span>(</span>"I'm a dog"</span>)</span></span>
      break</span></span>
  }</span></span>
}</span></span></code></pre>
Compare this to ReScript’s approach, where variants have dedicated constructors:</p>
type</span> animal</span> =</span> Dog</span> |</span> Cat</span></span>
</span>
let</span> fn</span> =</span> animal</span> =></span> {</span></span>
  switch animal</span> {</span></span>
  | Dog </span>=</span>> Js.log("I'm a dog")</span></span>
  | Cat => Js.log("I'm a cat")</span></span>
  }</span></span>
}</span></span></code></pre>
This gives ReScript variants a lot more flexibility because the constructors can
take arguments:</p>
type</span> account</span> =</span></span>
  |</span> None</span></span>
  |</span> Instagram</span>(</span>string</span>)</span></span>
  |</span> Facebook</span>(</span>string, int</span>)</span></span>
</span>
let</span> myAccount</span> =</span> Facebook</span>(</span>"Josh",</span> 26</span>)</span></span>
let</span> friendAccount</span> =</span> Instagram</span>(</span>"Jenny"</span>)</span></span>
</span>
let</span> process</span> =</span> acc</span> =></span> switch acc</span> {</span></span>
| Instagram(</span>name</span>) </span>=</span>> ...</span></span>
| Facebook(name, age) => ...</span></span>
| None => ...</span></span>
}</span></span>
</span>
process</span>(</span>myAccount</span>)</span></span></code></pre>Option</h3>
An Option is just a special type of Variant.</p>

Recall: undefined</code> and null</code> don’t exist in ReScript</li>
Potentially nonexistent values are still useful</li>
</ul>
Example:</p>
// Annotation for demonstration only</span></span>
let</span> licenseNumber</span>:</span> option<</span>int</span>></span> =</span></span>
  if</span> personHasACar</span> {</span></span>
    Some(5)</span></span>
  }</span> else</span> {</span></span>
    None</span></span>
  }</span></span></code></pre>
Use pattern matching to handle both cases:</p>
switch licenseNumber {</span></span>
| None =></span></span>
  Js.log("The person doesn't have a car")</span></span>
| Some(number) =></span></span>
  Js.log("The person's license number is " ++ Js.Int.toString(number))</span></span>
}</span></span></code></pre>Belt</h2>
The ReScript
standard library</a>.</p>

Immutable data structures</li>
Safety by default (e.g.
array access runtime safety</a>,
Belt functions never throw exceptions)</li>
Tree-shakable, good performance (citation needed)</li>
</ul>
let</span> someNumbers</span> =</span> [</span>1</span>,</span> 1</span>,</span> 4</span>,</span> 2</span>,</span> 3</span>,</span> 6</span>,</span> 3</span>,</span> 4</span>,</span> 2</span>]</span></span>
</span>
let</span> greaterThan2UniqueAndSorted</span> =</span></span>
  someNumbers</span></span>
  -></span>Belt</span>.</span>Array</span>.</span>keep</span>(</span>x</span> =></span> x</span> ></span> 2</span>)</span></span>
  //</span> convert to </span>and</span> from</span> set</span> to </span>make values unique</span></span>
  -></span>Belt</span>.</span>Set</span>.</span>Int</span>.</span>fromArray</span></span>
  -></span>Belt</span>.</span>Set</span>.</span>Int</span>.</span>toArray</span> //</span> output is already sorted</span></span>
</span>
Js</span>.</span>log2</span>(</span>"result",</span> greaterThan2UniqueAndSorted</span>)</span></span></code></pre>
When should I use Belt?</p>

You need an API that isn’t available in regular JS</li>
You want no compromises on type safety</li>
</ul>
When should I not use Belt?</p>

You want zero-cost abstractions</li>
You want semantics similar to JS</li>
</ul>
Personally, I like to replace the JS standard library with Belt entirely using
this bsconfig</code> setting:</p>
"bsc-flags": ["-</span>open</span> Belt</span>"]</span></span></code></pre>Fibonacci demo</h2>
Setup:</p>
git clone https://github.com/rescript-lang/rescript-project-template fib-demo</span></span>
cd fib-demo</span></span>
yarn</span></span></code></pre>
Problem: f0 = 0, f1 = 1, fn = f{n-1} + f{n-2} for n > 1</code></p>
Recursive process solution</h3>
ReScript code:</p>
let</span> rec</span> fib</span> =</span> n</span> =></span> {</span></span>
  if </span>n</span> <</span>=</span> 2 {</span></span>
    1</span></span>
  }</span> else</span> {</span></span>
    fib</span>(</span>n</span> - 1) + </span>fib</span>(</span>n</span> - 2)</span></span>
  }</span></span>
}</span></span></code></pre>
JavaScript output:</p>
function</span> fib</span>(</span>n</span>) {</span></span>
  if</span> (n</span> <=</span> 2</span>)</span> {</span></span>
    return</span> 1</span></span>
  }</span> else</span> {</span></span>
    return</span> (</span>fib</span>((n</span> -</span> 1</span>)</span> |</span> 0</span>)</span> +</span> fib</span>((n</span> -</span> 2</span>)</span> |</span> 0</span>))</span> |</span> 0</span></span>
  }</span></span>
}</span></span></code></pre>Iterative process (still using recursion!) solution</h3>
ReScript code:</p>
let</span> fib</span> =</span> n</span> =></span> {</span></span>
  let rec </span>iter</span> =</span> (</span>a</span>,</span> b</span>,</span> counter</span>)</span> =></span> {</span></span>
    if </span>counter</span> =</span>= 0 {</span></span>
      b</span></span>
    }</span> else</span> {</span></span>
      iter</span>(</span>a</span> + </span>b</span>, </span>a</span>, </span>counter</span> - 1)</span></span>
    }</span></span>
  }</span></span>
</span>
  iter</span>(</span>1</span>,</span> 0</span>,</span> n</span>)</span></span>
}</span></span></code></pre>
JavaScript output:</p>
function</span> fib</span>(</span>n</span>) {</span></span>
  var</span> _a</span> =</span> 1</span></span>
  var</span> _b</span> =</span> 0</span></span>
  var</span> _counter</span> =</span> n</span></span>
  while</span> (</span>true</span>)</span> {</span></span>
    var</span> counter</span> =</span> _counter</span></span>
    var</span> b</span> =</span> _b</span></span>
    var</span> a</span> =</span> _a</span></span>
    if</span> (counter</span> ===</span> 0</span>)</span> {</span></span>
      return</span> b</span></span>
    }</span></span>
    _counter</span> =</span> (counter</span> -</span> 1</span>)</span> |</span> 0</span></span>
    _b</span> =</span> a</span></span>
    _a</span> =</span> (a</span> +</span> b)</span> |</span> 0</span></span>
    continue</span></span>
  }</span></span>
}</span></span></code></pre>
Note that the iterative solution introduces tail call optimization!</p>
React demo</h2>
Setup:</p>
npx create-react-app a-todo-list</span></span></code></pre>
Then follow the rescript-react
installation instructions</a></p>
Full project:
https://github.com/mgmarlow/rescript-cra</a></p>
Should I use ReScript?</h2>
Yes if...</p>

Your code doesn’t rely too heavily on third-party JS packages</li>
You want total type correctness</li>
You want compiler-defined performance optimizations</li>
You’re using React</li>
</ul>
References</h2>

BuckleScript & Reason Rebranding</a></li>
State of Reason in 2021</a></li>
ReScript official roadmap</a></li>
Roles for Belt, Js, and Pervasives in ReScript</a></li>
</ul>


Reading: Intro to Haiku
2022-01-08T00:00:00+00:00
Talking about Intro to Haiku</em> by Harold Henderson.</p>
The 17 syllable (5-7-5) structure of Japanese haiku doesn't necessarily
translate well into English, so Henderson prefers English haiku in the realm of
12-15. There are a few interesting reasons for this difference:</p>

There are no articles (the, a, an, etc.) and very few pronouns in Japanese.</li>
Punctuation is replaced by cut-words that have no translatable meaning but
increase syllable count.</li>
Different grammar rules contribute to a very different sentence structure.</li>
</ul>
That said, even with a shorter syllable count, short-long-short is still the
recommended structure for haiku. The general guidelines for writing haiku are as
follows.</p>

Follow a short-long-short rhythm with fewer than 17 syllables (often 12-15).</li>
Include a single break in meaning that compares two adjacent, though
dissimilar ideas.</li>
Reflect on nature or one of the four seasons.</li>
Try to share an experience of awareness with the reader.</li>
</ul>
Selected poems</h2>
(translations by Harold Henderson</em>)</p>
Bashō</h3>
On a journey, ill,</span></span>
  and over fields all withered,</span></span>
    dreams go wandering still.</span></span></code></pre>A lightning gleam:</span></span>
  into darkness travels</span></span>
    a night heron’s scream.</span></span></code></pre>Issa</h3>
A new year starting, but—</span></span>
  it’s still just as it stands here,</span></span>
    this ramshackle hut!</span></span></code></pre>Shiki</h3>
The mists come;</span></span>
  the mountains fade and vanish;</span></span>
    the tower stands alone.</span></span></code></pre>Night; and once again,</span></span>
  the while I wait for you,</span></span>
    cold wind turns into rain.</span></span></code></pre>Icy the moonshine:</span></span>
  shadow of a tombstone,</span></span>
    shadow of a pine.</span></span></code></pre>


Best of 2021
2022-01-02T00:00:00+00:00
Inspired by
Fogus's post</a>
of the same name, this is a list of my favorite things of 2021. I'm focusing on
projects, ideas, and media that I found especially noteworthy throughout the
year (huge bias towards the latter half because my memory is getting old).</p>
Programming languages learned</h2>


ReScript</a>: a recent rediscovery, jumping off my
short-lived adventure with Scheme earlier this year. I have been on a
functional programming kick and ReScript has provided just enough functional
delight while maintaining familiar JavaScript underpinnings. I think this tool
has a lot of potential, but it remains a niche project with some hindering
design quirks.</p>
</li>

Scheme (Racket</a>): more of a dabble and less of a
learn, I tried to work through
SICP</a> this year
and put together some
neat solutions</a> to the text's
exhaustive exercises. Although I only made it through the first chapter,
principles from that reading have invaded my mind and I continue to think
about them even half a year later.</p>
</li>

Haxe</a>: a fantastic language for making games that will be
familiar to any JavaScript developer. I'm especially fond of
HaxeFlixel</a>, a batteries-included framework for 2D
games.</p>
</li>
</ul>
Some books I read this year</h2>


Franny & Zooey</a></em>.
A recommendation from a friend that ended up being one of my favorite books
ever written. The narrative is existential with a spiritual twist, a
coming-of-age novella with well-written characters exploring a complex family
dynamic. This book drew me in with unexpected force, especially given that the
entire novella is little more than four conversations.</p>
</li>

If on a Winter's Night a Traveler</a></em>.
I purchased this novel on a lark and was both surprised and amazed by its
premise. A book about reading a book, Calvino blends together several
narrative styles, settings, and plot devices into one cohesive experience. A
pleasant read that offers more insight than appears on the surface.</p>
</li>

Piranesi</a></em>.
This novel comes highly recommended and I think it deserves the praise. It's a
joyful read with just enough barbs to keep you thinking about it after
finishing. In particular, I was drawn to the classical motifs of its setting.</p>
</li>

Domain-driven Design</a></em>.
A seminal computer science tome that was an absolute chore to power through.
That said, I don't think I've ever cited a text more often in my day-to-day
work. Eric Evans has achieved something remarkable with the thoroughness of
this work, and although it is far from an easy read, it will be remembered for
a long time coming.</p>
</li>

Kraching</a></em> (A
Thousand Thousand Islands). Zedeck Siew remains my favorite writer in the
TTRPG space, creating unique and evocative settings with a prose that is more
akin to poetry.</p>
</li>

Intro to Haiku</a></em>.
Poems are a great cure for ennui, and haiku in particular is a very
approachable form. Once you step away from the haiku format you were taught as
a kid and learn some fundamentals from the Japanese greats, haiku takes on
another form. A beautiful way of sharing experiences with others.</p>
</li>
</ul>

On a journey, ill,</p>
and over fields all withered,</p>
dreams go wandering still.</p>
–Basho</p>
</blockquote>
Games I played this year</h2>


Riichi Mahjong: I stumbled into Mahjong in a huge way this year with the help
of my friend, Sam. Once I got a handle on the rules I was wholeheartedly
consumed. The blend of quick decision making and probabilistic reasoning is an
addictive dopamine hit that my brain cannot resist. I even read through Daina
Chiba's great introductory
strategy book</a>.</p>
</li>

Psychonauts 2: the first Psychonauts occupies a special place in my heart, but
I remained thoroughly skeptical of this long-awaited sequel. That said, I was
relieved and impressed to discover that the game is an improvement in every
respect to the original, and provides a uniquely introspective narrative in a
time of wavering psychological health.</p>
</li>

Myst, Quern, and Obduction: my partner and I have been on a puzzle-solving
adventure kick. While these games don't hold a candle to our favorites, The
Witness or Outer Wilds, playing these games together remotely with Milanote
open in a separate tab is a constant joy. We've learned that ending a session
with an "immediate next steps" list makes it that much easier to resume after
a hiatus.</p>
</li>
</ul>
Games shipped</h2>
Shout-out to Nick Preheim</a>, who
helped me ship two games this year with his art and collaboration.</p>


Stonk Market Simulator</a>: a
game jam submission. Inspired by some of the nonsense taking place on
r/wallstreetbets earlier in the year.</p>
</li>

Solarflare</a>: less humor and more game,
another jam submission that tries to mimic classic shmups.</p>
</li>

Noumena</a>: my first go at TTRPG writing, in
the form of a solo journaling game inspired by the bums and poets of the beat
generation. I'm quite proud of this project and am invigorated to work on more
TTRPG projects in the future.</p>
</li>
</ul>
Albums listened to</h2>
This year was full of post-punk bangers.</p>

For the First Time</em> by Black Country, New Road</li>
Cavalcade</em> by Black Midi</li>
Entertainment, Death</em> by Spirit of the Beehive</li>
Bright Green Field</em> by Squid</li>
L.W.</em> by King Gizzard & the Wizard Lizard</li>
</ul>
Hobbies old and new</h2>


Warhammer: lockdown inspired the need for creative entertainment that did not
involve a computer. Haven't played an actual game yet, but I've already sunk
too many hours into painting minis and reading lore.</p>
</li>

GMing TTRPGs: current system of choice is Pathfinder 2e. I've been a player
for a few years now, but this year I started my first full-length campaign.</p>
</li>

Bouldering: unfortunately at the start of this year I
ruptured a pulley</a>
in my finger, rendering me unable to climb seriously for most of the year.</p>
</li>
</ul>
Programming notes</h2>
Micro frontends</h3>
As JavaScript apps forever grow in size and complexity, I think there remains
room for a microservice-like solution for frontend development. The ideas
proposed in the foundational ThoughtWorks piece remain a good introduction to
the theory, although I think the specific implementation outlined in the article
is a bit dated</a>.</p>
Four years working with Ruby</h3>
Ever since I wanted to program professionally I wanted to work in Ruby, as
Practical OOD</em> and Eloquent Ruby</em> shaped my early programming journey. That's
why it's particularly surreal that I stumbled into a Ruby gig after years of
working with C# and JavaScript.</p>
Ruby has been an absolute pleasure to work with over the last four years, and
I've learned a ton through my interactions with other Rubyists. I think the
community behind the language has something unique, a special friendliness and
freedom of exploration pioneered by open source contributors like
_why the lucky stiff</a>.</p>
Rails is another story. I maintain that Rails is a phenomenal piece of software,
but more often than not its flexibility and rapid capabilities are abused in
ways that create unmaintainable code. Projects are cobbled together quickly for
first-to-market advantage, eschewing any and all upfront design.</p>
There's a lot of bad Rails code out there in the world, but I'll still enjoy
cleaning up my small part of it for the next long while.</p>
SICP and recursive process vs. recursive procedure</h3>
One revelation I experienced while reading SICP was the nuance between recursive
processes and recursive procedures, or, that recursive procedures can be written
iteratively. This is a topic worthy of its own post, but to summarize, check out
this code example that compares
two fibonacci implementations</a>.</p>
Lessons learned</h2>
Embracing chaotic notes</h3>
I've ditched my Zettelkasten and Notion setup in favor of something simpler. The
theory behind the Zettelkasten</a> is
fantastic, but I've found it creatively stifling. I worry too much about the
organization of my notes, spending more time architecting pages and browsing
templates than actually writing.</p>
I've switched back to writing notes by hand in
Field Notes</a> or using dead-simple apps like Apple
Notes. The low barrier-to-entry to get note on page means the important part of
expressing an idea can be done quickly with no distraction.</p>
I've learned that I enjoy the process of taking notes more than actually using
the notes as a reference. Only on rare occasions do I actually hunt down my past
notes for a future idea. I write notes for the enjoyment, the process of taking
any idea that flits into my head and establishing it in ink.</p>


Statues of Piranesi
2021-12-19T00:00:00+00:00
After finishing
Piranesi</a></em>,
my thoughts and attention have been captured by the influences of its setting.
In particular, the marble statues that fill Piranesi’s residence, the House.</p>
The classical influence on Piranesi is just shy of being explicitly stated—not
only is the House is referred to as “the Labyrinth” by several characters, but
its entrance hall is flanked by statues of Minotaurs. Both of these details
suggest a relationship to the heroic tale of Theseus.</p>
The story begins with Poseidon punishing the greedy King of Crete, King Minos,
by enticing his wife with a beautiful bull. The end result of that relationship
is the half-man, half-bull offspring known as the Minotaur.</p>
Ashamed of this creature who had a penchant for devouring human beings, King
Minos hires Daedalus to construct the Labyrinth that serves as the Minotaur’s
prison. What follows is a war with Athens, the ritual sacrificing of fourteen
children every year, and the slaying of the Minotaur thanks Athen’s favorite
tag-team duo Theseus and Ariadne.</p>
With this general connection to Greek myth established, I can now turn to the
statues that continue the trend.</p>
The statue of the Woman with the beehive is perhaps my favorite. After reading
Piranesi’s description, my mind immediately turned towards one of the most
famous similes in the Aeneid,</p>

Like bees in spring across the blossoming land, Busy beneath the sun, leading
their offspring, Full grown now, from the hive, or loading cells Until they
swell with honey and sweet nectar, Or taking shipments in, or lining up To
guard the fodder from the lazy drones; The teeming work breathes thyme and
fragrant honey. (Aeneid I.430-6)</p>
</blockquote>
Virgil describes the industriousness of Carthage, comparing its cohesive
citizens to that of bees in a hive. The simile is especially apt because bees
work in service to their queen as the citizens of Carthage work in service to
Queen Dido.</p>
In Piranesi, the protagonist gives a strikingly similar interpretation of the
statue.</p>

It occurred to me–it was no more than an idle thought – that both these
Statues might be said to represent Industriousness. The Gardener is old and
bent, and yet he digs faithfully in his garden. The Woman is pursuing her
profession of beekeeping and the Beehive that she carries is full of bees who
are also patiently carrying out their tasks. (Piranesi p. 40)</p>
</blockquote>
Since the book does not shy away from its references to Greek and Roman
mythology, I think there’s a strong case for the statue as a direct reference to
Dido and the people of Carthage.</p>
Another statue of interest is Piranesi’s personal favorite, that of the Faun
holding his finger to his lips.</p>
By appearance alone, this could easily be a reference to Pan. More
interestingly, perhaps, is that Pan is described as a master in impromptus
music, a style of free-form musical composition. Although Piranesi is only
briefly a musician (via a hand-crafted flute), he seems to embody the impromptus
ideology in his everyday existence, coexisting with the House without
questioning its meaning.</p>

I realised that the search for the Knowledge has encouraged us to think of the
House as if it were a sort of riddle to be unravelled, a text to be
interpreted, and that if ever we discover the Knowledge, then it will be as if
the Value has been wrested from the House and all that remains will be mere
scenery. (Piranesi p. 60)</p>
</blockquote>
Piranesi is resolute in his goal of living in the moment, acting under the
guiding principles of the impromptus. When he comes to this realization, his
character is cemented as a foil to the Other.</p>
I don’t think every statue in the story necessarily relates to Greek or Roman
mythology. Rather, I think they generally pull from powerful symbols or themes
that are recognizable and interpretable by people in general, archetypes that
Joseph Campbell would’ve described as universal to the human experience.</p>
Following this interpretation, the House is sort of a collective unconscious,
filled with archetypes common to the human experience.</p>
The Labyrinth is the human mind, and Piranesi its chronicler.</p>


Revisiting ReScript
2021-12-11T00:00:00+00:00
When I first started looking at ReScript two years ago it was a project under
another name: Reason. Derived from OCaml, Reason promised type safe code and
powerful functional primitives without ditching the JavaScript ecosystem. It was
created by Jordan Walke, the creator of React, and boasted adoption in
Facebook's core messaging product,
Facebook Messenger</a>.</p>
However, Reason was divided between multiple teams with different
responsibilities. Reason itself was a JavaScript-friendly syntax layer sitting
in front of OCaml. The actual compiler, BuckleScript, was maintained by a
separate team with a separate history. The development lifecycles for these two
projects led to an awkward fragmentation of tooling, documentation, and
community.</p>
Luckily, BuckleScript and Reason are now united under a common name,
ReScript</a>. This
change has brought about a fair deal of controversy, as it poses to further
divide an already niche community with yet another syntax layer.</p>
That aside, the project feels like it's in a much healthier state than two years
ago. Unifying the documentation under a
single domain</a> is a non-trivial change that makes
it easier to acclimate to the ecosystem. In addition, the new
VSCode extension</a>
goes a long way to make the experience feel at least comparable to TypeScript.</p>
Now's the right time to get into ReScript and start exploring some of its killer
features:</p>

Great type inference with basically no need for annotations.</li>
No undefined or null. Instead, a robust
option type</a>.</li>
Pattern matching, automatic currying, and other paradigms associated with
functional programming languages.</li>
Designed for JavaScript interop, making it easy to integrate into existing
codebases.</li>
</ul>
I want to bring particular attention to the last bullet point since it's the
most important when discussing real-world codebases. A new toolchain doesn't
amount to much if it doesn't easily integrate with existing systems.</p>
To test this, I created a prototype with create-react-app and Tailwind (full
code available here</a>).</p>
The whole toolchain integrates pretty seamlessly with Webpack, but in retrospect
that's not too surprising because the JavaScript output from ReScript is really
clean. Each file is compiled into something that almost resembles code written
by a human.</p>
I was surprised by the guidance to
keep the compiled JavaScript files version-controlled</a>
alongside their ReScript counterparts. Something about committing compiled
output feels fundamentally wrong, even if one of the core contributors of
ReScript is arguing for it. Either way, the implementor can choose which style
they prefer.</p>
My only real gripe with ReScript is the advertisement that it's "the fastest
build system on the web". Now, how can that be possible when
ESBuild</a> exists?</p>


What happened to proper tail calls in JavaScript?
2021-03-27T00:00:00+00:00
Proper tail calls (PTC) is a programming language feature that enables
memory-efficient recursive algorithms. I'm not going to belabor the details of
proper tail calls or how it pertains to JavaScript, as
Dr. Axel's article</a>
already offers those explanations. Instead, I'm going to discuss the evolution
of the feature in JavaScript since its genesis in ECMAScript 2015.</p>
Despite its inclusion in the
2015 language specification</a>,
PTC is currently only supported by Safari. It is astounding that six years after
the formal submission of the standard, only one major browser offers any kind of
support.</p>

JavaScriptCore (Safari) ✅
(read all about it</a>)</li>
V8 (Chrome, Edge, Opera) ❌</li>
SpiderMonkey (Firefox) ❌</li>
Carakan (Opera) ❌</li>
</ul>
Why are browser vendors ignoring PTC? V8 chalks it up to two main reasons:</p>


It makes it more difficult to understand during debugging how execution
arrived at a certain point since the stack contains discontinuities, and</li>
error.stack</a>
contains less information about execution flow which may break telemetry
software that collects and analyzes client-side errors.</li>
</ol>
</blockquote>
It's worth noting that V8 fully implemented proper tail calls but ultimately
removed them, according to their
blog post</a> from 2016.
To help outline a solution to the aforementioned problems, V8 created a proposal
for an alternative approach called
syntactic tail calls</a> (STC). As
the name suggests, it proposes a syntax for opting in to PTC, rather than
supporting implicit opt-in.</p>
The STC proposal is
hotly</a>
debated</a>. The arguments
tend to trend in one of two directions:</p>


STC is unnecessary and defeats the purpose of PTC. Safari has implemented PTC
since 2016 without issue, so most fears of implicit behavior are unwarranted.</p>
</li>

STC is important to guard against potential problems with implicit behavior.
As V8 summarized, PTC introduces educational concerns across developers and
debugging concerns across implementations.</p>
</li>
</ol>
TC39 editors express a general hesitancy towards STC and a lack of faith for
broader PTC adoption that is
well-summarized</a>
by contributor Jordan Harband. Since 2017, the proposal has been
marked inactive</a>.
There is no indication that the proposal will be revived or that PTC adoption
will move in a forward direction.</p>
All that drama aside, browser implementations are only one part of the story.
What about Babel?</p>
Similar to V8, Babel implemented and subsequently reverted both
proper tail calls</a> and
tail call optimization</a>. The reference
to PTC in the
ES2015 documentation</a> states,</p>

Temporarily Removed in Babel 6</p>
Only explicit self referencing tail recursion was supported due to the
complexity and performance impact of supporting tail calls globally. Removed
due to other bugs and will be re-implemented.</p>
</blockquote>
When will tail calls be re-implemented? Not in Babel 7, that's for sure. The
uncertain fate of PTC requires JavaScript developers to reach for alternative
approaches.</p>
Kyle Simpson describes the use of a trampoline, a helper function that rewrites
tail-recursive functions with while loops. His methodology is detailed in
Chapter 8 of Functional-Light JavaScript</a>.</p>
Those looking for npm packages have a couple of options:</p>


fext</a>, a library that enables optimizations by
wrapping functions with its API.</p>
</li>

babel-plugin-tailcall-optimization</a>,
a plugin that automatically rewrites tail-recursive functions with
trampolines.</p>
</li>
</ul>
PS, a final clarification for the pedantic:</p>
The terminology of proper tail calls (PTC) and tail call optimization (TCO) is
often conflated. Here's the difference between the two:</p>


proper tail calls</strong>: functions called in the tail position reuse the current
stack frame, preventing the creation of additional stack frames that cause
space inefficiency.</p>
</li>

tail call optimization</strong>: rewrites a recursive function into an iterative
one, usually by calling goto.</p>
</li>
</ul>
The difference between the two is nuanced, though often mentioned in spicy
Github threads. PTC only deals with stack manipulation, while TCO rewrites a
recursive function as an iterative function. Find more details from Ward
Cunningham's tail call optimization</a>
wiki.</p>


Game design is immaterial
2021-03-20T00:00:00+00:00
Reading
Elements of Game Design</a>
planted a splinter in my brain that I cannot stop fiddling with. On page 8, when
discussing the game designer's role,</p>

Designer's intentions are immaterial, save for how they turned out in the
implementation.</p>
</blockquote>
The implication is that design vanishes when the game handed off to the player.
The player doesn't directly interact with game design. Instead, the player
experiences with their senses: holding the controller, watching pixels on the
screen, jamming to a chiptune beat.</p>
I find this statement ultimately unsatisfying.</p>
There's something in the design itself that lingers; something that continues to
pull at the player's expectations long after they've dropped the game.</p>
Take, for example, my love of
DOOM</a>. The fluidity of
arena-based combat subverted my childhood understanding of first-person shooters
(FPS). Now every FPS I play is subject to lofty expectations stemmed from my
enjoyment of DOOM.</p>
Some games play with expectations more fundamentally within their design.
Antichamber</a> utilizes
non-Euclidean space to cultivate mind-bending puzzles. The entire experience
hinges on player assumptions that game worlds are reflections of the real world,
and thereby follow the same rules and physics.</p>
This concept of prior experience is referred to in philosophy as
a priori</a>, literally
"from the former". Kant suggests, as quoted by the
Standford Encyclopedia of Philosophy</a>
(emphasis mine):</p>

[T]he objective validity of the categories, as a priori concepts, rests on the
facts that through them alone is experience possible (as far as the form of
thinking is concerned). For they then are related necessarily and a priori to
objects of experience, since only by means of them can any object of
experience be thought at all</strong>.</p>
</blockquote>
Kant defines a priori concepts as conditions of experience. Every experience I
perceive is rooted in the existence of fundamental concepts that I do not
directly perceive. These fundamental concepts must exist in order for the
experience to exist.</p>
Applied to games, player experience rests upon an a priori foundation of game
design. Player's do not interact with game design directly, but the design must
exist in order for the game to exist. Following this transcendental view, the
design exists even though it is unknowable by the player.</p>
What I found while venturing into all of this theory is that, from a player's
perspective, "unknowable" is a better definition for game design than
"immaterial".</p>
Although a player only interacts with the sensory aspects of games, the design
doesn't vanish from the experience. It's still there, built upon as a foundation
of a priori concepts, affecting the player's overall enjoyment of the game.</p>
The design, the unknown something, is carried with the player separate from the
game. Players accumulate a repository of design concepts throughout their
lifetime that ultimately affect they way they perceive and experience games.</p>


Creative-consumptive entertainment
2021-03-17T00:00:00+00:00
Since discovering
a discussion on Hacker News</a>
about the perils of consumptive entertainment, I doubt my self-worth every time
I sit down to play a video game. I could be doing something productive. Instead,
I stare at my Steam library, guilt and indecision cycling endlessly.</p>
Forms of "consumptive" entertainment are regularly
looked down upon</a>, often cited
as necessary evils</a>. The modern
adage goes, "create more, consume less". Time spent consuming is time better
spent creating, writers opine.</p>
When most people think about entertainment, they tend to group it into one of
two forms:</p>

consumptive</strong>: no input needed from the participant</li>
creative</strong>: consists almost entirely of participant input</li>
</ul>
Consumptive entertainment is watching Game of Thrones, scrolling Instagram, or
playing Loop Hero</a>. Whether or not the participant
chooses to interact doesn't change the output of the entertainment. Footage
continues to roll, scrolling remains infinite, and video games play themselves
into eternity.</p>
Creative entertainment is painting a landscape, recording a song, writing a
program. Without the participant actively engaging, nothing is produced.</p>
These two forms of entertainment are often described as being at odds.
Binge-watching is bad, but an occasional episode is a reprieve from a hard day's
work. Creativity is good, particularly if years of toil and anguish are
reflected in the final piece.</p>
I propose a new classification of entertainment, one that draws the line between
consumptive and creative.</p>
Creative-consumptive entertainment is consumptive entertainment that is actively
engaged with.</p>
Reading a book with pencil in hand is a great example. Reading is a consumptive
act; both the words and the ideas are static when absorbed in a passive reading
session. However, read with a pencil and you'll discover yourself underlining
passages, writing small notes, and engaging with the words in a new, creative
way.</p>
This method of close reading is creative-consumptive because the ideas from the
page are re-interpreted by the reader, adding new meaning and texture.</p>
What's most interesting about creative-consumptive entertainment is the ability
for any consumptive form to transform into a creative form by applying
attention. The principles behind close reading carryover to television, movies,
video games, and so on. All it requires is active participation.</p>
I hope that this idea of creative-consumptive entertainment assuages the guilt
that modernity attaches to consumption. Active participation can transform
consumptive entertainment into something that is both more fulfilling and
engaging.</p>

mgmarlow.com - List of blog posts

Revisiting My Reading List

PGP and Real-World Cryptography

Refreshed cryptography</h2> It's probably clear from the previous section that the two new standards for PGP address concerns related to obsolete cryptography. Once again citing Daniel Huigens,</p>

Email Encryption with Sequoia PGP and Thunderbird

Coding with Agents; Managers and Builders

Prototyping a Chess Puzzle Game

Flux architecture for snabbdom</h3> Zooming out a bit, it's important to note that snabbdom is just a VDOM library. It does not prescribe a technique for managing state in your application or a philosophy around triggering re-renders. That's the realm of a framework.</p>

Guide to Cryptic Crosswords

Why React Matters

A Thorough Look into RBS for Rails

RBS tools</h2> When working with RBS in a Rails codebase, you will make ample use of the following tools:</p>

Adding RBS to a new Rails app</h2> From a clean slate:</p>

Deno's stdlib is Available Outside Deno

August Was a Great Month for Puzzles

New Emacs Package: Helix Mode

Action Cable + React

Kafka on the Shore is My Favorite Murakami Novel

How I Organize Email with HEY

Visualizing Bracket City Puzzles

How it works</h2> I had a couple of realizations while working on this little project.</p>

Onboarding a new Mac

Ruby and RSS feeds

Reminiscing on Flow

LSP, tooling, and the rise of VSCode</h2> In the early days, the Flow language server was on par with TypeScript's. Both tools were newly emerging and often ran into issues that required restarting the language server to re-index your codebase.</p>

Zod refinements are complicated

Modularizing Start Emacs

Async IO in Emacs

Pulling Puzzles from Lichess

Logseq Has Perfected Note Organization

Paper Puzzle Remixes

Best of 2024

Automating Quick Notes with iOS Shortcuts

Solving Puzzles by Making Puzzles

The Most Common React Mistake

Type predicates to avoid casting

Data migrations with data-migrate

Cool Rails concerns

Why I Still Use Apple Notes

Exploring the Writebook Source Code

Pages that render markdown</h2> When it comes to the textual content of books created with Writebook, everything boils down to the Page</code> model and it's fancy has_markdown :body</code> invocation:</p>

HEY to Fastmail and Back Again

Crafting Interpreters, Ruby Style

New stuff in Emacs 30

use-package version control support</h2> You can now install packages directly from version-controlled repositories (for those packages that aren't yet in ELPA, Non-GNU ELPA or MELPA).</p> For example:</p>

New customizations</h2> Show the current project (via project.el</code>) in your modeline with project-mode-line</code>.</p> </li> Add right-aligned modeline elements via mode-line-format-right-align</code>.</p> </li>

Read the full details</h2> That wraps up my highlights. There's a ton more stuff included in Emacs 30.1 so I encourage you to check it out the NEWS yourself</a>.</p> PS. Interested in trying out Emacs but don't know where to start? Check out my MIT-licensed configuration guide: Start Emacs</a>.</p>

Recently

Markdown Rendering with Awk

Styling for HTML exports</h2> The last piece of this Markdown renderer is adding the boilerplate HTML that wraps our document:</p>

DM Tools with Awk

A Few Months with Kagi

My Year in Reading

How to Install React

Hypermedia and Hyperbole

Recently

Deno + Tree Sitter + Emacs

Building a Compiler for My Static Site Generator

Building the compiler</h2> Orgify's compiler has three phases: tokenization, parsing, and code generation (although the last two steps are actually performed at the same time).</p>

Parsing and code generation</h3> The next step in compilation feeds these tokens to the parser. The parser runs through the list of tokens and gives them structure, appending them as leaves and branches to an abstract syntax tree (AST).</p>

Evaluating Emacs Lisp expressions</h4> Given that the parser generates quoted Emacs Lisp code, how does the compiler actually evaluate it? With eval</code>.</p>

Small Weekend Projects

Building a Flymake Backend for Clippy

Read the full details</h2>
That wraps up my highlights. There's a ton more stuff included in Emacs 30.1 so I encourage you to check it out the NEWS yourself</a>.</p>
PS. Interested in trying out Emacs but don't know where to start? Check out my MIT-licensed configuration guide: Start Emacs</a>.</p>

Building the compiler</h2>
Orgify's compiler has three phases: tokenization, parsing, and code generation (although the last two steps are actually performed at the same time).</p>