clarity's wiki


Probably computers were a mistake. But here we are.


Site Generator Notate Sword Language for Document Layout Clairth


Forth is a procedural, concatenative, stack-oriented programming language and interactive development environment designed by Charles H. "Chuck" Moore and first used by other programmers in 1970.


Forth is my current programming language obsession these days. I'm still new to it but am getting rapidly addicted to the power.


Unix Utilities Email


When I write system-level code these days it usually tends to be in Zig. I'm not married to the language but I've gotten comfortable working in it and appreciate the overall laid-back & friendly vibe of the community.

The Zig Language home page


Gemini is a smaller and kinder way of sharing documents over the internet.


Plan 9

Plan 9 is not a product, it is an experimental investigation into a different way of computing. The developers started from several basic assumptions: that CPUs are very cheap but that we don't really know how to combine them effectively; that good networking is very important; that an intelligent user interface is a Right Decision; that existing systems are not the correct way to do things, and in particular that today's workstations are not the way to go.

Devine Lu Linvega on Plan 9

These lecture notes use Plan 9 from Bell Labs to teach a first (practical!) course on operating systems. The system is easy to use for programmers, and is an excellent example of high-quality system designand software development. Studying its code reveals how simplicity can be more effective than contortions made by other systems.

Using Plan 9 from Bell Labs, by Francisco J Ballesteros


Uxn is a little forth machine with 32 instructions. It was designed with an implementation-first mindset with the goal of targeting salvaged computers, the distribution of Uxn projects is akin to sharing game roms for any classic console emulator.

About Uxn Uxn Tutorial

I'm making a little game in Uxn to explore how it feels:


Interesting things

Ideas & Experiments

Data-Oriented Design Against Recognition

For some time now I've been telling people about a little hack I use for understanding strange codebases. When I am interested in learning about a new codebase, I skim its git log until I find a tantalizing tag or commit message, like say "version 1". Invariably version 1 is far simpler than the current version. The core use cases haven't yet been swamped by an avalanche of features and exceptions. The skeleton of the architecture is more apparent. So I focus on this snapshot, and learn all I can. Once I understand the skeleton I can play changes forward and watch the codebase fill out in a controlled manner.

But relying on the log for this information is not ideal, because the log is immutable. Often a codebase might have had a major reorg around version 3, so that reading version 1 ends up being misleading, doing more harm than good. My new organization lays out this time axis explicitly in a coherent way, and makes it available to change. The sequence of features is available to be cleaned up as the architecture changes and the codebase evolves.

A new way to organize programs

LineDrive was developed by Maneesh Agrawala, Chris Stolte, and Christian Chabot at Stanford University, and they describe their system in a 2001 paper if you’re interested in the details. What is most interesting to me is the creators’ inspiration for LineDrive: hand-drawn route maps. While most online mapping services were, and still are, patterned after paper road atlases, LineDrive was designed to look like what you might quickly sketch on a napkin.

Remembering LineDrive

[Imp is a] live environment for working with structured data across multiple devices, blurring the lines between database and programming language.


Names must be human-readable in order to be widely used. Unfortunately, while DIDs and Tor .onion addresses are decentralized and globally unique, they are not human readable. How can we build user interfaces that real users might actually use? In this paper we provide an overview of petname systems, a way of mapping human readable names to cryptographically secure names.

Petnames: A humane approach to secure, decentralized naming

GNU Emacs / N Λ N O is a set of configuration files for GNU Emacs such as to provide a nice and consistent look and feel. It is based on design principles I described in the article "On the design of text Editors" that is available on arXiv.

Nano Emacs On the design of text Editors

Uiua (wee-wuh) is a general purpose, stack-based, array-oriented programming language with a focus on simplicity, beauty, and tacit code. Uiua lets you write code that is as short as possible while remaining readable, so you can focus on problems rather than ceremony. The language is not yet stable, as its design space is still being explored. However, it is already quite powerful and fun to use!



Starting Forth

There is a playful way to study the architecture of computers of the past. Find a piece of software you know well and try to find out how it was ported to these machines you don't.

A good choice would be DOOM. id Software's 1994 mega-hit has been ported to everything. It is designed around a core with no layering violations. It is usually easy to find and read the implementation of its six I/O sub-systems.

An other choice would be Eric Chahi's 1991 critically acclaimed" title "Another World", better known in North America as "Out Of This World" which also happens to be ubiquitous. I would argue it is in fact more interesting to study than DOOM because of its polygon based graphics which are suitable to wild optimizations. In some cases, clever tricks allowed Another World to run on hardware built up to five years prior to the game release.

The polygons of Another World

So you want to write a Lisp interpreter? Welcome!

The goal of the Make-A-Lisp project is to make it easy to write your own Lisp interpreter without sacrificing those many "Aha!" moments that come from ascending the McCarthy mountain. When you reach the peak of this particular mountain, you will have an interpreter for the mal Lisp language that is powerful enough to be self-hosting, meaning it will be able to run a mal interpreter written in mal itself.

The Make-A-Lisp Process

The title of the course is “A modular approach to audio programming”. I know it’s silly, but it pretty much describes the goal of each lecture—we try to understand the complex theory of digital audio as a progression of independent minimal working examples. Instead of building a monolithic application, we write multiple small, standalone programs in C that can possibly interact with each other.

μ, A modular approach to audio programming

Computer people are fine human beings, but they do a lot of harm in the ways they "help" other people with their computer problems. Now that we're trying to get everyone online, I thought it might be helpful to write down everything I've been taught about helping people use computers.

How to help someone use a computer

This is a book on the functional paradigm in general. We'll use the world's most popular functional programming language: JavaScript.

Professor Frisby's Mostly Adequate Guide to Functional Programming

You come upon a function argument at a fork in the road. If it takes the left road, it’ll evaluate itself and then be passed to its function. If it takes the right road, it’ll pass itself to the function to be evaluated somewhere down the road (🥁🐍). Let’s bet on which road will be faster.
Levy’s ‘99 paper Call by Push Value: A Subsuming Paradigm introduces a third option, Call-by-Push-Value (CBPV), to the CBV/CBN spectrum. ‘99 is basically the Cretaceous era if we’re releasing JavaScript frameworks, but it’s quite recent for releasing research. CBPV has just started to penetrate the zeitgeist, and it’s by far the most promising approach to calling-by.

Thunderseethe — I'm betting on Call-by-Push-Value

I’d like to design a language, more specifically implement a compiler for a programming language I’ve made up. This is not the first time I’ve wanted to do this. In fact, I’ve had the itch quite a few times before . I can’t tell you why I keep returning to this venture when I’ve failed at it so many times. What I can tell you is why I always fail. Every time I begin a sparkly new project with fresh eyes and quickly whip together a lexer.
So how do I overcome my parsing problem? I’ll simply not write a lexer or parser. I can’t get stuck writing a parser if I don’t start writing one. I can come back later and add a parser once I’ve designed more of the internals of my language. My hope is having the other steps (Type Checking, Code Generation, etc.) will provide a guiding hand for what my parser should look like when I do eventually write one. The goal of writing a parser is to produce an AST. But we don’t have to parse our AST out of text during prototyping, we can design an AST and then construct it ad hoc where we need it. Then the question is, if we’re not starting with lexing/parsing, then what step do we start with? The answer is type inference [...]

Thunderseethe — Designing a Language without a Parser

This textbook provides a gentle introduction to assembly language programming. What makes this introduction "gentle" is that it assumes the reader is already comfortable with C or C++ coding. We use this assumed knowledge to bridge backward towards the low level ISA (Instruction Set Architecture).

We drive home a very sharp point:

Assembly language is nothing to be scared of!

A Gentle Introduction to Assembly Language Programming